2026/9/8 20:08:41
FEATURED · 精选文章 
如果你最近和我一样被 Claude Code 和 Codex CLI 这类终端 AI 编码 Agent 搅得心痒痒那你大概率也刷到了opencode这个名字。它不是哪家大厂出的而是开源基础设施团队 SST 发起的一个项目主打开箱即用、多模型通吃。我把它当主力工具用了大概两个月期间经历了从 1.x 到 2.0 的升级踩了不少安装、配置、模型切换的坑也把 Skills、Memory、MCP 这些高阶玩法都试了一遍。这篇文章不是官方文档的翻译而是我基于实际项目操作记录的完整复盘从零开始讲清楚 opencode 是什么、怎么装、怎么配、怎么用到真实项目里最后附上高频问题排查表。我默认你是一个会用终端、跑过 Git 命令、接触过 AI 编程助手的开发者。如果你完全是新手也没关系前两部分我会把环境准备、安装路径、常见报错都写得很啰嗦照做就能跑起来。1. opencode 到底是什么为什么我又多装了一个终端工具1.1 从 Claude Code 和 Codex 说起终端 Agent 的爆发过去一年AI 编程助手从“编辑器里的补全插件”进化成了“终端里能自主干活的 Agent”。Claude Code 让 AI 直接读代码、跑命令、改文件Codex CLI 把 OpenAI 的模型能力塞进了命令行。这类工具的共同点是不需要图形界面AI 可以像人一样在项目目录里探索、执行测试、提交代码。但它们也各有痛点——有的只支持自家模型有的配置隐藏在 JSON 里有的想扩展第三方工具特别费劲。opencode 就是这个赛道里杀出来的一个“全家桶型”选手。它做对了三件事第一模型不绑定Anthropic、OpenAI、Google Gemini、OpenRouter、本地模型都能接甚至任何 OpenAI 兼容的服务都能配进来第二它把终端 TUI 界面做得相当舒服不是简单打印日志而是有交互面板、文件树、对话流第三它是真开源GitHub 上的 sst/opencode社区迭代速度极快插件机制、Skills 机制、内置浏览器调试都能用。1.2 opencode 的特殊定位不是大厂产品但是工程化社区的选择先说一个很多人问的问题opencode 是哪家公司的它是 SST 团队主导的开源项目。SST 这个团队之前在 Serverless 领域挺有名做了一套部署框架他们的技术审美很“工程化”写出来的工具通常文档清晰、CLI 体验好、默认配置合理。opencode 也是这种调性——装完之后第一次运行会让你选模型提供商然后自动生成配置文件不需要你去翻几十页文档。它的核心架构可以理解为一个用 Go/TUI 写的前端客户端 一套灵活的 Provider 适配层 可插拔的工具调用机制。你可以在里面跑 Agent 对话、让它操作文件、运行命令、搜索代码也可以让它调用外部 MCP 服务比如浏览器自动化、数据库查询。2.0 之后官方还加入了 TypeScript SDK 和更成熟的 Skills 机制基本向 Claude Code 的能力看齐甚至某些方面更好用。1.3 适合谁用终端党、多模型党、团队标准化需求我个人的体感是opencode 适合三类人长期泡在终端里的开发者习惯了 vim/neovim 或只是不想开 IDE 的轻量操作场景手头有多个模型 API公司采购的、自建的、第三方平台的想在一个工具里统一切换的人想给团队统一配置 AI 编码 Agent 行为的负责人因为 opencode 的配置文件是项目级的可以提交到 Git 仓库里成员 clone 下来就能用同一套规则。如果你现在的日常是 Cursor 重度用户倒也没必要立刻换但 opencode 作为终端补充工具配合插件体系完全能承担“写测试、修 bug、查文档、批量重构”这类脏活累活。2. 安装与第一跑通三步绕开最常见的坑2.1 环境准备Node.js 18、Git、一个终端opencode 的安装方式多种多样但无论哪种底层都依赖 Node.js 环境和 Git。Node.js 建议 18 以上我用的是 20 LTS。Git 必须有因为 Agent 执行 git diff、git commit 这些操作时底层就是调 git 命令。Windows 上建议直接装 Git for Windows它自带了一个 bash 环境很多奇怪的路径问题能少很多。检查命令我直接贴一下node -v git --version只要两个命令都有输出环境就算过关。如果 node 没有去官网下 LTS 版本即可这里就不赘述了。2.2 三种安装方式curl、npm、Homebrew 怎么选opencode 官方推荐用 curl 脚本一键安装curl -fsSL https://opencode.ai/install | bash这个脚本会把二进制放到用户目录下的特定位置同时打印出需要添加 PATH 的路径。目前在 macOS 和 Linux 上体验很顺。Windows 用户如果开了 WSL也建议直接在 WSL 里跑。我实际更常用的是 npm 安装好处是升级方便npm install -g opencode-ai注意包名是opencode-ai不是opencode。npm 源里有另一个不相关的包占了 opencode 这个名字官方包是这个带后缀的。如果你喜欢 Homebrew也有现成 formulabrew install sst/tap/opencode不管哪种方式装完先跑一下opencode --version确认。如果提示没找到命令优先检查 PATH。这一步是新手最高的报错来源我专门放到下一节讲。另外如果你以前装过 Go 环境网上老教程会写go install github.com/sst/opencodelatest。这条路在早期版本确实可以但现在官方发布物已经不太推这种方式了因为复杂依赖和 TUI 资源文件打包会导致 go 安装版本不完整。我建议直接用 curl 或 npm省事。2.3 Windows PowerShell 报“无法识别 cmdlet”怎么破这是搜索热词里出现次数最多的问题opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。本质原因只有一个可执行文件没有被系统找到。打开 PowerShell输入where.exe opencode如果没有输出说明安装路径不在 PATH 里。用 curl 脚本安装时它通常会装到%USERPROFILE%\.opencode\bin\opencode.exe或%LOCALAPPDATA%\opencode\bin之类的位置。解决办法是把对应目录加进 PATH$env:Path ;$env:USERPROFILE\.opencode\bin这一步只是当前会话有效。想让下次打开终端也生效需要设置用户级环境变量[Environment]::SetEnvironmentVariable(Path, $env:Path ;$env:USERPROFILE\.opencode\bin, User)然后完全关掉终端窗口再重新打开不要偷懒只开新标签页。PowerShell 对 PATH 的缓存有时会让人误以为没生效重启终端是最直接的验证方式。2.4 首次运行选 Provider 并完成登录安装成功后在任意项目目录下运行opencode第一次启动会进入引导模式让你选择要使用的模型提供商。常见选项有 Anthropic、OpenAI、Google、OpenRouter、Ollama 等。选了之后它会把对应的 API Key 写入配置文件后面会细讲然后你就进入交互式 TUI 界面了。这里我的经验是第一次别贪多先选一个最方便拿到的 key 跑通流程。比如有 Anthropic 账号就选 Anthropic没有就选 OpenRouter 注册一个免费账号用里面的免费模型也能体验全流程。等跑通了再去配置多个 Provider 来回切换。3. 模型接入与配置文件真正用起来的核心3.1 opencode.json一份配置管理多套模型opencode 的配置采用项目级优先的方式。运行opencode时它会自动查找当前目录的opencode.json找不到就往用户全局目录~/.config/opencode/opencode.json去找。项目级配置会被提交到 Git团队成员拉代码后自动共享。一个最基础的配置文件长这样{ $schema: https://opencode.ai/config.json, provider: { anthropic: { npm: ai-sdk/anthropic, name: Anthropic, options: { apiKey: {env:ANTHROPIC_API_KEY} }, models: { claude-sonnet-4-20250514: { name: Claude Sonnet 4 } } } }, model: claude-sonnet-4-20250514 }通常情况下你不用手写这么完整运行opencode后输入/models命令它会列出当前已经配置好的 Provider 和模型直接选就行。真正需要手写配置的场景是接入非标准的 API 服务或者想给模型自定义名称。3.2 免费模型怎么接OpenRouter 与本地 Ollama搜索热词里有个高频词是“opencode 免费模型”。这确实是 opencode 的一大优势——它不强绑付费 API。最常见的免费路径有两条。第一条OpenRouter。注册账号后生成 API Key然后在配置里添加{ provider: { openrouter: { npm: openrouter/ai-sdk-provider, name: OpenRouter, options: { apiKey: {env:OPENROUTER_API_KEY} }, models: { meta-llama/llama-3.3-70b-instruct:free: { name: Llama 3.3 70B Free } } } } }OpenRouter 的免费模型列表会变有些模型今天免费明天收费用/models刷新就能看到最新状态。它的优势在于模型丰富一个 key 能测很多不同的模型适合做横向对比。第二条本地模型 Ollama。如果你机器配置不错不想把代码发给任何第三方服务可以装 Ollama 拉一个模型起来ollama pull qwen2.5-coder:14b然后在 opencode 里添加 Ollama Provider{ provider: { ollama: { npm: ollama-ai-provider, name: Ollama, options: { baseURL: http://localhost:11434/api }, models: { qwen2.5-coder:14b: { name: Qwen 2.5 Coder 14B } } } } }本地模型的好处是隐私和免费缺点是能力和云端大模型差距明显。我建议用本地模型做小改、补全、简单解释代码复杂的架构设计、跨文件重构还是交给云端模型。3.3 ccswitch 这类切换工具多套配置如何并行实际用起来你会发现光靠 opencode 自带的/models切换配置管理有时还是不够优雅。尤其当你手上同时有公司内网服务、个人付费 API、临时测试的中转 key 时频繁改环境变量很痛苦。这时候社区流行的做法是配一个ccswitch之类的切换工具。这类工具统一管理多个 AI 工具Claude Code、Codex CLI、opencode的配置切换时自动改写对应工具的配置文件。比如你运行ccswitch use work它会把 opencode.json 里的 provider 全部替换成公司那套服务还会同步设置好环境变量文件。这种“工具再套工具”的方案听上去复杂但实际体验很爽。我个人的配置习惯是每个场景建一个独立的 profile里面写好该场景的 provider、model、环境变量然后通过 ccswitch 一键切换再也不用手动备份和覆盖配置文件。3.4 环境变量与自定义端点没有模板也能跑通接入第三方服务时最怕的是目标服务兼容 OpenAI 格式但 base URL 不确定。opencode 的 provider 配置给了你很大自由度只要服务兼容 OpenAI 接口你可以手动指定{ provider: { custom: { npm: ai-sdk/openai-compatible, name: My Custom API, options: { baseURL: https://your-api-endpoint.example.com/v1, apiKey: {env:CUSTOM_API_KEY} }, models: { your-model-name: { name: Your Model Name } } } } }注意npm用的是ai-sdk/openai-compatibleopencode 依赖 Vercel AI SDK这套 provider 机制本质上就是 AI SDK 的 provider 体系。理解了这一点你就能明白为什么它接模型这么灵活。环境变量引用用{env:xxx}的写法好处是 API Key 不会出现在配置文件里适合把配置文件提交到 Git 仓库。我把项目级配置提交到仓库后团队成员只要各自设置环境变量就能跑同一套 Agent 规则。4. 把 opencode 真正用到项目里Agent、Skills、Memory4.1 接手一个老项目的正确打开方式搜索热词里有“opencode 接手开发项目”这是个特别好的场景。我最近用 opencode 接手了一个遗留的 Java Maven 项目代码量十几万行模块依赖复杂老成员留下的文档基本等于没有。我的做法是三步走第一步先让 opencode 读项目结构输入指令/init它会生成一个 AGENTS.md 文件记录项目的技术栈、构建命令、目录约定、测试方式。这个文件相当于给 Agent 的“入职手册”之后每次对话它都会自动参考。对于老项目我建议手动补充这个文件把已知的坑、特殊配置都写进去。第二步让 Agent 跑一遍构建流程请先看一下项目的 pom.xml跟我说清楚这是一个什么项目然后帮我跑 mvn compile 试试注意要明确告诉它先“看”再做避免它上来就大改。opencode 在终端里执行命令前会显示将要运行的命令按 y 确认后才会执行所以就算它想乱跑你有机会拦截。第三步拆任务。老项目代码维护最大风险不是 AI 不会写而是 AI 改完不知道影响范围。我通常要求它每改一个模块就执行对应的单元测试并且把改动按文件粒度拆成多个 commit。在 opencode 里可以直接说“修改完成后分别对 A 模块和 B 模块运行 mvn test通过了再提交”它会一步步执行过程透明可控。4.2 多 Agent 工作流与权限控制很多终端 Agent 工具是单线程的一个对话一个 Agent 全程操作。opencode 在这方面更灵活你可以在 TUI 里输入/agents查看和切换不同的 Agent 实例。比如我跑前后端联调时会让一个 Agent 专看前端逻辑另一个 Agent 查后端接口然后我把两个 Agent 的结论汇总到主对话里。权限控制体现在文件规划和命令确认上。opencode 支持在配置里自定义 Agent 的权限规则比如禁止 Agent 执行rm -rf、禁止修改package-lock.json、只允许在src/目录下写文件。这类规则写在配置文件的permission字段里{ permission: { deny: [ rm -rf, git push ], allow: [ mvn test, npm test, git add, git commit ] } }这个功能在团队场景尤其重要。新人不熟悉仓库时经常一句话让 Agent 乱跑命令权限规则可以兜底。4.3 Skills 技能扩展把 Claude Code 生态迁移过来opencode 的Skills机制是我最喜欢的特性。简单说Skills 是一组预置的指令和提示词放到项目目录的.opencode/skills/下Agent 遇到对应场景会自动加载。它的灵感来自 Claude Code 社区的 skills 实践但 opencode 做了更规范化、更易写的实现支持 Markdown 或 JS/TS 格式。一个最简 Skill 长这样--- name: unit-tester description: 当用户要求写单元测试时自动使用此 skill --- 先分析源文件的依赖关系然后针对每个 public 方法生成对应的测试文件。 测试文件放在与源文件相同的目录下命名规则为 原文件名.test.ts。 运行测试命令前先检查依赖是否安装。把这个文件放在.opencode/skills/unit-tester/SKILL.md并在配置里启用 skills 目录Agent 就会在相关场景下自动读取这段说明改变它的行为。我知道不少人在 Claude Code 里用的是 “superpowers” 这类技能合集那套体系里有很多精心打磨的 skill 文件。迁移到 opencode 是可行的因为技能本质上是提示词加规则把.claude/skills/下的 Markdown 文件复制到.opencode/skills/再做少量格式调整即可。opencode 社区也有脚本能自动转换我自己手动迁移过两次成本很低。真正值钱的其实是那些规则文本不是存放它们的文件夹。4.4 Memory 记忆让 Agent 记住项目约定与偏好AI 编码 Agent 最气人的一点是今天告诉它的约定明天可能就忘了。opencode 提供了一个规范化的记忆机制配置项里可以设置全局记忆文件和项目记忆文件。默认情况下全局记忆在~/.config/opencode/memory.md项目记忆在.opencode/memory.md。它的工作方式是这样的每次会话开始时Agent 会读取这些记忆文件作为上下文会话过程中如果发现需要记录新的约定可以直接要求它“把这个规则记到 memory”它会主动更新对应文件。我用了一段时间后项目记忆里积累了不少有价值的内容比如“不要修改公共 API 的返回结构除非通过新增参数方式兼容”“部署分支是 release不要直接推 main”。配合 AGENTS.md 使用效果更好。AGENTS.md 偏向项目的静态事实memory.md 偏向动态经验。前者可以提交到 Git 仓库给所有人共享后者可以只在本地维护。当然你也可以都提交看团队习惯。4.5 用 Playwright 驱动前端 bug 排查再讲一个搜索热词里出现过的具体场景“opencode playwright 怎么测试前端 bug”。这在之前的版本里要自己配置半天现在 opencode 2.0 自带了浏览器调试工具通过 MCP 协议接入了 Playwright 自动化能力。实测流程是这样的在 opencode 的对话里直接说“打开浏览器访问本地 5173 端口打开页面后点击登录按钮看看控制台有没有报错”。Agent 会自动启动一个 Playwright 驱动的浏览器实例执行点击、输入、截图、读取控制台日志等操作然后把结果反馈到你面前。我遇到过一个很隐蔽的前端 bug某个弹窗组件在特定分辨率下不会正常弹出单纯看代码很难定位。我让 opencode 用 Playwright 打开页面把视口改成 1366x768点击触发按钮它通过截图和控制台日志帮我确认了问题出在 CSS 媒体查询和弹窗挂载时机冲突。整个排查过程几分钟搞定比我手动开 devtools 快很多。5. 编辑器与桌面端不止是黑窗口5.1 VSCode 插件边看代码边对话虽然 opencode 主阵地是终端 TUI但官方提供了 VSCode 插件扩展 ID 可以搜 “opencode”。安装后编辑器左侧会多一个面板能直接基于当前打开文件发起对话、查看 opencode 正在执行的命令、浏览 Agent 产生的 diff。这个插件适合在“需要边看代码边指挥 Agent”的场景。我用 VSCode 插件时最顺手的是把 opencode 作为“代码解释器”选中一段不熟悉的代码右键选择“用 opencode 解释”它会把解释结果输出到侧边栏不用切到终端去问。这比传统的人工去翻调用链效率高很多。当然有个前提VSCode 插件本质上是 opencode CLI 的壳你必须先保证opencode命令能在系统终端里直接运行插件才能正常连接到核心进程。5.2 JetBrains IDEA 插件与 Maven 项目配置搜索热词里还有 “opencode jetbrains idea 插件” 和 “opencode mvn 配置”这俩是连在一起的。官方确实有 JetBrains 插件支持 IntelliJ IDEA、PyCharm、WebStorm 等基于 IntelliJ 平台的 IDE。插件用法和 VSCode 版类似安装后会在右侧打开一个 opencode 工具窗口。对于 Maven 项目的配置我的建议是不要把 Java 构建交给 AI 自由发挥而是事先在 opencode 配置里把常用 Maven 命令写成快捷方式。比如在配置文件中自定义一个 agent 指令{ agent: { mvn-test: { prompt: 对当前 Maven 项目执行 mvn test只汇报测试失败项不要修改任何代码 } } }这样每次只要输入/agent mvn-test它就只干活不乱动。Java 项目构建时间长Agent 在执行命令时如果超时需要调大 TUI 里的超时时间或手动延长命令等待这个我放在常见问题里讲。5.3 桌面版与内置 UI 日志opencode 桌面版是后来才有的适合不喜欢终端交互的人。它能以桌面应用方式运行相当于把 TUI 界面平移到了独立窗口里同时增加了日志查看面板。如果你在 IDE 插件和终端之间切换觉得割裂桌面版可以考虑作为中转站。我实际使用经验是桌面版的价值主要体现在两点一是进程崩溃时能直接看到底层日志不用去终端里翻二是可以同时开多个项目窗口每个项目一个 Agent 会话互不干扰。终端里同时开多个 opencode 会话也能做到但窗口管理没桌面版直观。6. 高频问题排查与配置速查6.1 常见报错对照表这些是我在各大社区里看到以及自己踩过的坑整理成表方便查阅现象原因解决方案PowerShell 提示无法识别 opencode安装路径不在 PATH手动添加路径到用户环境变量重启终端运行后提示unexpected server error. check server logsAPI Base URL 不可达 / 环境变量过期 / 配置了不存在的模型名检查 provider 的 baseURL 是否能正常访问确认 API Key 是否有效用/models重选模型接入第三方服务后一直 401API Key 错误或环境变量没加载检查{env:XXX}变量是否已设置必要时用echo $env:XXX验证执行 mvn test 一直卡住不返回Maven 构建超时设置太短加大 opencode 里命令超时时间或改用后台执行后读取文件确认结果切换模型后对话历史错乱不同模型上下文格式差异大在 TUI 输入/new清空会话或者/compact压缩上下文Agent 修改文件后 git diff 出现全量变更行尾符CRLF/LF不一致在项目根目录加.gitattributes固定行尾符并在 AGENTS.md 中写明hy3-free 这类模型标签无法使用第三方提供了临时免费模型服务下线导致模型不存在用/models重新拉取模型列表换成有效的模型名升级到 2.0 后旧配置不生效配置字段变更重新运行opencode生成基准配置手动迁移自定义字段6.2 关于“opencode 套餐”和费用问题很多人问 opencode 收不收费、有没有套餐。opencode 本体是开源免费的你需要付费的只是底层模型 API 的调用费用。如果你用 Anthropic 或 OpenAI 的官方 API费用按 Tokens 计费用 OpenRouter 免费模型或本地 Ollama就接近零成本。没有所谓的“opencode 官方套餐”如果有人向你推销请谨慎判断大概率是套了一层壳的第三方服务。6.3 2.0 升级的关键变化如果你和我一样是从早期版本升上来的需要注意几个变化。2.0 重构了客户端架构TUI 界面响应更快新增了更清晰的 Agent 切换面板Skills 机制从实验性变成了一等公民记忆文件路径有调整旧的~/.config/opencode结构建议迁移到新格式插件生态也开始规范化VSCode、JetBrains 插件都同步更新了连接协议。升级后如果发现旧项目里 Agent 行为突然变了先检查AGENTS.md和.opencode目录是否被旧的流程覆盖必要时重新跑一遍/init生成适配 2.0 的说明文件。7. 什么情况下我依然会切回其他工具说了这么多 opencode 的优点最后讲点实在的个人感受也算给还在观望的朋友一个参考。opencode 并不是所有场景的银弹。如果你团队全员重度使用 IntelliJ 系 IDE习惯 Cursor 那种“代码块内联补全 对话改代码”的交互那直接给每个人都装终端 Agent 不一定合适学习成本和习惯冲突都真实存在。另外如果你的项目高度依赖专属 IDE 的智能索引比如大型 Java 工程的复杂重构opencode 的能力边界会明显它更适合做“读代码、解释、写测试、批量改小逻辑”这类事情而不是替代你思考整体架构。我现在的工作流是每天开机会打开 opencode 的桌面版挂在旁边日常改 bug、写单测、整理文档都交给它遇到需要大范围重写或跨模块协调的活儿我会切回 IDE 里的完整工具链。Claude Code 和 Codex 我也还在用opencode 胜在模型自由和开源透明但对 Anthropic 官方模型的原生调优深度仍然是 Claude Code 体验最顺。所以准确说不是选一个抛弃另一个而是让它们各自做最擅长的事。如果在配置过程中遇到某个具体报错最好把完整的错误信息连同 opencode 版本号贴给社区或翻一下官方 issue。这个项目更新频率很高很多坑在下一个版本就修掉了别卡在一个地方太久。
opencode实战指南：终端AI编码Agent安装、配置与高阶玩法
如果你最近和我一样被 Claude Code 和 Codex CLI 这类终端 AI 编码 Agent 搅得心痒痒那你大概率也刷到了opencode这个名字。它不是哪家大厂出的而是开源基础设施团队 SST 发起的一个项目主打开箱即用、多模型通吃。我把它当主力工具用了大概两个月期间经历了从 1.x 到 2.0 的升级踩了不少安装、配置、模型切换的坑也把 Skills、Memory、MCP 这些高阶玩法都试了一遍。这篇文章不是官方文档的翻译而是我基于实际项目操作记录的完整复盘从零开始讲清楚 opencode 是什么、怎么装、怎么配、怎么用到真实项目里最后附上高频问题排查表。我默认你是一个会用终端、跑过 Git 命令、接触过 AI 编程助手的开发者。如果你完全是新手也没关系前两部分我会把环境准备、安装路径、常见报错都写得很啰嗦照做就能跑起来。1. opencode 到底是什么为什么我又多装了一个终端工具1.1 从 Claude Code 和 Codex 说起终端 Agent 的爆发过去一年AI 编程助手从“编辑器里的补全插件”进化成了“终端里能自主干活的 Agent”。Claude Code 让 AI 直接读代码、跑命令、改文件Codex CLI 把 OpenAI 的模型能力塞进了命令行。这类工具的共同点是不需要图形界面AI 可以像人一样在项目目录里探索、执行测试、提交代码。但它们也各有痛点——有的只支持自家模型有的配置隐藏在 JSON 里有的想扩展第三方工具特别费劲。opencode 就是这个赛道里杀出来的一个“全家桶型”选手。它做对了三件事第一模型不绑定Anthropic、OpenAI、Google Gemini、OpenRouter、本地模型都能接甚至任何 OpenAI 兼容的服务都能配进来第二它把终端 TUI 界面做得相当舒服不是简单打印日志而是有交互面板、文件树、对话流第三它是真开源GitHub 上的 sst/opencode社区迭代速度极快插件机制、Skills 机制、内置浏览器调试都能用。1.2 opencode 的特殊定位不是大厂产品但是工程化社区的选择先说一个很多人问的问题opencode 是哪家公司的它是 SST 团队主导的开源项目。SST 这个团队之前在 Serverless 领域挺有名做了一套部署框架他们的技术审美很“工程化”写出来的工具通常文档清晰、CLI 体验好、默认配置合理。opencode 也是这种调性——装完之后第一次运行会让你选模型提供商然后自动生成配置文件不需要你去翻几十页文档。它的核心架构可以理解为一个用 Go/TUI 写的前端客户端 一套灵活的 Provider 适配层 可插拔的工具调用机制。你可以在里面跑 Agent 对话、让它操作文件、运行命令、搜索代码也可以让它调用外部 MCP 服务比如浏览器自动化、数据库查询。2.0 之后官方还加入了 TypeScript SDK 和更成熟的 Skills 机制基本向 Claude Code 的能力看齐甚至某些方面更好用。1.3 适合谁用终端党、多模型党、团队标准化需求我个人的体感是opencode 适合三类人长期泡在终端里的开发者习惯了 vim/neovim 或只是不想开 IDE 的轻量操作场景手头有多个模型 API公司采购的、自建的、第三方平台的想在一个工具里统一切换的人想给团队统一配置 AI 编码 Agent 行为的负责人因为 opencode 的配置文件是项目级的可以提交到 Git 仓库里成员 clone 下来就能用同一套规则。如果你现在的日常是 Cursor 重度用户倒也没必要立刻换但 opencode 作为终端补充工具配合插件体系完全能承担“写测试、修 bug、查文档、批量重构”这类脏活累活。2. 安装与第一跑通三步绕开最常见的坑2.1 环境准备Node.js 18、Git、一个终端opencode 的安装方式多种多样但无论哪种底层都依赖 Node.js 环境和 Git。Node.js 建议 18 以上我用的是 20 LTS。Git 必须有因为 Agent 执行 git diff、git commit 这些操作时底层就是调 git 命令。Windows 上建议直接装 Git for Windows它自带了一个 bash 环境很多奇怪的路径问题能少很多。检查命令我直接贴一下node -v git --version只要两个命令都有输出环境就算过关。如果 node 没有去官网下 LTS 版本即可这里就不赘述了。2.2 三种安装方式curl、npm、Homebrew 怎么选opencode 官方推荐用 curl 脚本一键安装curl -fsSL https://opencode.ai/install | bash这个脚本会把二进制放到用户目录下的特定位置同时打印出需要添加 PATH 的路径。目前在 macOS 和 Linux 上体验很顺。Windows 用户如果开了 WSL也建议直接在 WSL 里跑。我实际更常用的是 npm 安装好处是升级方便npm install -g opencode-ai注意包名是opencode-ai不是opencode。npm 源里有另一个不相关的包占了 opencode 这个名字官方包是这个带后缀的。如果你喜欢 Homebrew也有现成 formulabrew install sst/tap/opencode不管哪种方式装完先跑一下opencode --version确认。如果提示没找到命令优先检查 PATH。这一步是新手最高的报错来源我专门放到下一节讲。另外如果你以前装过 Go 环境网上老教程会写go install github.com/sst/opencodelatest。这条路在早期版本确实可以但现在官方发布物已经不太推这种方式了因为复杂依赖和 TUI 资源文件打包会导致 go 安装版本不完整。我建议直接用 curl 或 npm省事。2.3 Windows PowerShell 报“无法识别 cmdlet”怎么破这是搜索热词里出现次数最多的问题opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。本质原因只有一个可执行文件没有被系统找到。打开 PowerShell输入where.exe opencode如果没有输出说明安装路径不在 PATH 里。用 curl 脚本安装时它通常会装到%USERPROFILE%\.opencode\bin\opencode.exe或%LOCALAPPDATA%\opencode\bin之类的位置。解决办法是把对应目录加进 PATH$env:Path ;$env:USERPROFILE\.opencode\bin这一步只是当前会话有效。想让下次打开终端也生效需要设置用户级环境变量[Environment]::SetEnvironmentVariable(Path, $env:Path ;$env:USERPROFILE\.opencode\bin, User)然后完全关掉终端窗口再重新打开不要偷懒只开新标签页。PowerShell 对 PATH 的缓存有时会让人误以为没生效重启终端是最直接的验证方式。2.4 首次运行选 Provider 并完成登录安装成功后在任意项目目录下运行opencode第一次启动会进入引导模式让你选择要使用的模型提供商。常见选项有 Anthropic、OpenAI、Google、OpenRouter、Ollama 等。选了之后它会把对应的 API Key 写入配置文件后面会细讲然后你就进入交互式 TUI 界面了。这里我的经验是第一次别贪多先选一个最方便拿到的 key 跑通流程。比如有 Anthropic 账号就选 Anthropic没有就选 OpenRouter 注册一个免费账号用里面的免费模型也能体验全流程。等跑通了再去配置多个 Provider 来回切换。3. 模型接入与配置文件真正用起来的核心3.1 opencode.json一份配置管理多套模型opencode 的配置采用项目级优先的方式。运行opencode时它会自动查找当前目录的opencode.json找不到就往用户全局目录~/.config/opencode/opencode.json去找。项目级配置会被提交到 Git团队成员拉代码后自动共享。一个最基础的配置文件长这样{ $schema: https://opencode.ai/config.json, provider: { anthropic: { npm: ai-sdk/anthropic, name: Anthropic, options: { apiKey: {env:ANTHROPIC_API_KEY} }, models: { claude-sonnet-4-20250514: { name: Claude Sonnet 4 } } } }, model: claude-sonnet-4-20250514 }通常情况下你不用手写这么完整运行opencode后输入/models命令它会列出当前已经配置好的 Provider 和模型直接选就行。真正需要手写配置的场景是接入非标准的 API 服务或者想给模型自定义名称。3.2 免费模型怎么接OpenRouter 与本地 Ollama搜索热词里有个高频词是“opencode 免费模型”。这确实是 opencode 的一大优势——它不强绑付费 API。最常见的免费路径有两条。第一条OpenRouter。注册账号后生成 API Key然后在配置里添加{ provider: { openrouter: { npm: openrouter/ai-sdk-provider, name: OpenRouter, options: { apiKey: {env:OPENROUTER_API_KEY} }, models: { meta-llama/llama-3.3-70b-instruct:free: { name: Llama 3.3 70B Free } } } } }OpenRouter 的免费模型列表会变有些模型今天免费明天收费用/models刷新就能看到最新状态。它的优势在于模型丰富一个 key 能测很多不同的模型适合做横向对比。第二条本地模型 Ollama。如果你机器配置不错不想把代码发给任何第三方服务可以装 Ollama 拉一个模型起来ollama pull qwen2.5-coder:14b然后在 opencode 里添加 Ollama Provider{ provider: { ollama: { npm: ollama-ai-provider, name: Ollama, options: { baseURL: http://localhost:11434/api }, models: { qwen2.5-coder:14b: { name: Qwen 2.5 Coder 14B } } } } }本地模型的好处是隐私和免费缺点是能力和云端大模型差距明显。我建议用本地模型做小改、补全、简单解释代码复杂的架构设计、跨文件重构还是交给云端模型。3.3 ccswitch 这类切换工具多套配置如何并行实际用起来你会发现光靠 opencode 自带的/models切换配置管理有时还是不够优雅。尤其当你手上同时有公司内网服务、个人付费 API、临时测试的中转 key 时频繁改环境变量很痛苦。这时候社区流行的做法是配一个ccswitch之类的切换工具。这类工具统一管理多个 AI 工具Claude Code、Codex CLI、opencode的配置切换时自动改写对应工具的配置文件。比如你运行ccswitch use work它会把 opencode.json 里的 provider 全部替换成公司那套服务还会同步设置好环境变量文件。这种“工具再套工具”的方案听上去复杂但实际体验很爽。我个人的配置习惯是每个场景建一个独立的 profile里面写好该场景的 provider、model、环境变量然后通过 ccswitch 一键切换再也不用手动备份和覆盖配置文件。3.4 环境变量与自定义端点没有模板也能跑通接入第三方服务时最怕的是目标服务兼容 OpenAI 格式但 base URL 不确定。opencode 的 provider 配置给了你很大自由度只要服务兼容 OpenAI 接口你可以手动指定{ provider: { custom: { npm: ai-sdk/openai-compatible, name: My Custom API, options: { baseURL: https://your-api-endpoint.example.com/v1, apiKey: {env:CUSTOM_API_KEY} }, models: { your-model-name: { name: Your Model Name } } } } }注意npm用的是ai-sdk/openai-compatibleopencode 依赖 Vercel AI SDK这套 provider 机制本质上就是 AI SDK 的 provider 体系。理解了这一点你就能明白为什么它接模型这么灵活。环境变量引用用{env:xxx}的写法好处是 API Key 不会出现在配置文件里适合把配置文件提交到 Git 仓库。我把项目级配置提交到仓库后团队成员只要各自设置环境变量就能跑同一套 Agent 规则。4. 把 opencode 真正用到项目里Agent、Skills、Memory4.1 接手一个老项目的正确打开方式搜索热词里有“opencode 接手开发项目”这是个特别好的场景。我最近用 opencode 接手了一个遗留的 Java Maven 项目代码量十几万行模块依赖复杂老成员留下的文档基本等于没有。我的做法是三步走第一步先让 opencode 读项目结构输入指令/init它会生成一个 AGENTS.md 文件记录项目的技术栈、构建命令、目录约定、测试方式。这个文件相当于给 Agent 的“入职手册”之后每次对话它都会自动参考。对于老项目我建议手动补充这个文件把已知的坑、特殊配置都写进去。第二步让 Agent 跑一遍构建流程请先看一下项目的 pom.xml跟我说清楚这是一个什么项目然后帮我跑 mvn compile 试试注意要明确告诉它先“看”再做避免它上来就大改。opencode 在终端里执行命令前会显示将要运行的命令按 y 确认后才会执行所以就算它想乱跑你有机会拦截。第三步拆任务。老项目代码维护最大风险不是 AI 不会写而是 AI 改完不知道影响范围。我通常要求它每改一个模块就执行对应的单元测试并且把改动按文件粒度拆成多个 commit。在 opencode 里可以直接说“修改完成后分别对 A 模块和 B 模块运行 mvn test通过了再提交”它会一步步执行过程透明可控。4.2 多 Agent 工作流与权限控制很多终端 Agent 工具是单线程的一个对话一个 Agent 全程操作。opencode 在这方面更灵活你可以在 TUI 里输入/agents查看和切换不同的 Agent 实例。比如我跑前后端联调时会让一个 Agent 专看前端逻辑另一个 Agent 查后端接口然后我把两个 Agent 的结论汇总到主对话里。权限控制体现在文件规划和命令确认上。opencode 支持在配置里自定义 Agent 的权限规则比如禁止 Agent 执行rm -rf、禁止修改package-lock.json、只允许在src/目录下写文件。这类规则写在配置文件的permission字段里{ permission: { deny: [ rm -rf, git push ], allow: [ mvn test, npm test, git add, git commit ] } }这个功能在团队场景尤其重要。新人不熟悉仓库时经常一句话让 Agent 乱跑命令权限规则可以兜底。4.3 Skills 技能扩展把 Claude Code 生态迁移过来opencode 的Skills机制是我最喜欢的特性。简单说Skills 是一组预置的指令和提示词放到项目目录的.opencode/skills/下Agent 遇到对应场景会自动加载。它的灵感来自 Claude Code 社区的 skills 实践但 opencode 做了更规范化、更易写的实现支持 Markdown 或 JS/TS 格式。一个最简 Skill 长这样--- name: unit-tester description: 当用户要求写单元测试时自动使用此 skill --- 先分析源文件的依赖关系然后针对每个 public 方法生成对应的测试文件。 测试文件放在与源文件相同的目录下命名规则为 原文件名.test.ts。 运行测试命令前先检查依赖是否安装。把这个文件放在.opencode/skills/unit-tester/SKILL.md并在配置里启用 skills 目录Agent 就会在相关场景下自动读取这段说明改变它的行为。我知道不少人在 Claude Code 里用的是 “superpowers” 这类技能合集那套体系里有很多精心打磨的 skill 文件。迁移到 opencode 是可行的因为技能本质上是提示词加规则把.claude/skills/下的 Markdown 文件复制到.opencode/skills/再做少量格式调整即可。opencode 社区也有脚本能自动转换我自己手动迁移过两次成本很低。真正值钱的其实是那些规则文本不是存放它们的文件夹。4.4 Memory 记忆让 Agent 记住项目约定与偏好AI 编码 Agent 最气人的一点是今天告诉它的约定明天可能就忘了。opencode 提供了一个规范化的记忆机制配置项里可以设置全局记忆文件和项目记忆文件。默认情况下全局记忆在~/.config/opencode/memory.md项目记忆在.opencode/memory.md。它的工作方式是这样的每次会话开始时Agent 会读取这些记忆文件作为上下文会话过程中如果发现需要记录新的约定可以直接要求它“把这个规则记到 memory”它会主动更新对应文件。我用了一段时间后项目记忆里积累了不少有价值的内容比如“不要修改公共 API 的返回结构除非通过新增参数方式兼容”“部署分支是 release不要直接推 main”。配合 AGENTS.md 使用效果更好。AGENTS.md 偏向项目的静态事实memory.md 偏向动态经验。前者可以提交到 Git 仓库给所有人共享后者可以只在本地维护。当然你也可以都提交看团队习惯。4.5 用 Playwright 驱动前端 bug 排查再讲一个搜索热词里出现过的具体场景“opencode playwright 怎么测试前端 bug”。这在之前的版本里要自己配置半天现在 opencode 2.0 自带了浏览器调试工具通过 MCP 协议接入了 Playwright 自动化能力。实测流程是这样的在 opencode 的对话里直接说“打开浏览器访问本地 5173 端口打开页面后点击登录按钮看看控制台有没有报错”。Agent 会自动启动一个 Playwright 驱动的浏览器实例执行点击、输入、截图、读取控制台日志等操作然后把结果反馈到你面前。我遇到过一个很隐蔽的前端 bug某个弹窗组件在特定分辨率下不会正常弹出单纯看代码很难定位。我让 opencode 用 Playwright 打开页面把视口改成 1366x768点击触发按钮它通过截图和控制台日志帮我确认了问题出在 CSS 媒体查询和弹窗挂载时机冲突。整个排查过程几分钟搞定比我手动开 devtools 快很多。5. 编辑器与桌面端不止是黑窗口5.1 VSCode 插件边看代码边对话虽然 opencode 主阵地是终端 TUI但官方提供了 VSCode 插件扩展 ID 可以搜 “opencode”。安装后编辑器左侧会多一个面板能直接基于当前打开文件发起对话、查看 opencode 正在执行的命令、浏览 Agent 产生的 diff。这个插件适合在“需要边看代码边指挥 Agent”的场景。我用 VSCode 插件时最顺手的是把 opencode 作为“代码解释器”选中一段不熟悉的代码右键选择“用 opencode 解释”它会把解释结果输出到侧边栏不用切到终端去问。这比传统的人工去翻调用链效率高很多。当然有个前提VSCode 插件本质上是 opencode CLI 的壳你必须先保证opencode命令能在系统终端里直接运行插件才能正常连接到核心进程。5.2 JetBrains IDEA 插件与 Maven 项目配置搜索热词里还有 “opencode jetbrains idea 插件” 和 “opencode mvn 配置”这俩是连在一起的。官方确实有 JetBrains 插件支持 IntelliJ IDEA、PyCharm、WebStorm 等基于 IntelliJ 平台的 IDE。插件用法和 VSCode 版类似安装后会在右侧打开一个 opencode 工具窗口。对于 Maven 项目的配置我的建议是不要把 Java 构建交给 AI 自由发挥而是事先在 opencode 配置里把常用 Maven 命令写成快捷方式。比如在配置文件中自定义一个 agent 指令{ agent: { mvn-test: { prompt: 对当前 Maven 项目执行 mvn test只汇报测试失败项不要修改任何代码 } } }这样每次只要输入/agent mvn-test它就只干活不乱动。Java 项目构建时间长Agent 在执行命令时如果超时需要调大 TUI 里的超时时间或手动延长命令等待这个我放在常见问题里讲。5.3 桌面版与内置 UI 日志opencode 桌面版是后来才有的适合不喜欢终端交互的人。它能以桌面应用方式运行相当于把 TUI 界面平移到了独立窗口里同时增加了日志查看面板。如果你在 IDE 插件和终端之间切换觉得割裂桌面版可以考虑作为中转站。我实际使用经验是桌面版的价值主要体现在两点一是进程崩溃时能直接看到底层日志不用去终端里翻二是可以同时开多个项目窗口每个项目一个 Agent 会话互不干扰。终端里同时开多个 opencode 会话也能做到但窗口管理没桌面版直观。6. 高频问题排查与配置速查6.1 常见报错对照表这些是我在各大社区里看到以及自己踩过的坑整理成表方便查阅现象原因解决方案PowerShell 提示无法识别 opencode安装路径不在 PATH手动添加路径到用户环境变量重启终端运行后提示unexpected server error. check server logsAPI Base URL 不可达 / 环境变量过期 / 配置了不存在的模型名检查 provider 的 baseURL 是否能正常访问确认 API Key 是否有效用/models重选模型接入第三方服务后一直 401API Key 错误或环境变量没加载检查{env:XXX}变量是否已设置必要时用echo $env:XXX验证执行 mvn test 一直卡住不返回Maven 构建超时设置太短加大 opencode 里命令超时时间或改用后台执行后读取文件确认结果切换模型后对话历史错乱不同模型上下文格式差异大在 TUI 输入/new清空会话或者/compact压缩上下文Agent 修改文件后 git diff 出现全量变更行尾符CRLF/LF不一致在项目根目录加.gitattributes固定行尾符并在 AGENTS.md 中写明hy3-free 这类模型标签无法使用第三方提供了临时免费模型服务下线导致模型不存在用/models重新拉取模型列表换成有效的模型名升级到 2.0 后旧配置不生效配置字段变更重新运行opencode生成基准配置手动迁移自定义字段6.2 关于“opencode 套餐”和费用问题很多人问 opencode 收不收费、有没有套餐。opencode 本体是开源免费的你需要付费的只是底层模型 API 的调用费用。如果你用 Anthropic 或 OpenAI 的官方 API费用按 Tokens 计费用 OpenRouter 免费模型或本地 Ollama就接近零成本。没有所谓的“opencode 官方套餐”如果有人向你推销请谨慎判断大概率是套了一层壳的第三方服务。6.3 2.0 升级的关键变化如果你和我一样是从早期版本升上来的需要注意几个变化。2.0 重构了客户端架构TUI 界面响应更快新增了更清晰的 Agent 切换面板Skills 机制从实验性变成了一等公民记忆文件路径有调整旧的~/.config/opencode结构建议迁移到新格式插件生态也开始规范化VSCode、JetBrains 插件都同步更新了连接协议。升级后如果发现旧项目里 Agent 行为突然变了先检查AGENTS.md和.opencode目录是否被旧的流程覆盖必要时重新跑一遍/init生成适配 2.0 的说明文件。7. 什么情况下我依然会切回其他工具说了这么多 opencode 的优点最后讲点实在的个人感受也算给还在观望的朋友一个参考。opencode 并不是所有场景的银弹。如果你团队全员重度使用 IntelliJ 系 IDE习惯 Cursor 那种“代码块内联补全 对话改代码”的交互那直接给每个人都装终端 Agent 不一定合适学习成本和习惯冲突都真实存在。另外如果你的项目高度依赖专属 IDE 的智能索引比如大型 Java 工程的复杂重构opencode 的能力边界会明显它更适合做“读代码、解释、写测试、批量改小逻辑”这类事情而不是替代你思考整体架构。我现在的工作流是每天开机会打开 opencode 的桌面版挂在旁边日常改 bug、写单测、整理文档都交给它遇到需要大范围重写或跨模块协调的活儿我会切回 IDE 里的完整工具链。Claude Code 和 Codex 我也还在用opencode 胜在模型自由和开源透明但对 Anthropic 官方模型的原生调优深度仍然是 Claude Code 体验最顺。所以准确说不是选一个抛弃另一个而是让它们各自做最擅长的事。如果在配置过程中遇到某个具体报错最好把完整的错误信息连同 opencode 版本号贴给社区或翻一下官方 issue。这个项目更新频率很高很多坑在下一个版本就修掉了别卡在一个地方太久。 
