1. 从一个终端窗口说起opencode 到底是什么如果你最近在逛 GitHub 或技术社区应该不只一次刷到过opencode这个名字。我是一个每天要在终端里待八小时以上的人IDE 用的频率反而不如 shell 高所以当看到又一个AI 编程助手出现时第一反应是又来一个套壳 CLI但实际用了一周之后我承认这个判断下早了。opencode 是一款开源的 AI Agent 编程工具以终端 TUI 为主要交互界面核心能力是让 AI 直接读写项目文件、执行命令、跑测试、改 bug甚至自己规划多步开发任务。它跟你熟悉的 Claude Code、Codex CLI 属于同一类产品但有几个很明显的差异点完全开源、模型无关可以接多家模型服务、本地配置优先、插件生态扩展性强。这篇文章我会以实操为主把安装、配置、模型接入、核心功能Skills、Memory、终端内测试、IDE 插件、以及和 Codex / Claude Code / Pi 的横向对比都聊一遍。写的时候默认你用过终端、知道 npm 或者 Go 的基本概念但没接触过任何 Agent 编程工具——我尽量让两类读者都能从中拿到能直接用的东西。先放结论如果你需要的是一个不锁定厂商、能在终端里完成从读代码到改代码全流程的 AI 助手opencode 目前是很值得投入时间去配置的那一个。下面我们从安装开始一步步拆。2. 安装与项目概览从零把 opencode 跑起来2.1 项目背景与核心设计思路opencode 最初源自社区开发者对于终端 AI Agent 应该更开放的诉求。它不像某些商业产品那样要求你必须使用特定模型、特定登录方式而是把模型接入层做成了可插拔的结构。你可以在配置里指定不同服务商的 API也可以接入本地模型这让它天然比闭源方案多了一层灵活度。我在排查它源码结构的时候发现它的核心代码其实大量借鉴了 Claude Code 的交互模式终端里的流式输出、工具调用确认、多文件编辑等但在架构上做了更模块化的拆分。这也解释了为什么社区里很多人称它为 开源的 Claude Code 替代品——它有那个味道了但底层设计思路是完全不同的。它的主要定位有三类用户日常重度依赖终端的开发者希望把 AI 编程能力塞进现有工作流。有模型选择洁癖的人不想被单一厂商绑定或者本来就有自建模型网关。需要细粒度控制 AI 行为权限、脚本、工具链的团队或独立开发者。2.2 安装选择npm、curl 脚本与 Go 版本opencode 官方提供了多种安装方式这里我只讲我实测过的三种按推荐度排序第一种npm 全局安装推荐npm install -g opencode-ai注意包名是opencode-ai不是opencode。我刚装的时候直接搜opencode装到了一个同名无关包浪费了几分钟。装完之后终端里跑opencode --version验证是否能正常输出版本号。我的环境是 Node 20.11实测没有任何依赖冲突。如果你用的是旧版本 Node低于 18大概率会报语法错误建议先升级 Node 环境。第二种官方安装脚本curl -fsSL https://opencode.ai/install | bash这个适合不想通过 npm 管理全局工具的场景。脚本会自动检测操作系统架构把二进制装到~/.opencode/bin并在 shell rc 文件里写入 PATH。相对 npm 版本这个二进制包体积更小、启动速度也稍快一点。第三种Go 版本对应opencode go热词go install github.com/opencode-ai/opencodelatest这个版本其实是同一个项目的 Go 实现性能表现更好内存占用明显比 Node 版低官方定位是高性能迭代版。如果你平时用 Go 工具链直接上这个。两个版本的数据目录和配置文件格式是共通的从 npm 版切到 Go 版不需要重新配置任何模型。注意无论哪种方式装完第一次运行前建议先检查~/.opencode或~/.config/opencode目录是否存在。它会存放全局配置和会话数据。如果你有洁癖可以提前看一眼里面都有什么内容避免后续卸载不干净。2.3 验证安装与首次启动跑通安装只是第一步关键是确认它能不能正常对话。在任意目录执行opencode会进入交互式 TUI 界面底部有输入框。如果直接输入你好它大概率会提示你还没配置模型。这时候先按CtrlC退出我们接着配置模型服务。这里要纠正一个常见的误解很多人以为opencode自带模型实际它必须依赖外部模型 API 或本地模型服务。它本身是一个客户端 Agent 调度器模型能力全部来自你配置的服务端点。理解这一点之后配置模型的思路就清晰了。opencode项目本身就是这个问题很好的一个答案与其让每个开发者重复搭一套终端 AI Agent的轮子不如把调度、工具调用、权限控制这些通用部分做扎实把模型选择完全交给用户。3. 模型接入与 config 配置把你的 API Key 接进来3.1 支持哪些模型服务商这是 opencode 最有吸引力的部分之一也是搜索热词里opencode 免费模型opencode 配置出现频率最高的原因。opencode 原生支持的服务商包括AnthropicClaude 系列、OpenAIGPT 系列、Google Gemini、Mistral、Ollama本地模型、以及任何兼容 OpenAI API 协议的自建端点。你可以在配置里同时配多个服务商会话内通过命令随时切换模型。内核的 provider 抽象层做得比较干净官方用一句话描述就是 Bring Your Own Key自备密钥。在我的实际测试中OpenAI 系的模型接入是最顺滑的因为协议生态最成熟Anthropic 系在工具调用准确率上表现最好这可能也是社区里 Claude Code 用户迁移过来后觉得手感最接近的原因。3.2 配置文件的正确写法配置文件位置分两级全局的在~/.config/opencode/opencode.json项目级的在你项目根目录下也叫opencode.json。后者的优先级更高——这个设计很实用不同项目可以用不同模型或不同 system prompt。最简配置大概长这样{ $schema: https://opencode.ai/config.json, provider: { openai: { apiKey: sk-xxxx, model: gpt-4o } }, model: openai/gpt-4o }但实际建议不要把 apiKey 直接写进配置文件更稳的做法是通过环境变量传入export OPENAI_API_KEYsk-xxxx然后在opencode.json里只声明服务商和模型名{ $schema: https://opencode.ai/config.json, provider: { openai: { model: gpt-4o, apiKey: {env:OPENAI_API_KEY} } }, model: openai/gpt-4o }这个{env:VAR_NAME}的写法是 opencode 支持的变量替换语法强烈建议用。好处是我可以把这个配置文件直接提交到 Git 仓库而不用担心密钥泄露换台机器只需要重新设置环境变量即可。3.3 多模型切换与优先顺序配好多个 provider 之后TUI 输入框内可以直接用/models命令列出所有可用模型用方向键切换。如果你在配置文件里同时配了codex和claude切换之后当前会话的上下文会保留——这点实测很舒服不用开新会话就能对比两个模型的回答质量。关于opencode 免费模型这个词我得提醒一句它指的是接入社区提供的免费模型端点或者本地模型如通过 Ollama 跑 Qwen、Llama 等开源模型而不是 opencode 官方提供免费额度。我实测过通过 Ollama 接入本地模型配置非常简单{ provider: { ollama: { model: qwen2.5-coder:14b } }, model: ollama/qwen2.5-coder:14b }只要本地 Ollama 服务在跑opencode 就能直接用。我还用 ccswitch 配合 opencode 做过配置管理多套 API 配置之间的切换确实方便很多这个后面单独说。4. 核心功能实测Skills、Memory 与终端里跑测试4.1 Skills给 AI 注入自定义技能包这是opencode skills热词指向的核心功能。简单理解Skills 是一组预定义好的指令、提示词和工具调用模板让 AI 在特定场景下表现得像专精这个领域的助手而你不需要每次对话时重复描述背景。实际操作是在任意目录下创建~/.config/opencode/skills/每个技能包是一个文件夹里面至少需要一个SKILL.md文件。举个例子我写了一个用于前端组件审查的技能包--- name: frontend-review description: 审查前端 React 组件的代码质量、性能隐患和可访问性 --- 当用户要求审查组件时你需要 1. 先定位目标组件文件 2. 检查 props 设计和组件拆分合理性 3. 找出不必要的 re-render 4. 检查键盘导航和 aria 属性 5. 输出结构化审查报告保存后在 opencode 对话中输入/skills能看到所有已加载的技能选中技能之后再描述需求AI 就会按照技能包里的行为模式来执行。实际体验上这相当于把提示词工程固化成了可分发、可版本管理的文件包。我还发现 Skills 的优先级设计很合理如果当前请求匹配了某个技能的 description它优先走技能包的指令如果完全不匹配就回落到普通对话模式。这意味着你不用担心技能包污染日常使用场景。注意技能包不要命名太泛比如coder这种描述会让所有请求都尝试命中它反而降低灵活度。命名越具体触发越精准。4.2 Memory跨会话记住你的偏好opencode memory解决的问题很实在传统 AI 编程助手每次会话都是失忆的你的命名习惯、代码风格、常用命令每次都要重新描述一遍。opencode 的 Memory 机制就是把重要偏好写到本地归档中后续会话自动调用。通过/memory命令可以查看当前记忆内容。实际使用中我会主动告诉它几个关键偏好比如测试文件放在__tests__目录而不是test目录缩进用空格不用 Tab不要动package.json中的依赖版本。之后每次会话它都会依据这些记忆执行任务踩雷率明显下降。记忆存储逻辑在我实测中比较朴实显式写入的内容会长期保留对话中自动产生的短期记忆会周期性归档。它不是 AI 自动总结那么智能但好处是可控——你可以随时进去把不需要的记忆删掉。4.3 Playwright 与前端 Bug 修复热词里有一个很典型的场景opencode playwright 怎么测试前端 bug。这是我在本地复现最成功的一个功能值得详细讲。opencode 内置了对浏览器自动化工具的支持默认集成了 Playwright。你可以让 AI 自己打开浏览器、访问本地开发服务器、与页面交互然后把报错信息带回来分析修复。实际流程大概是在 opencode 对话中描述 bug比如登录按钮点击后没反应打开控制台看下报错。AI 会调用浏览器工具启动一个真实的 Chromium 实例。它自己打开页面、点击按钮、读取 console 日志。日志中的错误会进入它的分析上下文然后它主动读取相关源码文件定位问题。定位完成后它给出修复建议并询问是否直接修改。我第一次看到它在浏览器里自动点按钮的时候说实话有点发毛——这个能力在真实场景下的效率提升太大但如果你不做权限控制风险也同步放大。所以下面这条务必记得浏览器相关操作默认要在会话中确认不要开全自动模式跑生产环境地址。4.4 会话模式与权限控制opencode 支持三种操作模式自动模式全自动执行所有工具调用、普通模式关键操作需人工确认、以及只读模式只看不改。日常开发建议用普通模式让它在改文件前征求同意。自动模式适合跑测试、批量格式化这种低风险操作。实操中我发现的比较实用的是模式切换命令/mode它会显示当前模式和可切换的选项用方向键切换即可。我在跑大规模重构时切到普通模式每步都审跑测试时会临时切到自动模式。5. 多端扩展VS Code、IDEA 与桌面版5.1 VS Code / Cursor 插件vscode opencode 插件和opencode vscode指向的是同一个东西官方 VS Code 扩展。安装方式很简单在 VS Code 扩展市场搜索 opencode。安装后左侧会出现 opencode 的面板图标。面板里会显示当前项目的会话列表也可以直接发起新会话。我用下来的体验是VS Code 插件更适合做这样一件事选中代码片段右键选择Send to opencode把选中内容作为上下文发送给终端里正在运行的会话。这个配合方式比在两个窗口之间手动复制粘贴效率高很多而且保持单一会话上下文AI 对项目的理解不断层。插件本身不自带终端它是毛刺玻璃式的面板形态。如果你需要代码中嵌着 TUI 的体验可以用 VS Code 的集成终端直接在项目根目录启动 opencode——这种用法我个人更推荐因为 TUI 界面在终端里的渲染效果目前没有任何 GUI 面板能替代。5.2 JetBrains IDEA 插件IDEA 插件与 VS Code 版功能相似但安装路径不同打开 Settings → Plugins → Marketplace搜索 opencode 安装即可。有个细节值得注意IDEA 插件在我本地的内存占用比 VS Code 版略高如果你同时开着多个 IDEA 窗口和 opencode 服务注意一下系统资源。插件支持把选中代码和当前打开文件路径发送给会话AI 定位问题时可以直接通过路径找到对应文件减少因为上下文不足导致的乱猜文件问题。5.3 桌面版与 TUI 的关系热词里还有opencode 桌面版。目前官方的主推交互依然是终端 TUI桌面版更像是一个带 GUI 外壳的封装底层仍然是同一个 Agent 核心。我的建议是不要把它当成主力方式——至少在 TUI 体验已经很成熟的前提下GUI 版并没有体现出不可替代的优势。等它把可视化会话管理和多项目切换做得更顺手之后再迁移也不迟。6. 常见问题与排查技巧实录6.1 Windows 下 无法将 opencode 项识别为 cmdlet... 报错这个报错在搜索热词里出现得非常典型opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称原因只有一个系统 PATH 环境变量没有包含 opencode 的安装目录。解决步骤找到 opencode 实际安装路径npm 全局安装一般会在C:\Users\你的用户名\AppData\Roaming\npm。按Win R输入sysdm.cpl打开环境变量设置。在用户变量的Path中添加上述路径。重新打开终端执行opencode --version验证。如果你用的是 curl 脚本安装路径一般在%USERPROFILE%\.opencode\bin同样加到 Path 里。改完环境变量一定要重开终端否则当前会话不会刷新。6.2 unexpected server error 排查另外一条高频报错是Error: unexpected server error. Check server logs for more details.我排查这个问题的经验是90% 的情况出在模型 API 端点不稳定或配置参数不匹配上。依次做这几件事先确认 API Key 是否有效在终端里用 curl 直接请求一次模型 API看是否返回 200。检查 opencode.json 中的 model 名拼写是否与服务商提供的模型 ID 完全一致。查看日志opencode的日志文件在~/.local/share/opencode/log/tail 最后几十行通常能直接看到 4xx/5xx 的具体原因。我遇到过多次实际案例是模型服务端临时限流等待几分钟后自动恢复。如果日志里显示429大概率是限流或余额问题。6.3 常见问题速查表问题可能原因解决方案opencode 命令找不到PATH 未配置检查安装路径并添加至 PATH对话无响应模型 API Key 无效检查环境变量和配置文件工具调用权限不足Sandbox 权限限制调整权限配置或在高级模式启用输出内容截断上下文过长清理对话上下文或减少文件读取范围连接服务失败代理配置冲突检查终端代理设置与网络策略6.4 几个值得记住的避坑技巧技巧一本地优先原则尽量把所有配置写在项目级opencode.json里这样换项目时配置能跟着走不会污染全局。配置文件里不要写死 API Key。技巧二用/compact压缩上下文当对话很长导致模型开始忘事时用/compact命令压缩上下文。它会把当前对话的核心信息提炼出来然后开启新的上下文窗口。这个命令我几乎每天都会用比新建会话省事得多。技巧三测试环境跑自动化即便 opencode 的 Playwright 集成很好用也不建议在没加防护的真实业务环境里跑全自动浏览器操作。我的习惯是先用localhost开发环境验证脚本确认无误后再考虑其他地方的风险。7. 主流终端 Agent 工具横向对比opencode、Codex、Claude Code 与 Pi这个话题在热词里出现了好几次opencode codex claude codeopencode codex pi 哪个 agent 好用我正好四个都用过一段不短的时间可以给出一些直观感受。维度opencodeClaude CodeCodex CLIPi开源是否否是模型灵活性高任意 OpenAI 兼容端点低绑 Claude低绑 OpenAI中支持多种工具调用能力强文件、命令、浏览器强中中配置复杂度中文件驱动低低中TUI 体验流畅最流畅尚可一般插件生态社区活跃Skills 机制官方 Skills无有限单说编码能力的绝对值Claude Code 在复杂项目上的理解力和推断力目前还是第一梯队但它的封闭生态让很多动手能力强的人不太舒服。Codex CLI 跟 OpenAI 生态绑得最紧如果你主要用 GPT-5 或未来更新模型它是省事的选择。Pi 的定位更像一个极简版的 Agent CLI完成小任务足够面对复杂项目时工具链不够丰富。opencode 的优势在于它把开源、多模型、工具扩展这三点做到了同一个产品里而且社区迭代速度极快。论哪个 agent 好用没有绝对答案因为绑定了你的模型偏好和项目类型——但如果你追求的是我现在用着舒服将来还能灵活换opencode 会是我优先推荐的一个选项。8. 作为项目接手者如何使用 opencode热词里有个opencode 接手开发项目这个方向很值得单独聊。因为我之前接手一个老项目时主要靠人工翻代码后来走通了一套用 opencode 快速上手新代码库的路径。第一步在项目根目录启动 opencode给它一句很宽的指令读一下README.md、package.json/go.mod、以及入口文件总结这个项目的功能模块、技术栈和启动方式。第二步根据它的总结追问具体的模块用户认证这块是怎么实现的这个数据库表结构在哪里定义。它会顺着文件依赖逐步展开效率比人肉看代码高很多。第三步跑测试让 Bug 现身——带它跑一遍测试过程中让它把失败用例跟对应源码关联起来。这套流程的空闲命中率高因为 opencode 的工具调用权限设计让它可以自己读文件、执行命令、搜索关键词完全模拟了一个有 IDE 权限的同事。如果配合 Memory 使用它还能记住这个项目的结构特点后续会话不用反复重新讲。这里有一个心得接手老项目时别指望 AI 一次把整个代码库讲完那样上下文很容易爆掉。最佳策略是按模块分批喂每轮聚焦一个业务闭环比如登录 → 鉴权 → 会话管理。9. 给新手的最后建议从安装到熟练使用我大概花了两三天。如果你只记住三件事我希望是这三件第一opencode 不是一个开箱即用的成品软件它是一套需要你花点时间配置的AI Agent 工作台。前期投入主要在模型接入和 Skills 配置上后续回报很稳定。第二先小范围试点再慢慢扩展它的权限范围。我今天敢让它直接改文件、跑浏览器是因为我已经摸清了它的行为模式。新手一上来就全自动引导很容易因为权限失控把项目搞乱。第三关注社区版本更新。opencode 的迭代频率很高每周基本都有新功能或性能优化。我用 npm 版的时候经常顺手npm update -g opencode-ai保持版本不落后。如果你之前一直在用 Claude Code 或 Codex想找一个不绑死模型、可定制性更强的替代品opencode 会是接下来一年值得长期关注的方向。按我个人的使用习惯它现在已经是我终端工作流里最常用的一个 TUI 应用而且在可见的未来还会继续占据这个位置。