OpenCode配置使用手册：AI辅助编程高效指南

前言

Cursor、Trae、Github Copilot、通义灵码……这些AI辅助编程工具，想必各位开发者已经耳熟能详了。今天，我们把目光投向一个不太一样的选手——它不止于代码补全，而是一个能与你深度协作的“编程伙伴”。没错，它就是OpenCode。

简介

简单来说，OpenCode是一个开源的AI编程袋里（AI coding agent）。它的独特之处在于，你可以直接在终端、桌面应用，或者你最熟悉的IDE（比如VS Code）里与它对话，共同完成编码任务。

无论是理解一个陌生的代码库、编写新功能、重构臃肿的代码，还是定位那些恼人的Bug，OpenCode都能提供实质性的帮助，堪称开发效率的“翻跟斗”。

在模型支持上，OpenCode显得相当“博爱”。它接入了超过75家模型提供商，内置了GLM-4.7、MiniMax M2.1等免费模型，同时也支持对接OpenAI、Anthropic、Google等主流商业模型。如果你追求隐私或定制化，配置本地模型（如Llama 3）也不在话下。这种灵活性，让它能轻松应对从轻量脚本到复杂架构的各种场景。

安装

安装OpenCode最省事的方法，是使用官方的一键安装脚本：

curl -fsSL https://opencode.ai/install | bash

当然，你也可以根据习惯选择其他方式：

• Node.js：通过npm全局安装。

npm install -g opencode-ai

• macOS/Linux：如果你在用Homebrew，一条命令就能搞定。

brew install anomalyco/tap/opencode

配置

安装完成后，需要进行简单配置才能开始使用：

1. 连接模型：在终端运行 /connect 命令。
2. 输入密钥：根据提示，输入你所选模型提供商的API密钥。
3. 理解配置加载：OpenCode的配置遵循一个明确的优先级顺序，它会依次从以下位置读取 opencode.json 文件：

   远程配置 (.well-known/opencode)
   → 全局配置 (~/.config/opencode/opencode.json)
   → 环境变量 (OPENCODE_CONFIG)
   → 项目配置 (./opencode.json)

   一份最简化的配置可能长这样，只需指定主要模型和一个轻量模型即可：

   {
     "model": "anthropic/claude-sonnet-4-20250514",
     "small_model": "anthropic/claude-haiku-3-5-20241022"
   }

4. 熟悉目录结构：了解配置文件存放的位置，有助于后续的自定义和问题排查。全局配置位于 ~/.config/opencode/ 下，项目级配置则放在项目根目录的 .opencode/ 文件夹中。

初始化

当你准备在一个新项目中使用OpenCode时，需要先让它“认识”这个项目。

1. 进入你的项目目录：cd xxx/project
2. 启动OpenCode：opencode
3. 运行初始化命令：/init

这个步骤会生成一个 AGENTS.md 文件，它帮助OpenCode理解项目的整体结构和上下文，为后续的精准协作打下基础。

使用方法

配置妥当，项目也已初始化，现在可以真正体验OpenCode的核心能力了。它主要提供了两种工作模式，对应不同的思维和操作场景。

对话（Plan）

可以把Plan模式看作是AI的“思考与规划”模式。当你需要分析问题、讨论方案，而不是立即动手改代码时，这个模式就派上用场了。

在Plan模式下，你可以：

• 排查问题：把错误日志扔给它，让它帮你分析根因。
• 梳理流程：让AI帮你理清复杂的业务逻辑和数据流向。
• 制定计划：描述一个需求，让它输出可执行的任务拆解清单。
• 方案设计：讨论技术选型、架构优化等决策性问题。

比如，你可以直接提问：“帮我分析一下这个项目可以做哪些性能优化”。

Plan模式非常适合以下典型场景：

• 代码审查：“帮我review一下这段代码，看看有哪些问题？”
• 架构咨询：“我想在这个项目中引入状态管理，有什么建议？”
• 故障诊断：“这个接口返回500错误，帮我分析一下可能的原因。”
• 重构规划：“这个文件有2000多行，帮我规划一下如何拆分成小组件。”

记住，在Plan模式下，AI会给出详尽的分析、建议和步骤，但它不会直接修改你的代码文件。这是进行深度技术探讨的理想模式。

写代码（Build）

