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

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

（5）Docker 安装

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

3. 验证安装

opencode --version 

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

1. 新手配置：OpenCode Zen

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

在 TUI 中输入连接命令：

/connect 

启动 OpenCode：

opencode 

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

在 /connect 命令后选择对应模型提供商，输入其官方 API 密钥即可。建议将 API 密钥存入项目本地配置。

四、项目初始化

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

1. OpenCode 会自动扫描项目文件，在根目录生成 AGENTS.md 文件；
2. 输入初始化命令：

/init 

3. 终端导航到项目根目录：

cd /path/to/your/project 

重要提示：务必将 AGENTS.md 提交到 Git 仓库，以便团队协作时快速读取项目信息。

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

OpenCode 的核心是 Plan（规划模式）+Build（构建模式）。按 Tab 键 切换模式，右下角显示指示器。

• Plan 模式：只读分析，生成实施计划；
• Build 模式：执行编码，修改或创建文件。

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

适合跨文件、多步骤开发。示例需求：实现用户删除笔记后标记为软删除，新增回收站页面。

1. 切换到 Plan 模式，确认计划无误；
2. 切换到 Build 模式；
3. 输入指令：

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

4. 若计划不符，补充需求：

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

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

适合单行代码修改或轻量操作。直接在 Build 模式下输入指令：

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

小技巧：使用 @ 符号可模糊搜索项目文件。

实战 3：代码解释

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

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

实战 4：撤销/重做修改

• 撤销：输入 /undo；
• 重做：输入 /redo。

实战 5：会话分享

输入命令 /share，生成对话链接分享给团队同事。

六、高频实用命令

七、高级玩法

1. 自定义模型参数

在配置面板调整核心参数：

• 温度参数（Temperature）：0-1 区间，值越小越严谨（推荐 0.2-0.4）；
• 最大生成长度（Max Tokens）：限制单次生成长度；
• 上下文扫描范围：可选当前文件/文件夹/整个项目。

2. 自定义 Agent 代理

在项目根目录创建 .opencode/prompts/ 文件夹，写入系统提示词（如 security.md），调用特定角色 Agent。

八、VSCode 集成

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

优势：可直接将文件树拖放到终端，自动添加到上下文。

九、避坑指南

1. Windows 卡顿：优先使用 WSL；
2. API 密钥失败：检查密钥有效性及网络环境；
3. AI 无法理解项目：确认已执行 /init 且 AGENTS.md 存在；
4. 代码规范不符：在 AGENTS.md 中补充编码规范；
5. Token 消耗快：使用 /compact 压缩上下文，选用轻量模型。

十、总结

OpenCode 作为开源 AI 编码代理，通过 Plan+Build 双模式和 Slash 命令体系，能有效提升开发效率。掌握安装、配置及常用命令即可应对大多数开发场景。