OpenCode AI 编程工具使用指南：从安装配置到实战技巧

（3）Arch Linux 安装

sudo pacman -S opencode
# 稳定版
paru -S opencode-bin
# AUR 最新版

（4）Windows 安装（非 WSL）

除了 WSL，还支持 Chocolatey/Scoop/NPM，任选其一：

# Chocolatey
choco install opencode
# Scoop
scoop install opencode
# NPM
npm install -g opencode-ai

注意：Windows 上通过 Bun 安装的支持目前正在开发中，暂不推荐。

（5）Docker 安装

适合不想配置环境的开发者，直接运行容器：

docker run -it --rm ghcr.io/anomalyco/opencode

3. 验证安装

安装完成后，终端输入以下命令，显示版本号即安装成功：

opencode --version

三、基础配置：API 密钥与模型对接，新手也能一步到位

安装完成后，核心配置就是对接 LLM 模型的 API 密钥，这里分新手推荐（OpenCode Zen）和进阶配置（自定义模型），新手优先用 OpenCode Zen，无需手动找第三方 API 密钥，简单快捷！

1. 新手配置：OpenCode Zen（官方精选模型）

OpenCode Zen 是官方测试验证的精选模型集合，适配编码场景，步骤如下：

1. 选择 opencode 选项，终端会提示前往授权地址：opencode.ai/auth；
2. 浏览器打开该地址，完成登录并添加账单信息（新手可体验免费额度），复制生成的 API 密钥；
3. 回到终端，粘贴 API 密钥并按回车，配置完成！

在 TUI 中输入连接命令，按回车：

/connect

终端启动 OpenCode 的 TUI 界面：

opencode

2. 进阶配置：自定义第三方模型（GPT/Claude/GLM 等）

如果想使用 GPT-4o、Claude 3、GLM-4.7 等第三方模型，只需在 /connect 命令后选择对应模型提供商，输入其官方 API 密钥即可，步骤和上述一致。

小技巧：API 密钥建议存入项目本地配置，避免全局泄露；国内开发者可优先选择 GLM-4.7、DeepSeek-V3 等国产模型，中文支持更好，访问速度更快。

四、项目初始化：让 OpenCode 读懂你的项目

配置完成后，需要先对项目进行初始化，让 OpenCode 扫描项目结构、理解编码规范，后续才能精准生成 / 修改代码，步骤超简单：

1. OpenCode 会自动扫描项目文件，在根目录生成 AGENTS.md 文件，该文件记录了项目结构、编码规范等核心信息。

输入初始化命令，按回车：

/init

启动 OpenCode：

opencode

终端导航到你的项目根目录：

cd /path/to/your/project # 替换为你的项目路径

重要提示：一定要将 AGENTS.md 提交到 Git 仓库！后续团队协作或重新使用 OpenCode 时，它能让工具快速读懂项目，无需重复扫描。

五、核心功能实战：Plan+Build 双模式，搞定 80% 开发场景

OpenCode 的核心精髓是 Plan（规划模式）+Build（构建模式）双工作流，先让 AI 出方案，再让 AI 写代码，避免直接编码导致的逻辑偏差，代码一次性通过率提升 40% 以上！同时支持直接修改、代码解释、撤销重做等基础功能，下面结合实际案例手把手教学。

核心操作：模式切换

• 按 Tab 键 可在 Plan 和 Build 模式之间切换，终端右下角会显示 模式指示器（Plan/Build）；
• Plan 模式：只读分析，不修改任何文件，仅生成自然语言实施计划；
• Build 模式：执行编码，根据 Plan 计划，自动修改 / 创建文件，实现代码落地。

实战 1：新增功能（复杂场景，先 Plan 再 Build）

适合需要跨文件、多步骤的复杂功能开发（如新增业务模块、开发新页面），示例需求：实现用户删除笔记后，标记为软删除，新增回收站页面支持恢复 / 永久删除。

1. 切换到 Plan 模式：按 Tab 键，确认右下角显示 Plan；
2. 切换到 Build 模式：确认计划无误后，按 Tab 键切换到 Build；
3. OpenCode 会自动修改数据库模型、新增接口、开发页面，所有修改都会实时显示在终端，可随时查看。

执行编码：在终端输入指令，让 AI 开始开发：

按照计划执行，完成所有修改。

迭代计划：OpenCode 会生成实施计划（如修改哪些文件、新增哪些接口、页面布局设计等），如果计划不符合预期，直接在终端补充需求即可，比如：

回收站页面的设计参考项目中已有的笔记列表页面，使用相同的 UI 组件。

小技巧：可直接将设计图 拖放到终端，OpenCode 会自动识别图片内容，作为设计参考！

描述需求：在终端输入详细需求（把 AI 当初级开发者，越详细越好）：

当用户删除笔记时，在数据库中将该笔记标记为 deleted 状态（软删除，不真正删除）；新增一个回收站页面，展示所有标记为 deleted 的笔记；在回收站页面，用户可以点击恢复按钮将笔记恢复为正常状态，也可以点击永久删除按钮彻底删除笔记。

实战 2：直接修改（简单场景，跳过 Plan）

适合单行代码修改、简单功能添加、代码重构等轻量操作（如给接口加鉴权、修改按钮样式），示例需求：给 /settings 路由添加鉴权，参考 /notes 路由的鉴权逻辑。直接在 Build 模式下输入指令（需提供足够细节，指定参考文件）：

