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

注意：Windows 上通过 Bun 安装的支持目前仍在开发中。

Docker 安装

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

3. 验证安装

输入以下命令，显示版本号即成功：

opencode --version 

三、基础配置：API 密钥与模型对接

核心配置是对接 LLM 模型的 API 密钥。

1. 新手配置：OpenCode Zen

1. 选择 opencode 选项，终端提示前往授权地址：opencode.ai/auth；
2. 浏览器登录并添加账单信息，复制生成的 API 密钥；
3. 回到终端粘贴密钥并按回车。

在 TUI 中输入连接命令：

/connect 

启动界面：

opencode 

2. 进阶配置：自定义第三方模型

如需使用 GPT-4o、Claude 3 等，在 /connect 后选择对应提供商，输入官方 API 密钥即可。

小技巧：建议将 API 密钥存入项目本地配置，避免全局泄露。

四、项目初始化

配置完成后，需对项目进行初始化，让 OpenCode 理解项目结构。

1. 输入初始化命令：

/init 

2. 启动 OpenCode 并导航至项目根目录：

cd /path/to/your/project 

重要提示：务必将生成的 AGENTS.md 提交到 Git 仓库，便于团队协作或后续复用。

五、核心功能实战：Plan+Build 双模式

OpenCode 的核心是 Plan（规划）+Build（构建）双工作流。先由 AI 出方案，再执行编码，显著提升一次性通过率。

模式切换

• 按 Tab 键 切换 Plan 和 Build 模式，右下角显示指示器；
• Plan 模式：只读分析，生成实施计划；
• Build 模式：执行编码，自动修改文件。

实战 1：新增功能（复杂场景）

示例需求：实现用户删除笔记后标记为软删除，新增回收站页面。

1. 切换到 Plan 模式，确认右下角显示 Plan；
2. 描述需求：

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

3. 切换到 Build 模式，执行指令：

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

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

实战 2：直接修改（简单场景）

适合单行修改或轻量操作。直接在 Build 模式下输入指令，使用 @ 符号引用文件路径：

给 @packages/functions/src/settings.ts 中的/settings 路由添加身份验证，参考 @packages/functions/src/notes.ts 中/notes 路由的鉴权逻辑。

实战 3：代码解释与撤销重做

遇到陌生代码库，可让 OpenCode 讲解逻辑：

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

若生成代码不符合预期，可使用命令回滚：

• 撤销：/undo
• 重做：/redo

实战 4：会话分享

输入 /share 生成对话链接，同事打开即可查看完整的需求分析与代码修改过程。

六、高频实用命令

Slash 斜杠命令是核心操作方式，无需鼠标：

七、高级玩法：定制化

1. 自定义模型参数

在配置面板调整参数以平衡效果与速度：

• 温度参数（Temperature）：0-1 区间，生产环境推荐 0.2-0.4；
• 最大生成长度（Max Tokens）：前端组件建议设 2048；
• 上下文扫描范围：大型项目建议选「当前文件夹」。

2. 自定义 Agent 代理

创建自定义 Agent 实现专属功能，如安全检测专家。

1. 在项目根目录创建 .opencode/prompts/ 文件夹；
2. 创建 security.md 写入系统提示词：

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

3. 在终端输入 /run security 调用。

八、VSCode 集成

习惯 VSCode 的开发者可安装官方插件实现无缝操作：

1. 打开扩展市场，搜索 OpenCode 并安装；
2. 重启 VSCode，底部终端启动使用；
3. 可在 keybindings.json 中绑定快捷键（如 Ctrl+'）快速唤起。

优势：可将左侧文件树的文件拖放到终端，OpenCode 会自动识别并添加到上下文。

九、避坑指南

1. Windows 卡顿：优先使用 WSL，原生终端部分功能支持有限；
2. API 密钥失败：检查密钥有效性及额度，国内用户注意网络环境；
3. 无法理解项目：确认已执行 /init 且 AGENTS.md 存在；
4. 代码规范不符：在 AGENTS.md 中补充编码规范；
5. Token 消耗快：使用 /compact 压缩上下文，简单任务用轻量模型。

十、总结

OpenCode 作为一款开源 AI 编码代理，旨在解放程序员双手，聚焦核心业务。掌握 Plan+Build 双模式和 Slash 命令体系，就能应对绝大多数开发工作。后续随着社区完善，功能将更加强大。参考官方文档获取最新功能和更新内容。