如果说Plan模式是“动口”，那Build模式就是“动手”。这是OpenCode真正替你编写和修改代码的核心模式。

切换方式很简单：在对话界面按 Tab 键，或者直接输入 /build 命令。

进入Build模式后，你就可以发号施令了：

1. 代码生成：“帮我创建一个用户登录表单，包含用户名、密码和验证码。”
2. 代码重构：“把这个类组件重构为函数组件，使用Hooks。”
3. Bug修复：“修复这个文件中的内存泄漏问题。”
4. 批量修改：“把所有console.log替换成统一的日志工具。”
5. 文件操作：“创建一个新的API服务文件，包含用户相关的CRUD操作。”

它的工作流程通常是：你描述需求 → AI分析上下文并生成变更方案 → 你确认后，AI自动应用修改 → 你可以通过 git diff 查看具体变动。

这里有个重要提醒：Build模式会直接修改文件。因此，最佳实践是，在让AI进行大规模操作前，先确保你的代码已提交到Git。另外，善用 /check 命令可以让AI先给出方案而不立即执行，配合 .gitignore 和 AGENTS.md 可以更好地控制AI的操作范围。

撤销变更

在Build模式下，如果AI的修改不尽如人意，别担心，有多种方式可以回退：

方式一：依赖Git
最传统也是最可靠的方法，直接用Git命令回滚。

方式二：使用OpenCode指令
OpenCode提供了便捷的撤销命令，/undo 可以撤销最近的修改，也可以指定文件。

方式三：让AI自己回滚
直接告诉AI：“把我刚才的修改撤销，恢复到修改前的状态。” 它也能理解并执行。

总结一下安全操作的心得：大改之前先提交；多用 /check 预览方案；随时关注 git status；涉及多文件时，考虑分批确认，降低风险。

分享

现代开发离不开协作。OpenCode内置的分享功能，让你能轻松将一段有价值的AI对话共享给队友。

生成分享链接

在任何对话中，只需输入 /share 指令。OpenCode会立即将当前对话内容（包括你的提问、AI的回答、代码片段、文件变更记录，甚至AI的思考过程）生成一个唯一的URL，并自动复制到你的剪贴板。

分享链接的使用场景

这个功能的应用场景非常广泛：

• 技术评审：让AI帮忙Review代码后，生成链接发给同事进行二次评审。
• 问题求助：将排查Bug的完整分析过程分享到团队群，信息一目了然。
• 知识沉淀：让AI总结的最佳实践，生成链接后可直接存入团队Wiki。
• 远程协作：将AI生成的模块代码及实现思路分享给远程同事，保持上下文同步。

分享链接的安全性

需要注意的是，生成的分享链接默认是公开的，任何拥有链接的人都可以查看，且长期有效。因此，分享前请务必检查对话中是否包含敏感信息（如密钥、内部地址等）。对于有更高安全要求的企业，OpenCode Enterprise版本支持私有部署和精细的权限控制。

分享链接示例

执行 /share 后，你会得到一个类似 https://opencode.ai/s/abc123def456 的链接。打开后，访问者可以看到一个完整的对话界面，能够查看历史、复制代码、查看文件Diff，甚至将对话导出为Markdown，体验相当完整。

进阶技巧

要真正发挥OpenCode的威力，不妨试试这些组合技。

组合使用 Plan + Build

最高效的流程往往是“先谋定而后动”。先在Plan模式下与AI充分讨论方案、厘清思路，然后再切换到Build模式，让它精准执行。这就像先和架构师画好蓝图，再让工程师施工，事半功倍。

使用上下文指令

OpenCode支持精准的上下文引用，让你的指令更具体：

• 引用文件：@src/components/Button.tsx 帮我优化这个组件
• 引用代码行：@src/utils.ts:10-50 这段代码有什么问题？
• 引用函数：@formatDate 函数帮我添加参数校验

批量操作

AI擅长处理重复性工作。你可以直接下达批量指令，例如：“修改所有组件，统一添加loading状态”、“把所有User相关的变量名改为Member”、“删除项目中所有未使用的import”。

总而言之，掌握OpenCode的精髓在于理解其三种核心能力的定位：Plan模式用于思考，Build模式用于执行，分享功能用于协作。灵活运用这三者，这位AI编程伙伴才能真正融入你的工作流，成为提升开发质效的得力助手。