给@packages/functions/src/settings.ts 中的/settings 路由添加身份验证，参考@packages/functions/src/notes.ts 中/notes 路由的鉴权逻辑，实现完全相同的功能。

小技巧：使用 @符号 可模糊搜索项目文件，直接引用文件路径，无需手动输入完整路径，大幅提升效率！

实战 3：代码解释（读懂陌生代码 / 祖传代码）

遇到不熟悉的代码库或老项目时，可让 OpenCode 直接讲解代码逻辑，示例：

解释@packages/functions/src/api/index.ts 中的认证逻辑，说明每一步的作用。

适合快速接手新项目、理解团队同事的代码，省去逐行阅读的时间。

实战 4：撤销 / 重做修改（操作失误快速回滚）

如果 AI 生成的代码不符合预期，无需手动修改，直接用命令快速回滚：

1. 撤销修改：输入 /undo，可撤销上一步操作，多次输入可撤销多次修改；
2. 重做修改：输入 /redo，可恢复最近一次撤销的修改。

实战 5：会话分享（团队协作，同步开发思路）

如果需要和团队同事沟通开发方案，可将 OpenCode 的对话生成链接分享，输入命令：

/share

链接会自动复制到剪贴板，同事打开即可查看完整的需求分析、计划设计、代码修改过程，无需反复沟通。

六、高频实用命令：Slash 命令体系，提升操作效率

OpenCode 的 Slash 斜杠命令 是核心操作方式，所有功能都可通过命令实现，无需鼠标操作，下面整理了开发中最常用的高频命令，建议收藏！

七、高级玩法：定制化 OpenCode，适配个人 / 团队开发习惯

OpenCode 支持高度定制化，可通过 自定义主题、快捷键、模型参数、Agent 代理 等，让工具完全适配你的开发习惯，这里分享 2 个最实用的高级技巧：

1. 自定义模型参数，平衡生成效果与速度

在配置面板中可修改模型核心参数，根据开发场景调整：

• 温度参数（Temperature）：0-1 区间，值越小代码越严谨（推荐 0.2-0.4，生产环境），值越大创造性越强（适合原型开发）；
• 最大生成长度（Max Tokens）：限制单次生成代码长度，前端组件开发建议设 2048，避免冗余代码；
• 上下文扫描范围：可选「当前文件 / 当前文件夹 / 整个项目」，大型项目建议选「当前文件夹」，减少性能消耗。

2. 自定义 Agent 代理，实现专属功能

可创建自定义 Agent（如代码审查专家、安全检测专家），让 OpenCode 扮演特定角色，实现专属功能：

1. 在项目根目录创建文件夹：.opencode/prompts/；
2. 在终端输入 /run security，即可调用该自定义 Agent，对项目进行安全检测。

创建自定义 Agent 文件（如 security.md），写入系统提示词：

你是一名资深网络安全专家，专门检查代码中的 SQL 注入、XSS 漏洞、权限绕过等安全问题，发现问题后给出详细的修复方案，不直接修改代码。

八、VSCode 集成：IDE 无缝使用，无需切换终端

对于习惯用 VSCode 的开发者，可将 OpenCode 集成到 IDE 中，实现 终端 + 编辑器 无缝操作，体验更佳：

1. 打开 VSCode，按 Ctrl+Shift+X（Windows/Linux）/Cmd+Shift+X（Mac）打开扩展市场；
2. 搜索 OpenCode，找到官方认证插件并安装，重启 VSCode 生效；
3. 打开 VSCode 底部终端，按正常步骤启动 / 使用 OpenCode 即可；
4. 小技巧：在 VSCode 的 keybindings.json 中绑定快捷键（如 Ctrl+'），可快速唤起 OpenCode，无需手动输入命令。

优势：可直接将 VSCode 左侧文件树的文件 拖放到终端，OpenCode 会自动识别并执行 /add 命令，添加到上下文，大幅提升操作效率。

九、避坑指南：新手常见问题与解决方法

1. Windows 系统使用卡顿 / 功能不全：优先使用 WSL（Windows Subsystem for Linux），原生终端对部分功能支持有限；
2. API 密钥配置失败：检查密钥是否正确，第三方模型需确认密钥未过期、有足够额度，国内用户需注意网络环境；
3. AI 无法理解项目结构：确认已执行 /init 命令，且 AGENTS.md 文件存在，未被修改 / 删除；
4. 生成代码与项目规范不符：在 AGENTS.md 中补充项目编码规范（如代码风格、命名规则、框架使用要求），OpenCode 会自动遵循；
5. Token 消耗过快：使用 /compact 命令压缩上下文，避免无关对话占用 Token，简单任务用轻量模型（如 gpt-4o-mini、GLM-4.7）。

十、总结

OpenCode 作为一款开源的 AI 编码代理，真正做到了 '解放程序员双手，聚焦核心业务'，它不是替代开发者，而是成为开发者的 '编程搭子'—— 帮你处理重复编码、读懂陌生代码、重构老项目、写技术文档，让你把时间花在更有价值的需求设计和架构优化上。

本文从安装配置到实战技巧，覆盖了 OpenCode 的核心使用场景，只要掌握 Plan+Build 双模式 和 Slash 命令体系，就能搞定绝大多数开发工作。后续随着社区生态的完善，OpenCode 的功能会越来越强大，赶紧上手试试，让 AI 帮你提升开发效率吧！

最后，推荐大家关注 OpenCode 官方文档（https://opencode.ai/docs/zh-cn）和 GitHub 仓库，及时获取最新功能和更新内容，也可以参与社区贡献，一起完善这款开源工具！