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

3. 验证安装

opencode --version

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

1. 新手配置：OpenCode Zen

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

在 TUI 中输入连接命令：

/connect

启动 OpenCode：

opencode

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

在 /connect 命令后选择对应模型提供商，输入其官方 API 密钥即可。国内开发者可优先选择 GLM-4.7、DeepSeek-V3 等国产模型。

四、项目初始化

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

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

/init

3. 导航到项目根目录：

cd /path/to/your/project

提示：建议将 AGENTS.md 提交到 Git 仓库，便于团队协作和后续识别。

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

按 Tab 键 可在 Plan 和 Build 模式之间切换。

• Plan 模式：只读分析，不修改任何文件，仅生成实施计划；
• Build 模式：执行编码，根据 Plan 计划自动修改/创建文件。

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

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

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

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

3. 切换到 Build 模式，执行编码：

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

实战 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），定义角色（如安全检测专家），通过 /run security 调用。

八、VSCode 集成

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

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

九、避坑指南

1. Windows 系统卡顿：优先使用 WSL；
2. API 密钥配置失败：检查密钥是否正确及有效期；
3. AI 无法理解项目结构：确认已执行 /init 且 AGENTS.md 存在；
4. 生成代码与规范不符：在 AGENTS.md 中补充项目编码规范；
5. Token 消耗过快：使用 /compact 命令压缩上下文。

十、总结

OpenCode 是一款开源的 AI 编码代理，支持 Plan+Build 双模式工作流和 Slash 命令体系。掌握其核心用法可有效处理重复编码、读懂陌生代码、重构老项目，提升开发效率。更多功能请参考 OpenCode 官方文档。