香香甜甜圈1. OpenCode 到底是什么，为什么值得折腾
OpenCode 是一个开源终端 AI 编程助手。不是套壳的编辑器，也不是网页端的 ChatGPT 包装，它跑在你的终端里，跟 NeoVim、VS Code、JetBrains 系列都可以配合使用。核心定位是“帮你在真实项目里写代码、改代码、执行命令”的那个 AI 搭档，而不是简单的代码问答工具。
很多朋友把 OpenCode 和 Claude Code、Codex 混为一谈，实际上它们属于同类产品，但 OpenCode 有一个很关键的特质——模型无关。它可以接 OpenAI、Anthropic、Google Gemini、本地 Ollama，甚至任何兼容 OpenAI 接口的自部署模型。这点比 Claude Code 只能绑 Claude、Codex 跟 GitHub Copilot 绑定更灵活，对有模型切换需求的人来说特别实用。
这篇内容会覆盖 OpenCode 从零到一的完整流程：安装、模型配置、日常使用技巧、模板系统，以及我从实际项目中踩过的一些坑。适合三类人看：
- 已经在用 Cursor / Claude Code，想找个开源替代或者想多一个终端工具的开发者
- 对 AI 编程有基础了解，但没真正配置过终端 Agent 的新手
- 自己部署了模型 API，想找一个客户端把模型“用”起来的人
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装前的环境准备
2.1 Node.js 是前置条件
OpenCode 无论哪个版本，都要求本机有 Node.js 环境。这一点和很多人的直觉不太一样，OpenCode 底层是用 TypeScript 写的，安装包通过 npm 分发，所以 Node.js 是硬性依赖。
安装 Node.js 建议直接去官网下载 LTS 版本，不要用系统自带的 apt 源或者 yum 源里的老版本，那些版本通常很旧，装完后 OpenCode 跑起来会有各种奇奇怪怪的兼容性问题。LTS 版本目前稳定在 20.x 以上，安装完在终端确认一下：
bash复制node -v
npm -v
我遇到过不少朋友在 Windows 上装完 Node 之后，发现 npm 命令提示“不是内部或外部命令”。这个通常是因为安装时没有把 Node.js 自动加入 PATH，或者安装完成后没有重新打开终端。解决办法就是检查环境变量里有没有 Node.js 的安装目录，再重开一个终端窗口。
Zsh 用户还可以顺手配一下 npm 的全局路径，不然全局安装的包可能找不到：
bash复制npm config set prefix ~/.npm-global
echo 'export PATH=$PATH:~/.npm-global/bin' >> ~/.zshrc
source ~/.zshrc
2.2 OpenCode 的安装方式
安装 OpenCode 目前有两种主流方式，我分别说一下适用场景：
第一种是 npx 直接运行，不需要全局安装：
bash复制npx opencode
这种方式适合临时体验或者不想污染全局环境的情况。缺点是每次启动都要经历一次 npm 的解析，速度上会慢一点点。如果你只是想看看 OpenCode 长什么样，用这个方式足够了。
第二种是全局安装：
bash复制npm install -g opencode
安装完成后直接执行 opencode 就能启动。我推荐日常使用这种方式，Terminal 里启动 Agent 本来就追求快，全局安装能省掉 npx 每次解析依赖的时间。
安装完验证一下版本：
bash复制opencode --version
如果你用的是 macOS，也可以走 Homebrew 安装：
bash复制brew install sst/tap/opencode
不过 brew 版本有时候更新不及时，npm 全局安装通常是最快拿到新版本的渠道。
3. 模型供应商配置，所有 AI 编程工具的核心环节
3.1 先理解 OpenCode 的模型接入机制
AI 编程工具不配置模型，就像手机不装 SIM 卡——硬件没问题，但没有服务可用。OpenCode 在这方面设计得比较聪明，它抽象了一层 provider 机制，你可以在配置文件里指定使用哪个模型，也可以随时切换。
各个模型 API 的 key 通过环境变量注入，而不是硬编码在配置里。这种设计的好处也简单：配置跟随环境走，你在公司用自己的账号，在家里用另一个账号，不会搞混。
3.2 用 Anthropic 模型做默认配置
OpenCode 对 Anthropic Claude 的支持是最成熟的。只需要设置一个环境变量：
bash复制export ANTHROPIC_API_KEY=your-api-key-here
设置完直接运行 opencode，它会自动使用 Claude 模型。在配置文件中你还可以精确控制模型名称，比如想用 Claude Sonnet 4 还是 Opus ：
json复制{
"model": "anthropic/claude-sonnet-4"
}
这个 provider/model 的格式贯穿始终，前面的部分是 provider 名称，后面是具体的模型 ID。
3.3 OpenAI 兼容接口的接入方式
如果你用的是 OpenAI 官方模型或者第三方兼容 OpenAI 协议的接口，环境变量名称要换成 OpenCode 约定的格式：
bash复制export OPENAI_API_KEY=sk-xxx
OpenCode 的配置目录是 ~/.config/opencode/，你可以在 opencode.json 里做更细的配置。比如自定义 base URL 指向自己的代理服务：
json复制{
"$schema": "https://opencode.ai/config.json",
"provider": {
"openai": {
"options": {
"baseURL": "https://your-endpoint.com/v1"
}
}
}
}
3.4 本地模型 Ollama 的接入
本地模型是很多人比较关心的，我之前也试过用 Ollama 跑 Qwen 和 DeepSeek 的量化版。接入方式只要设置一个环境变量：
bash复制export OLLAMA_API_KEY=ollama
然后让 OpenCode 使用本地模型：
bash复制opencode --model ollama/qwen2.5-coder
注意，本地模型跑出来的效果和云端商用模型差距还是比较明显的。个人体会是，本地 7B 级别模型适合做代码解释和简单重构，真正驱动 Agent 去多文件改代码还是偏吃力。但是论隐私保护，本地模型自有它的价值。
3.5 多 Provider 切换的实际体验
OpenCode 在 TUI（终端界面）里用快捷键就能切换模型，不过它的模型列表需要配置 models 字段，在配置文件中手动声明：
json复制{
"models": {
"claude-sonnet-4": {
"provider": "anthropic",
"name": "Claude Sonnet 4"
},
"gpt-4o": {
"provider": "openai",
"name": "GPT-4o"
},
"qwen2.5-coder": {
"provider": "ollama",
"name": "Qwen 2.5 Coder (Local)"
}
}
}
配置好之后，在 TUI 里按 Ctrl + K 可以弹出模型切换面板。这个功能在对比模型输出质量时太有用了，同一个 Prompt 分别在 GPT-4o 和 Claude 上跑一遍，再看哪个答案更贴需求，在模型选型阶段能省不少时间。
4. OpenCode 的核心功能拆解
4.1 三种调用模式
OpenCode 不是只有一个简单的问答界面，它提供三种使用方式，我逐个讲清楚它们的区别和适用场景。
对话模式（Chat）：直接在 TUI 里输入问题，OpenCode 会以对话形式回答。适合需求澄清、代码解释、方案讨论。
命令模式（Command）：在 TUI 输入框里以 / 开头输入斜杠命令。比如 /init 可以初始化项目，/plan 可以拆分任务，/agent 可以进入自主执行模式。这是 OpenCode 真正像一个“Agent”而不是“聊天机器人”的关键。
非交互模式（Non-interactive）：直接在终端里传参运行：
bash复制opencode run "帮我重构 src/utils/api.ts 中的错误处理逻辑"
这种模式适合脚本化调用和 CI/CD 集成。比如写个 shell 脚本，批量让 OpenCode 处理后端项目里的 TODO 注释，自动生成补丁文件。
4.2 Agent 模式：让 AI 动手操作
OpenCode 的 agent 模式，是它在体验上最接近 Cursor Agent 和 Claude Code 的地方。进入 agent 模式后，它可以读取项目文件、修改代码、执行终端命令，同时按一定的循环逻辑工作：读文件 → 理解 → 修改 → 看测试结果 → 再修改。
这个模式特别适合做这类任务：“把整个项目的 import 语句按绝对路径重排”“给 utils 目录下所有函数补 JSDoc 注释”这类需要跨多个文件的重复性工作。我在一个中型 TypeScript 项目里实测过，一次性重构了 20 多个文件的导入路径，成功率很高，当然改完之后还是需要自己 review 一遍 diff 的。
不过 agent 模式也有隐患。它会执行终端命令，如果你不小心让它跑了危险操作（比如删库），后果自负。我习惯在刚开始时对项目做一次 git 提交，确保状态干净，这样 agent 不管折腾出什么样子都能一键回滚。
4.3 权限控制系统
OpenCode 的权限控制分为三类：文件读写权限、命令执行权限、联网权限。默认情况下它会先询问你是否允许某个操作，这种机制在安全性和便利性之间取了平衡。
如果你对项目比较有信心，可以放开权限限制：
bash复制opencode --dangerously-bypass-approvals-and-sandbox
这个参数名字本身就足够直白，适合在 CI 环境或临时容器里使用。平时做人肉开发建议还是保留询问模式，尤其是联网权限，AI 在 agent 模式下可能会主动请求外部 API，保留确认环节能避免一些不必要的请求产生费用。
4.4 OpenCode 与 VS Code 的结合
OpenCode 原生是 TUI，但如果你想在编辑器里用，也有官方 VS Code 扩展。安装后可以在 VS Code 里直接调起 OpenCode，选中的代码可以一键发给 OpenCode 处理。
相比纯终端，VS Code 扩展的好处是能看到上下文。左边是代码，右边是 OpenCode 的回复，选中代码后按快捷键发送，AI 给出的修改建议直接在编辑器里高亮展示。这种体验其实比 Cursor 的 chat 面板更轻量，因为它不依赖编辑器的内置模型配置，只负责把请求转发到 OpenCode。
5. 模板系统与实践
5.1 模板是什么，能解决什么问题
OpenCode 的模板机制，和我们在 Git 仓库里看到那些 .templates 目录作用是类似的。它的核心价值是把“可复用的 prompt 片段”沉淀下来。
这个设计解决的是 AI 编程中的一个经典痛点：同一个问题，你每次都要花大量字数去描述背景、明确需求、限定输出格式。而模板让人可以将这些上下文固定下来，需要时一键调用。
5.2 Skill 的目录规范与编写
OpenCode v2.0 之后引入了类似 Claude Code 的 SKILL 机制。每个 skill 是一个目录，目录里必须有 SKILL.md 文件：
bash复制~/.config/opencode/skills/
└── my-skill/
└── SKILL.md
SKILL.md 使用 YAML frontmatter 定义元信息，正文部分是具体的指令：
markdown复制---
name: my-skill
description: 当用户需要生成 API 路由测试时使用
---
# API 路由测试生成
当用户要求为 Fastify 路由创建测试文件时，遵循以下步骤：
1. 解析路由文件中的 HTTP 方法和 URL
2. 使用项目的测试框架（fastify.inject 或 supertest）生成测试
3. 测试包含正常请求和 404 等异常路径
4. 输出文件放在 `test/` 目录下，命名规则为 `[router-name].test.ts`
配置完 skill 之后，你可以在对话里直接引用它。skill 的真正价值在于保持团队 AI 使用体验的一致性——新人加入项目，只要导入同一套 skill 文件，AI 的产出格式和风格就基本统一。
5.3 OpenSpec 与模板工程化
如果你的项目团队比较看重工程规范，可以看看 OpenCode 的 OpenSpec 支持。这是 OpenSpec 组织定义的一套 AI-friendly 项目规范模板，里面包含文档结构、任务追踪、需求拆分的标准。OpenCode 可以直接基于这套规范生成项目骨架。
在项目里执行：
bash复制opencode init
它会根据当前项目结构自动生成一个 .opencode/ 目录，里面包含项目说明、任务定义和 agent 配置。当一个项目被多个 AI 工具交替处理时，这些结构化的元数据就非常关键，相当于给不同的 AI 工具提供了统一的“项目知识入口”。
5.4 快速创建项目模板
OpenCode 还支持从模板创建项目。内置的模板包括 TypeScript 库、React 应用、Python CLI、Go 服务等。使用方法：
bash复制opencode create my-project --template typescript
这个功能的实用性在于，你不用再经历“从零搭 TS 项目配置 tsconfig + jest + eslint”的繁琐过程。模板生成后，直接让 OpenCode 在这个骨架里做功能开发，AI 的上下文完整度会明显高于在空目录里直接开始的情况。
6. 日常使用中的关键技巧
6.1 项目上下文的构建
OpenCode 不是随意让 AI 读整个文件系统的。它默认会读取项目里的 AGENTS.md 文件（类似 Claude Code 的 CLAUDE.md），这个文件可以看作给 AI 看的项目说明书。
我的习惯是，在项目根目录放一份 AGENTS.md，内容包含：
- 项目的前端框架、后端框架、数据库
- 代码风格约定（缩进、命名规范、是否用 semicolon）
- 关键的目录结构说明
- 测试、Lint 命令
- 常见的部署流程和注意事项
这样每次启动 OpenCode，它不需要你反复解释项目背景，直接基于 AGENTS.md 里的上下文来工作。这个文件的质量，直接决定 AI 产出代码与项目风格的契合度。
6.2 /plan 模式拆解任务
处理复杂需求时，我强烈建议先走 /plan 模式。输入需求后，OpenCode 会先输出一个实施计划，包括涉及的文件、改动内容、潜在风险。确认计划后再让它执行，能避免 AI 直接上手改出一些你根本不想要的方案。
这个“计划先行”的思路，其实和传统开发的“设计评审”是同构的。AI 的能力越强，越需要前置约束，否则它跑偏的代价就越大。
6.3 会话持久化与恢复
OpenCode 支持会话保存，你可以在一次长时间调试后，把整个会话存储下来，第二天继续接着聊。会话文件存在 ~/.local/share/opencode/ 目录下，用 opencode --resume 可以恢复最近的会话。
这个功能在以下场景尤其好用：上午让 AI 理清了某个模块的调用链，下午因为其他事情打断了，晚上回来直接恢复会话，AI 对问题的理解还在，不需要重新用一大段话来描述上下文。
7. 常见问题与排查技巧
7.1 无法启动或白屏
如果你安装完成之后运行 opencode 卡在启动页或者直接崩溃，可以先看一下终端报错信息。多数情况下是 Node.js 版本过低导致。OpenCode 要求 Node.js 18+，建议直接用最新的 LTS。
另一个可能的原因是终端不兼容 TUI 渲染。Windows 老版的 cmd 或 PowerShell 5.x 对 TUI 支持很差，会出现界面错乱。解决方式是使用 Windows Terminal，或者 WSL 里的终端环境。
7.2 模型接入失败
模型接入失败的报错通常集中在两类：认证失败（401/403）和网络超时。
认证失败就是 API key 不对，检查环境变量是否设置成功：
bash复制echo $ANTHROPIC_API_KEY
如果你在多个 shell 配置文件（.bashrc/.zshrc）中反复设置过同一个环境变量，注意后设置的会覆盖先前的。
网络超时则和你的 API 端点有关。如果用了自定义 base URL，先直接 curl 一下这个地址，确认接口本身是通的，再排查 OpenCode 的配置。很多时候问题根本不在 OpenCode，而是端点服务的连通性。
7.3 Agent 模式卡住不动
Agent 模式卡住有几种情况：
- 模型返回的 token 过长，某些 provider 遇到超长响应会直接截断，Agent 会处于“等待输出”的假死状态
- 权限询问弹窗没有显示在当前终端焦点上，看起来像是卡住了，其实是在等你确认
- 模型上下文窗口满了，这时需要清理 session 或者开启新的会话
前两种好解决，最后一种要养成定期清理上下文的习惯。我通常每进行一个完整功能开发，就开一个新会话，让 AI 每次聚焦一个上下文窗口内的任务，效果比一个会话从头用到尾稳定得多。
7.4 OpenCode 与 Git 的冲突问题
AI 自动改代码，有时会碰你正在编辑的文件。如果你用 VS Code 同时打开同一个项目，OpenCode 在终端里改了文件，VS Code 不一定能立即感知到缓存变化。这会造成手动保存时把 AI 写的部分覆盖掉。
解决方式：让 OpenCode 工作前先 git commit 当前状态，AI 工作完后你直接看 diff。不要一边手动编辑一边让 agent 改同一个文件，这是最容易产生冲突的操作方式。
8. 从 Cursor 迁移到 OpenCode 的个人体会
用过 Cursor 的朋友应该清楚，Cursor 的 Agent 能力是它最核心的卖点，但它是一个商业闭源产品，模型绑定在它们的订阅体系里，而且开箱即用的代码补全体验依赖它们定制的模型。
OpenCode 作为开源终端工具，天然适合那些想把 AI Agent 深度嵌入到自己已经成熟的工作流中的开发者。比如你目前的开发环境是 Neovim + tmux，那 OpenCode 的 TUI 界面和快捷键风格会非常自然；如果你习惯在 VS Code 里做代码审查，那它的 VS Code 扩展也能接得住。
我个人在实际使用中最大的感受是，OpenCode 的上下文控制比想象中更灵活。Skill 机制可以像搭积木一样给 AI 组装不同的技能模块，这比每次调用时临时写一大段“指导语”可靠得多。折腾一次 skill 配置，后面每次使用都能受益。
最后再分享一个小技巧：如果你在做技术选型，可以同时装上 OpenCode 和 Claude Code，给它们同一个任务，看看哪个产出更贴近你的项目规范。同一个模型，不同 Agent 的 prompt 组织和工具调用策略差异巨大，实测下来结论可能和网上传闻很不一样。工具多从来不是坏事，重要的是搞清楚每一个工具的独特边界在哪里。