最近技术圈里 AI 编程助手的热度一直没降Claude Code、Codex CLI 这些名字大家都不陌生但如果你想找一个更开放、更自由的选择那一定要看看 opencode。它是一个开源的终端 AI 编程助手用 Go 写的核心支持接入多种模型服务既能交互式聊天也能跑自动化脚本还被做成了 VSCode、IDEA 插件和桌面版。我大概用了半年从最开始装来尝鲜到后来真的把它用进代码审查、老项目接手、前端回归测试这些日常环节体验下来确实省了不少事。这篇就当一份 opencode 的实战笔记把安装、模型配置、Skills、Memory、LSP、编辑器集成这些点串起来再把报错汇总成一份排查表争取让新手少走弯路。1. opencode 是什么和 Claude Code、Codex CLI 对比后的选择1.1 定位一个跑在终端里的开源 AI 编码助手opencode 本质上是一个懂代码的 AI 对话入口它跑在终端里启动后会进入一个交互式界面TUI你可以在里面直接让 AI 读代码、改代码、跑命令、查报错也可以给它一个完整任务让它自动执行。它和你平时用的 ChatGPT 网页版最大的区别在于它天然生存在你的项目上下文里能直接读取当前仓库的文件结构、代码内容、Git 状态操作结果实时可见改完的文件直接落在磁盘上不需要你像传统聊天机器人那样反复复制粘贴代码。有一点值得单独说opencode 2.x 之后的架构改成了客户-服务端模式。opencode serve负责在本地起一个服务端终端 TUI、编辑器插件、桌面版都作为客户端连到同一个服务端上。这意味着你在 VSCode 里起的会话可以接着在终端里继续聊上下文是共享的。这个设计一开始我还觉得多此一举用久了才发现它其实是 opencode 能同时支持这么多前端形态的根本原因。1.2 为什么选它多模型、开源、Go 底层的差异点我身边经常有人问Claude Code、Codex CLI、opencode 到底选哪个。这个问题没有标准答案但可以列一张表看清楚差异对比项opencodeClaude CodeCodex CLI是否开源完全开源闭源开源支持的模型多家 自定义 Provider仅 Claude 系列以 OpenAI 系列为主核心实现Go闭源实现Node/TypeScriptSkills/扩展支持支持有限客户端形态TUI / 插件 / 桌面终端为主终端为主适合人群多模型切换、喜欢折腾Anthropic 生态重度用户OpenAI 生态重度用户我个人的使用感受是opencode 最大的优势不是某一个功能多强而是不锁死。今天想用 Anthropic 的 Claude明天想切到国产模型后天想在破电脑上接个本地模型它都支持。用 Go 写核心也带来一个很实在的好处单一二进制文件启动速度快跨平台分发简单不像 Node 系工具那样偶尔还要操心依赖版本。另外opencode 的run非交互模式也很实用。你可以直接在命令行里跑opencode run review git diff它会在不进入 TUI 的情况下执行任务并输出结果非常适合作 CI 辅助或者简单的脚本调用。这是我在实际工作中用得最频繁的功能之一。2. opencode 安装教程三个平台的一路踩坑记录2.1 macOS 和 Linux 的一行命令安装macOS 和 Linux 用户是最省心的官方提供了安装脚本curl -fsSL https://opencode.ai/install | bash如果你用 Homebrew也可以走 brew 路线brew install sst/tap/opencode我个人的建议是优先用安装脚本因为 brew 仓库里的版本偶尔会滞后而 opencode 迭代速度很快新版本往往会修掉一些老版本在 TUI 交互上的小毛病。如果你在公司内网环境不方便跑脚本直接去 GitHub Releases 页面下载对应平台的可执行文件也能用Linux 下记得下载后执行chmod x opencode再放到/usr/local/bin下。2.2 Windows 下“无法将 opencode 识别为 cmdlet”的解决办法Windows 用户最常见的报错就是搜索引擎里经常出现的那条无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这句话翻译成人话就是PowerShell 在系统的 PATH 环境变量里找不到 opencode 这个命令。它不代表你安装失败而是装了但没被系统找到。最常见的场景是用 npm 全局安装之后没有把 npm 的全局目录加进 PATH。解决办法分几步走先确认安装是否成功在 PowerShell 里跑一次npm ls -g opencode-ai能看到版本号说明已经装上了。然后查看 npm 的全局安装目录npm config get prefix把上面输出的路径加入系统 PATH打开系统属性 → 环境变量 → 系统变量 → Path → 新建填入类似C:\Users\你的用户名\AppData\Roaming\npm这样的路径然后保存。关掉当前 PowerShell 窗口重新打开一个新的再执行opencode --version。如果还识别不了那就别折腾 npm 了直接下载 Windows 安装包或独立 exe把可执行文件放到一个目录里手动把这个目录加进 PATH 就行。这个报错本身不复杂但非常劝退新手所以我单独拿出来讲。其实只要记得改完 PATH 必须重开终端这个原则Windows 下很多工具的报错都能自己解决。2.3 安装后怎么确认环境没问题装好之后先跑一条最基础的命令opencode --version能看到版本号输出就说明可执行文件没问题。接着直接敲opencode回车进入交互界面。第一次启动时它会让你选择模型提供商如果手头还没有任何 API Key可以先选一个免费的或者直接退出先看配置文件怎么写下一节详细讲。还有一个小细节如果你是通过 npm 安装的建议留意 Node.js 版本最好用 Node 20 LTS 或更高。版本太老的话某些依赖可能装不上表现就是安装过程报一堆错最后opencode命令也起不来。3. opencode 配置与模型接入官方模型、免费模型和本地模型3.1 配置文件在哪里全局配置与项目配置opencode 的配置分两层全局配置和项目配置。全局配置默认在~/.config/opencode/opencode.jsonWindows 下是%USERPROFILE%\.config\opencode\opencode.json它负责你的默认模型、全局 Provider、API Key 等项目配置则放在项目根目录的opencode.json里只对该项目生效适合团队里通过 Git 共享一套 AI 编码规范。我个人的习惯是全局配置只放 Provider 和 API Key项目配置放模型选择、Skills、LSP 这类和具体项目强相关的内容。配置文件的顶层结构大致是这样的{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-20250514, provider: { anthropic: { options: { apiKey: env:ANTHROPIC_API_KEY } } } }注意apiKey那里我写的是env:ANTHROPIC_API_KEY意思是从环境变量读取密钥。强烈建议不要直接把 Key 明文写在配置文件里尤其是项目配置有可能会提交到 Git 仓库时明文 Key 等于裸奔。3.2 接入 Anthropic、OpenAI 与自定义兼容接口接入 Anthropic 和 OpenAI 的官方接口是最简单的两种方式任选一是设置环境变量后直接启动export ANTHROPIC_API_KEYsk-ant-xxx export OPENAI_API_KEYsk-xxx opencode二是在配置文件的 provider 字段里写清楚。opencode 在模型接入上做得很灵活它把每个模型服务商当成一个Provider每个 Provider 本质上对应一个 AI SDK 的接入包。官方支持的 Provider 开箱即用而第三方或自建服务只要兼容 OpenAI 的/v1接口就可以用ai-sdk/openai-compatible这个包来接入。这里给一个自定义 Provider 的例子{ model: myllm/qwen-max, provider: { myllm: { npm: ai-sdk/openai-compatible, name: My LLM Gateway, options: { baseURL: https://your-gateway.example.com/v1, apiKey: env:MY_LLM_KEY }, models: { qwen-max: { name: Qwen Max }, glm-4: { name: GLM-4 } } } } }这段配置的含义是定义一个名为myllm的 Provider走 OpenAI 兼容协议指向某个网关地址然后在这个 Provider 下注册两个模型。配置文件写完后在 TUI 里用/models命令切换模型就能看到myllm/qwen-max这样的选项。这套机制的实用价值在于很多企业内部会有统一的模型网关或者云厂商提供 OpenAI 兼容的接口你不需要等 opencode 官方出适配自己就能接进去。我接手过的几个项目里有的公司就是用内部网关统一管理模型 Key 的opencode 这层抽象帮了大忙。3.3 免费模型和本地模型怎么接如果你只是尝鲜不想花钱有两条路可以走。一条是接聚合平台的免费模型额度比如 OpenRouter 就提供一些免费或限时免费的模型。配置方式跟自定义 Provider 一样把 baseURL 指到 OpenRouter 的兼容地址填上你的 Key然后在模型列表里选带 free 标识的模型即可。免费模型的缺点是速率限制比较严格上下文窗口也可能偏小用来改个小脚本、写个正则表达式没问题但别指望它处理大型重构。另一条是接本地模型。配合 Ollama 这类工具把模型拉到本地跑opencode 再通过 OpenAI 兼容接口接到 Ollama 上。配置示例{ provider: { ollama: { npm: ai-sdk/openai-compatible, name: Ollama Local, options: { baseURL: http://localhost:11434/v1, apiKey: ollama }, models: { qwen2.5-coder:7b: { name: Qwen 2.5 Coder 7B } } } } }本地模型最大的好处是隐私和安全代码不需要离开你的机器。但说实话7B 级别的模型在日常编码辅助上跟云端大模型还有明显差距简单任务可以复杂逻辑推理容易跑偏。我的建议是本地模型放在敏感项目或断网环境里用日常主力还是接云端的付费模型两者互补而不是替代。3.4 “this model is not available in your country”怎么处理搜索引擎里这个报错出现频率很高因为很多人在配置完某个模型后一运行就收到一行红色提示This model is not available in your country.这个报错不是 opencode 本身的错误而是模型服务商根据账号归属地或出口网络位置判断后返回的限制信息。opencode 只是个客户端它把请求发给服务商服务商决定这个地区不提供服务。遇到这种情况正确的处理方向是先查你所用模型服务商的官方支持地区列表看看你所在的地区到底在不在服务范围内如果不在要么换一家在你所在地区正常提供服务的服务商要么直接用本地模型把自己的数据和模型都握在手里。想绕过服务商的地区限制是不可取的也不合规我更建议把精力放在找到一套合法可用的模型组合上而不是去钻空子。4. opencode 进阶功能实战Skills、Memory、LSP 与 Playwright4.1 Skills把团队规范封装成可复用技能Skills 是 opencode 里我很喜欢的一个功能它本质上允许你给 AI 定义一套职业技能。你可以把团队的代码规范、常用的审查流程、特定框架的最佳实践写成一个个 SkillAI 在遇到对应任务时会自动加载并遵循。Skill 的目录结构很简单默认放在~/.config/opencode/skills/技能名/SKILL.md。一个典型的代码审查 Skill 长这样--- name: code-review description: 对代码变更进行审查输出问题清单和修改建议 --- # 代码审查 当用户要求审查代码时严格按以下步骤执行 1. 先运行 git diff 查看变更内容 2. 从可读性、正确性、性能、安全性四个维度检查 3. 每个问题标注文件路径和行号 4. 对每个问题给出具体的修改建议配置好之后你在对话里说一句帮我做一下代码审查opencode 就会根据 description 里的描述匹配到这个 Skill然后按 SKILL.md 里写的步骤执行。我的经验是Skill 不是插件它不会自动加载代码它更像把一段高质量提示词变成可复用的命令。所以写 Skill 的时候description 一定要写清楚触发条件正文里的指令要具体到先做什么、再做什么、输出什么格式越细化越好。如果只是写一句审查代码AI 很可能给你一堆正确的废话。4.2 Memory 与 AGENTS.md让 AI 记住项目背景opencode 在项目语境上的处理和现在主流 AI 编码工具类似项目根目录下的 AGENTS.md 文件就是给 AI 看的项目说明书。每次会话开始opencode 都会读取这个文件把它当作理解项目的背景信息。一个比较完整的 AGENTS.md 大概长这样# AGENTS.md ## 项目简介 这是一个订单管理系统的后端服务Go 编写使用 Gin 框架。 ## 常用命令 - 运行测试: go test ./... - 启动服务: make dev ## 注意事项 - 不要修改 internal/db 目录下的文件 - 新增接口必须写单元测试 - 错误处理统一使用 internal/errors 包这个文件写得好不好直接决定 AI 在项目里的表现。如果连项目是用什么语言、测试怎么跑、哪些文件不能动都不告诉 AI那它就只能在代码里瞎猜。这里分享一个接手老项目的实操流程。我拿到一个陌生项目时第一步不是急着让 AI 改代码而是先建好 AGENTS.md把项目结构、启动方式、关键目录职责写清楚然后让 opencode 先给我讲一遍这个项目的整体架构确认它理解对了再开始让它做具体任务。这样做的好处是AI 的后续操作都建立在正确认知上不会出现改了一个文件却破坏了另一个模块的乌龙。如果你把 opencode 当临时同事AGENTS.md 就是给它做的入职培训。4.3 LSP 集成代码跳转和诊断不再靠猜LSPLanguage Server Protocol语言服务器协议这个名词听起来吓人但理解起来很简单它是一套统一标准让工具能和懂某门语言的语言服务器通信。编译器级别的信息——符号定义、类型推导、错误诊断——都可以通过 LSP 暴露出来。opencode 支持接入 LSP这让它的代码理解能力从看文本升级到了看语义。没有 LSP 的时候AI 分析代码基本靠模式匹配遇到同名函数、复杂类型推断时容易出错接入 LSP 后它能拿到真正的符号定义和诊断信息改代码的准确率明显提升。配置方式是在配置文件的lsp字段里指定语言服务器。以 TypeScript 为例常见的写法是{ lsp: { typescript: { server: typescript-language-server, args: [--stdio] } } }不同版本的 opencode 对 LSP 配置的字段名可能略有差异写之前最好看一眼你安装版本对应的配置 schema。但核心逻辑不变你负责装好语言服务器比如npm install -g typescript-language-server、gopls、jdtlsopencode 负责连上去用。实际使用中最明显的体验差异在两点一是让 AI跳到某个函数的定义处它不再靠猜直接定位源码位置二是它能在改动前先读取当前文件的诊断信息知道代码里已经有哪些错误避免在错误的代码上继续加错误。4.4 Playwright 调试前端 Bug 的操作流程opencode 另一个让我觉得惊艳的功能是接入了 Playwright。什么意思呢它可以让 AI 真正打开浏览器去操作页面、点击按钮、输入文字、截图再看结果改代码。这直接改变了以前前端 Bug 靠人手工复现、再把信息贴给 AI的流程。我实测下来的一套流程是这样的先把前端项目本地跑起来记下地址比如http://localhost:5173。在 opencode 里输入任务比如打开 http://localhost:5173/login用错误的密码登录截图看看有没有报错提示。opencode 会调用 Playwright 打开浏览器执行操作并截图把截图作为上下文继续分析。你可以在对话里追问页面上显示网络错误但控制台里返回的是 401帮我改一下登录接口的错误处理。AI 定位到相关代码给出修改方案你确认后应用再让它重新执行一遍刚才的流程验证。这套流程对复现路径复杂、描述不清楚的前端 Bug 尤其有效。以前描述一个 Bug 要打半天字现在直接让它自己点一遍问题在哪一目了然。有几个细节要提醒使用 Playwright 功能前记得执行npx playwright install chromium把浏览器内核装好另外页面服务要先跑起来地址用本机能访问的真实地址别让它打开一个没启动的端口然后空转半天。最后截图和操作日志都会留在会话记录里你可以随时翻看不用怕 AI 干坏事不留证据。4.5 TUI 里常用的操作速查opencode 的终端界面初看有点花但常用操作就那么几个在输入框直接输指令回车是发送输入/会弹出命令面板/models切换模型、/sessions看历史会话、/settings打开配置相关操作对话中想引用某个具体文件用加文件名把它拉进上下文这样 AI 就能看到文件内容。生成过程中想打断按 Esc 或 CtrlC 就行。还有一个我在多项目切换时很常用的点TUI 里可以维持多个会话每个项目一个会话互不干扰。配合opencode run这种非交互模式你甚至可以在脚本里批量跑代码审查任务。终端重度用户上手很快不太习惯的可以直接用下一节要说的编辑器插件。5. VSCode 插件、IDEA 插件与桌面版的使用体验5.1 VSCode 插件侧边栏对话与一键应用 diff如果你习惯在编辑器里干活而不是在黑色终端里敲命令那 opencode 的 VSCode 插件是你的首选。直接在扩展市场搜 opencode 就能找到安装后侧边栏会出现 opencode 面板它连接到本地同一个服务端和终端里的会话是共享的。我最常用的操作是在编辑器里选中一段代码右键选择发送给 opencode它会在侧边栏给出分析和修改建议确认没问题后可以直接查看 diff 并一键应用改完的代码就在编辑器里了。整个过程不用切窗口体验上很接近 Cursor 这类 AI 编辑器的辅助感但底层的模型和配置都由你自己掌控。快捷键方面我习惯给呼出 opencode 面板绑定一个组合键点右上角扩展设置里就能配。这个插件解决了一个实际问题终端模式下查看大段 diff 不太方便而在编辑器里 diff 展示是强项。所以我的习惯是分析性任务在终端跑改代码用 VSCode 插件。5.2 JetBrains IDEA 插件如果你主力 IDE 是 IntelliJ IDEA、PyCharm、GoLand 这些 JetBrains 家族产品也可以直接在插件市场搜索 opencode 安装。功能形态和 VSCode 插件类似在右侧工具窗口打开对话面板选中代码发送查看并应用修改。有一点值得单独说JetBrains 系的用户很多在做 Java/Kotlin 项目这类项目涉及大量类继承和依赖注入AI 光看代码容易懵。建议配合 LSP 把 Java 语言服务器jdtls接上这样 opencode 能读懂类之间的关系改起来会准很多。5.3 opencode Desktop 桌面版opencode 还提供了桌面客户端适合不习惯终端、也不想依赖编辑器的用户。桌面版本质上是把 TUI 包了一层图形界面底层还是连着本地服务端所以配置和终端完全共用不用重复配模型。我个人的观点是桌面版更适合平时不写代码但需要做代码审查、技术管理的人或者刚入门不想碰命令行的新手。对日常都在终端里泡着的开发者它更多是一个备选入口。但不管用哪种形态底层服务端只有一个这恰恰是 opencode 客户-服务端架构设计最聪明的地方。6. opencode 常见报错排查与避坑技巧6.1 报错速查表建议收藏整理了一份我见过的高频报错速查表先整体看一眼再展开讲几个重点报错提示含义解决方向无法将“opencode”项识别为 cmdlet...Windows 系统找不到命令检查 PATH 配置详见 2.2 节this model is not available in your country模型服务商地区限制查看服务商官方支持地区换服务商或换本地模型unexpected server error. check server logsopencode 服务端异常查看日志确认 API Key、余额、网络连通性connection refused客户端连不上服务端先手动跑一次 opencode serve检查端口占用model not found配置的模型名不存在用 /models 命令查看当前实际可用的模型rate limit exceeded请求超限降低请求频率换个配额更宽的套餐6.2 几个高频报错的深入排查过程先说unexpected server error. check server logs。这个报错信息比较模糊第一次遇到的时候我也摸不着头脑。排查路径其实很固定先找到 opencode 的日志文件Linux/macOS 下一般在~/.local/share/opencode/log/Windows 下在%USERPROFILE%\.local\share\opencode\log\。打开日志看具体的错误原因最常见的三个是 API Key 失效、账号余额不足、请求超时。分别对应的处理是重新生成 Key、检查服务商后台余额、在配置里把超时时间调大一点。再比如connection refused。新版 opencode 架构里一切客户端都依赖服务端如果你发现 TUI 或者插件连不上先手动跑opencode serve看能不能正常启动。如果服务端起不来检查是不是端口被占用或者本地防火墙拦了回环地址。还有一个小概率情况是旧版本服务端进程残留杀掉所有 opencode 相关进程再重试即可。LSP 不生效的问题也比较常见。排查看三处第一语言服务器本体装没装TypeScript 项目先执行which typescript-language-server没有输出就说明没装第二配置文件里 server 名称和参数是否和你装的版本一致第三确认你打开的文件类型确实有对应的语言服务器在运行。这三步走完90% 的 LSP 问题都能解决。6.3 我实际使用中的几个小技巧最后分享几条我自己总结的经验不是官方文档里会写的但实测很有用。不要在同一个终端窗口里叠多个 TUI 会话会互相干扰输出建议用 tmux 或者直接多开终端标签页。另外 opencode 的会话数据存在本地时间久了会积累不少磁盘占用隔一段时间清理一下历史会话是必要的。团队协作时项目配置文件尽量提交到 Git可以让所有成员用同一套模型和 Skills减少在我电脑上好好的这种问题。再一个很有价值的用法是在 CI 脚本里加一步 opencode 审查。比如提交前让opencode run review git diff --cached跑一遍虽然不能完全替代人工 code review但能很有效地拦截低级错误——拼写错误、忘记处理错误返回、明显的边界条件遗漏它都能一眼看出来。这一步的边际成本几乎是零带来的收益却非常稳定。说到底opencode 这类工具的定位从来不是替代你写代码而是把读代码、找问题、做重复修改这些环节压缩到最短。工具本身很轻真正值钱的是你给它配置的那套 Skills 和项目记忆。最后再提醒一句API Key 这类敏感信息一定用环境变量引用项目配置要提交到 Git 之前多看一眼有没有泄露痕迹。这部分花点时间打磨长期收益是实打实的。 
长河君 · 2026/9/8 18:07:06 · 阅读 1.2k 开源终端AI编程助手opencode实战指南
最近技术圈里 AI 编程助手的热度一直没降Claude Code、Codex CLI 这些名字大家都不陌生但如果你想找一个更开放、更自由的选择那一定要看看 opencode。它是一个开源的终端 AI 编程助手用 Go 写的核心支持接入多种模型服务既能交互式聊天也能跑自动化脚本还被做成了 VSCode、IDEA 插件和桌面版。我大概用了半年从最开始装来尝鲜到后来真的把它用进代码审查、老项目接手、前端回归测试这些日常环节体验下来确实省了不少事。这篇就当一份 opencode 的实战笔记把安装、模型配置、Skills、Memory、LSP、编辑器集成这些点串起来再把报错汇总成一份排查表争取让新手少走弯路。1. opencode 是什么和 Claude Code、Codex CLI 对比后的选择1.1 定位一个跑在终端里的开源 AI 编码助手opencode 本质上是一个懂代码的 AI 对话入口它跑在终端里启动后会进入一个交互式界面TUI你可以在里面直接让 AI 读代码、改代码、跑命令、查报错也可以给它一个完整任务让它自动执行。它和你平时用的 ChatGPT 网页版最大的区别在于它天然生存在你的项目上下文里能直接读取当前仓库的文件结构、代码内容、Git 状态操作结果实时可见改完的文件直接落在磁盘上不需要你像传统聊天机器人那样反复复制粘贴代码。有一点值得单独说opencode 2.x 之后的架构改成了客户-服务端模式。opencode serve负责在本地起一个服务端终端 TUI、编辑器插件、桌面版都作为客户端连到同一个服务端上。这意味着你在 VSCode 里起的会话可以接着在终端里继续聊上下文是共享的。这个设计一开始我还觉得多此一举用久了才发现它其实是 opencode 能同时支持这么多前端形态的根本原因。1.2 为什么选它多模型、开源、Go 底层的差异点我身边经常有人问Claude Code、Codex CLI、opencode 到底选哪个。这个问题没有标准答案但可以列一张表看清楚差异对比项opencodeClaude CodeCodex CLI是否开源完全开源闭源开源支持的模型多家 自定义 Provider仅 Claude 系列以 OpenAI 系列为主核心实现Go闭源实现Node/TypeScriptSkills/扩展支持支持有限客户端形态TUI / 插件 / 桌面终端为主终端为主适合人群多模型切换、喜欢折腾Anthropic 生态重度用户OpenAI 生态重度用户我个人的使用感受是opencode 最大的优势不是某一个功能多强而是不锁死。今天想用 Anthropic 的 Claude明天想切到国产模型后天想在破电脑上接个本地模型它都支持。用 Go 写核心也带来一个很实在的好处单一二进制文件启动速度快跨平台分发简单不像 Node 系工具那样偶尔还要操心依赖版本。另外opencode 的run非交互模式也很实用。你可以直接在命令行里跑opencode run review git diff它会在不进入 TUI 的情况下执行任务并输出结果非常适合作 CI 辅助或者简单的脚本调用。这是我在实际工作中用得最频繁的功能之一。2. opencode 安装教程三个平台的一路踩坑记录2.1 macOS 和 Linux 的一行命令安装macOS 和 Linux 用户是最省心的官方提供了安装脚本curl -fsSL https://opencode.ai/install | bash如果你用 Homebrew也可以走 brew 路线brew install sst/tap/opencode我个人的建议是优先用安装脚本因为 brew 仓库里的版本偶尔会滞后而 opencode 迭代速度很快新版本往往会修掉一些老版本在 TUI 交互上的小毛病。如果你在公司内网环境不方便跑脚本直接去 GitHub Releases 页面下载对应平台的可执行文件也能用Linux 下记得下载后执行chmod x opencode再放到/usr/local/bin下。2.2 Windows 下“无法将 opencode 识别为 cmdlet”的解决办法Windows 用户最常见的报错就是搜索引擎里经常出现的那条无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这句话翻译成人话就是PowerShell 在系统的 PATH 环境变量里找不到 opencode 这个命令。它不代表你安装失败而是装了但没被系统找到。最常见的场景是用 npm 全局安装之后没有把 npm 的全局目录加进 PATH。解决办法分几步走先确认安装是否成功在 PowerShell 里跑一次npm ls -g opencode-ai能看到版本号说明已经装上了。然后查看 npm 的全局安装目录npm config get prefix把上面输出的路径加入系统 PATH打开系统属性 → 环境变量 → 系统变量 → Path → 新建填入类似C:\Users\你的用户名\AppData\Roaming\npm这样的路径然后保存。关掉当前 PowerShell 窗口重新打开一个新的再执行opencode --version。如果还识别不了那就别折腾 npm 了直接下载 Windows 安装包或独立 exe把可执行文件放到一个目录里手动把这个目录加进 PATH 就行。这个报错本身不复杂但非常劝退新手所以我单独拿出来讲。其实只要记得改完 PATH 必须重开终端这个原则Windows 下很多工具的报错都能自己解决。2.3 安装后怎么确认环境没问题装好之后先跑一条最基础的命令opencode --version能看到版本号输出就说明可执行文件没问题。接着直接敲opencode回车进入交互界面。第一次启动时它会让你选择模型提供商如果手头还没有任何 API Key可以先选一个免费的或者直接退出先看配置文件怎么写下一节详细讲。还有一个小细节如果你是通过 npm 安装的建议留意 Node.js 版本最好用 Node 20 LTS 或更高。版本太老的话某些依赖可能装不上表现就是安装过程报一堆错最后opencode命令也起不来。3. opencode 配置与模型接入官方模型、免费模型和本地模型3.1 配置文件在哪里全局配置与项目配置opencode 的配置分两层全局配置和项目配置。全局配置默认在~/.config/opencode/opencode.jsonWindows 下是%USERPROFILE%\.config\opencode\opencode.json它负责你的默认模型、全局 Provider、API Key 等项目配置则放在项目根目录的opencode.json里只对该项目生效适合团队里通过 Git 共享一套 AI 编码规范。我个人的习惯是全局配置只放 Provider 和 API Key项目配置放模型选择、Skills、LSP 这类和具体项目强相关的内容。配置文件的顶层结构大致是这样的{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-20250514, provider: { anthropic: { options: { apiKey: env:ANTHROPIC_API_KEY } } } }注意apiKey那里我写的是env:ANTHROPIC_API_KEY意思是从环境变量读取密钥。强烈建议不要直接把 Key 明文写在配置文件里尤其是项目配置有可能会提交到 Git 仓库时明文 Key 等于裸奔。3.2 接入 Anthropic、OpenAI 与自定义兼容接口接入 Anthropic 和 OpenAI 的官方接口是最简单的两种方式任选一是设置环境变量后直接启动export ANTHROPIC_API_KEYsk-ant-xxx export OPENAI_API_KEYsk-xxx opencode二是在配置文件的 provider 字段里写清楚。opencode 在模型接入上做得很灵活它把每个模型服务商当成一个Provider每个 Provider 本质上对应一个 AI SDK 的接入包。官方支持的 Provider 开箱即用而第三方或自建服务只要兼容 OpenAI 的/v1接口就可以用ai-sdk/openai-compatible这个包来接入。这里给一个自定义 Provider 的例子{ model: myllm/qwen-max, provider: { myllm: { npm: ai-sdk/openai-compatible, name: My LLM Gateway, options: { baseURL: https://your-gateway.example.com/v1, apiKey: env:MY_LLM_KEY }, models: { qwen-max: { name: Qwen Max }, glm-4: { name: GLM-4 } } } } }这段配置的含义是定义一个名为myllm的 Provider走 OpenAI 兼容协议指向某个网关地址然后在这个 Provider 下注册两个模型。配置文件写完后在 TUI 里用/models命令切换模型就能看到myllm/qwen-max这样的选项。这套机制的实用价值在于很多企业内部会有统一的模型网关或者云厂商提供 OpenAI 兼容的接口你不需要等 opencode 官方出适配自己就能接进去。我接手过的几个项目里有的公司就是用内部网关统一管理模型 Key 的opencode 这层抽象帮了大忙。3.3 免费模型和本地模型怎么接如果你只是尝鲜不想花钱有两条路可以走。一条是接聚合平台的免费模型额度比如 OpenRouter 就提供一些免费或限时免费的模型。配置方式跟自定义 Provider 一样把 baseURL 指到 OpenRouter 的兼容地址填上你的 Key然后在模型列表里选带 free 标识的模型即可。免费模型的缺点是速率限制比较严格上下文窗口也可能偏小用来改个小脚本、写个正则表达式没问题但别指望它处理大型重构。另一条是接本地模型。配合 Ollama 这类工具把模型拉到本地跑opencode 再通过 OpenAI 兼容接口接到 Ollama 上。配置示例{ provider: { ollama: { npm: ai-sdk/openai-compatible, name: Ollama Local, options: { baseURL: http://localhost:11434/v1, apiKey: ollama }, models: { qwen2.5-coder:7b: { name: Qwen 2.5 Coder 7B } } } } }本地模型最大的好处是隐私和安全代码不需要离开你的机器。但说实话7B 级别的模型在日常编码辅助上跟云端大模型还有明显差距简单任务可以复杂逻辑推理容易跑偏。我的建议是本地模型放在敏感项目或断网环境里用日常主力还是接云端的付费模型两者互补而不是替代。3.4 “this model is not available in your country”怎么处理搜索引擎里这个报错出现频率很高因为很多人在配置完某个模型后一运行就收到一行红色提示This model is not available in your country.这个报错不是 opencode 本身的错误而是模型服务商根据账号归属地或出口网络位置判断后返回的限制信息。opencode 只是个客户端它把请求发给服务商服务商决定这个地区不提供服务。遇到这种情况正确的处理方向是先查你所用模型服务商的官方支持地区列表看看你所在的地区到底在不在服务范围内如果不在要么换一家在你所在地区正常提供服务的服务商要么直接用本地模型把自己的数据和模型都握在手里。想绕过服务商的地区限制是不可取的也不合规我更建议把精力放在找到一套合法可用的模型组合上而不是去钻空子。4. opencode 进阶功能实战Skills、Memory、LSP 与 Playwright4.1 Skills把团队规范封装成可复用技能Skills 是 opencode 里我很喜欢的一个功能它本质上允许你给 AI 定义一套职业技能。你可以把团队的代码规范、常用的审查流程、特定框架的最佳实践写成一个个 SkillAI 在遇到对应任务时会自动加载并遵循。Skill 的目录结构很简单默认放在~/.config/opencode/skills/技能名/SKILL.md。一个典型的代码审查 Skill 长这样--- name: code-review description: 对代码变更进行审查输出问题清单和修改建议 --- # 代码审查 当用户要求审查代码时严格按以下步骤执行 1. 先运行 git diff 查看变更内容 2. 从可读性、正确性、性能、安全性四个维度检查 3. 每个问题标注文件路径和行号 4. 对每个问题给出具体的修改建议配置好之后你在对话里说一句帮我做一下代码审查opencode 就会根据 description 里的描述匹配到这个 Skill然后按 SKILL.md 里写的步骤执行。我的经验是Skill 不是插件它不会自动加载代码它更像把一段高质量提示词变成可复用的命令。所以写 Skill 的时候description 一定要写清楚触发条件正文里的指令要具体到先做什么、再做什么、输出什么格式越细化越好。如果只是写一句审查代码AI 很可能给你一堆正确的废话。4.2 Memory 与 AGENTS.md让 AI 记住项目背景opencode 在项目语境上的处理和现在主流 AI 编码工具类似项目根目录下的 AGENTS.md 文件就是给 AI 看的项目说明书。每次会话开始opencode 都会读取这个文件把它当作理解项目的背景信息。一个比较完整的 AGENTS.md 大概长这样# AGENTS.md ## 项目简介 这是一个订单管理系统的后端服务Go 编写使用 Gin 框架。 ## 常用命令 - 运行测试: go test ./... - 启动服务: make dev ## 注意事项 - 不要修改 internal/db 目录下的文件 - 新增接口必须写单元测试 - 错误处理统一使用 internal/errors 包这个文件写得好不好直接决定 AI 在项目里的表现。如果连项目是用什么语言、测试怎么跑、哪些文件不能动都不告诉 AI那它就只能在代码里瞎猜。这里分享一个接手老项目的实操流程。我拿到一个陌生项目时第一步不是急着让 AI 改代码而是先建好 AGENTS.md把项目结构、启动方式、关键目录职责写清楚然后让 opencode 先给我讲一遍这个项目的整体架构确认它理解对了再开始让它做具体任务。这样做的好处是AI 的后续操作都建立在正确认知上不会出现改了一个文件却破坏了另一个模块的乌龙。如果你把 opencode 当临时同事AGENTS.md 就是给它做的入职培训。4.3 LSP 集成代码跳转和诊断不再靠猜LSPLanguage Server Protocol语言服务器协议这个名词听起来吓人但理解起来很简单它是一套统一标准让工具能和懂某门语言的语言服务器通信。编译器级别的信息——符号定义、类型推导、错误诊断——都可以通过 LSP 暴露出来。opencode 支持接入 LSP这让它的代码理解能力从看文本升级到了看语义。没有 LSP 的时候AI 分析代码基本靠模式匹配遇到同名函数、复杂类型推断时容易出错接入 LSP 后它能拿到真正的符号定义和诊断信息改代码的准确率明显提升。配置方式是在配置文件的lsp字段里指定语言服务器。以 TypeScript 为例常见的写法是{ lsp: { typescript: { server: typescript-language-server, args: [--stdio] } } }不同版本的 opencode 对 LSP 配置的字段名可能略有差异写之前最好看一眼你安装版本对应的配置 schema。但核心逻辑不变你负责装好语言服务器比如npm install -g typescript-language-server、gopls、jdtlsopencode 负责连上去用。实际使用中最明显的体验差异在两点一是让 AI跳到某个函数的定义处它不再靠猜直接定位源码位置二是它能在改动前先读取当前文件的诊断信息知道代码里已经有哪些错误避免在错误的代码上继续加错误。4.4 Playwright 调试前端 Bug 的操作流程opencode 另一个让我觉得惊艳的功能是接入了 Playwright。什么意思呢它可以让 AI 真正打开浏览器去操作页面、点击按钮、输入文字、截图再看结果改代码。这直接改变了以前前端 Bug 靠人手工复现、再把信息贴给 AI的流程。我实测下来的一套流程是这样的先把前端项目本地跑起来记下地址比如http://localhost:5173。在 opencode 里输入任务比如打开 http://localhost:5173/login用错误的密码登录截图看看有没有报错提示。opencode 会调用 Playwright 打开浏览器执行操作并截图把截图作为上下文继续分析。你可以在对话里追问页面上显示网络错误但控制台里返回的是 401帮我改一下登录接口的错误处理。AI 定位到相关代码给出修改方案你确认后应用再让它重新执行一遍刚才的流程验证。这套流程对复现路径复杂、描述不清楚的前端 Bug 尤其有效。以前描述一个 Bug 要打半天字现在直接让它自己点一遍问题在哪一目了然。有几个细节要提醒使用 Playwright 功能前记得执行npx playwright install chromium把浏览器内核装好另外页面服务要先跑起来地址用本机能访问的真实地址别让它打开一个没启动的端口然后空转半天。最后截图和操作日志都会留在会话记录里你可以随时翻看不用怕 AI 干坏事不留证据。4.5 TUI 里常用的操作速查opencode 的终端界面初看有点花但常用操作就那么几个在输入框直接输指令回车是发送输入/会弹出命令面板/models切换模型、/sessions看历史会话、/settings打开配置相关操作对话中想引用某个具体文件用加文件名把它拉进上下文这样 AI 就能看到文件内容。生成过程中想打断按 Esc 或 CtrlC 就行。还有一个我在多项目切换时很常用的点TUI 里可以维持多个会话每个项目一个会话互不干扰。配合opencode run这种非交互模式你甚至可以在脚本里批量跑代码审查任务。终端重度用户上手很快不太习惯的可以直接用下一节要说的编辑器插件。5. VSCode 插件、IDEA 插件与桌面版的使用体验5.1 VSCode 插件侧边栏对话与一键应用 diff如果你习惯在编辑器里干活而不是在黑色终端里敲命令那 opencode 的 VSCode 插件是你的首选。直接在扩展市场搜 opencode 就能找到安装后侧边栏会出现 opencode 面板它连接到本地同一个服务端和终端里的会话是共享的。我最常用的操作是在编辑器里选中一段代码右键选择发送给 opencode它会在侧边栏给出分析和修改建议确认没问题后可以直接查看 diff 并一键应用改完的代码就在编辑器里了。整个过程不用切窗口体验上很接近 Cursor 这类 AI 编辑器的辅助感但底层的模型和配置都由你自己掌控。快捷键方面我习惯给呼出 opencode 面板绑定一个组合键点右上角扩展设置里就能配。这个插件解决了一个实际问题终端模式下查看大段 diff 不太方便而在编辑器里 diff 展示是强项。所以我的习惯是分析性任务在终端跑改代码用 VSCode 插件。5.2 JetBrains IDEA 插件如果你主力 IDE 是 IntelliJ IDEA、PyCharm、GoLand 这些 JetBrains 家族产品也可以直接在插件市场搜索 opencode 安装。功能形态和 VSCode 插件类似在右侧工具窗口打开对话面板选中代码发送查看并应用修改。有一点值得单独说JetBrains 系的用户很多在做 Java/Kotlin 项目这类项目涉及大量类继承和依赖注入AI 光看代码容易懵。建议配合 LSP 把 Java 语言服务器jdtls接上这样 opencode 能读懂类之间的关系改起来会准很多。5.3 opencode Desktop 桌面版opencode 还提供了桌面客户端适合不习惯终端、也不想依赖编辑器的用户。桌面版本质上是把 TUI 包了一层图形界面底层还是连着本地服务端所以配置和终端完全共用不用重复配模型。我个人的观点是桌面版更适合平时不写代码但需要做代码审查、技术管理的人或者刚入门不想碰命令行的新手。对日常都在终端里泡着的开发者它更多是一个备选入口。但不管用哪种形态底层服务端只有一个这恰恰是 opencode 客户-服务端架构设计最聪明的地方。6. opencode 常见报错排查与避坑技巧6.1 报错速查表建议收藏整理了一份我见过的高频报错速查表先整体看一眼再展开讲几个重点报错提示含义解决方向无法将“opencode”项识别为 cmdlet...Windows 系统找不到命令检查 PATH 配置详见 2.2 节this model is not available in your country模型服务商地区限制查看服务商官方支持地区换服务商或换本地模型unexpected server error. check server logsopencode 服务端异常查看日志确认 API Key、余额、网络连通性connection refused客户端连不上服务端先手动跑一次 opencode serve检查端口占用model not found配置的模型名不存在用 /models 命令查看当前实际可用的模型rate limit exceeded请求超限降低请求频率换个配额更宽的套餐6.2 几个高频报错的深入排查过程先说unexpected server error. check server logs。这个报错信息比较模糊第一次遇到的时候我也摸不着头脑。排查路径其实很固定先找到 opencode 的日志文件Linux/macOS 下一般在~/.local/share/opencode/log/Windows 下在%USERPROFILE%\.local\share\opencode\log\。打开日志看具体的错误原因最常见的三个是 API Key 失效、账号余额不足、请求超时。分别对应的处理是重新生成 Key、检查服务商后台余额、在配置里把超时时间调大一点。再比如connection refused。新版 opencode 架构里一切客户端都依赖服务端如果你发现 TUI 或者插件连不上先手动跑opencode serve看能不能正常启动。如果服务端起不来检查是不是端口被占用或者本地防火墙拦了回环地址。还有一个小概率情况是旧版本服务端进程残留杀掉所有 opencode 相关进程再重试即可。LSP 不生效的问题也比较常见。排查看三处第一语言服务器本体装没装TypeScript 项目先执行which typescript-language-server没有输出就说明没装第二配置文件里 server 名称和参数是否和你装的版本一致第三确认你打开的文件类型确实有对应的语言服务器在运行。这三步走完90% 的 LSP 问题都能解决。6.3 我实际使用中的几个小技巧最后分享几条我自己总结的经验不是官方文档里会写的但实测很有用。不要在同一个终端窗口里叠多个 TUI 会话会互相干扰输出建议用 tmux 或者直接多开终端标签页。另外 opencode 的会话数据存在本地时间久了会积累不少磁盘占用隔一段时间清理一下历史会话是必要的。团队协作时项目配置文件尽量提交到 Git可以让所有成员用同一套模型和 Skills减少在我电脑上好好的这种问题。再一个很有价值的用法是在 CI 脚本里加一步 opencode 审查。比如提交前让opencode run review git diff --cached跑一遍虽然不能完全替代人工 code review但能很有效地拦截低级错误——拼写错误、忘记处理错误返回、明显的边界条件遗漏它都能一眼看出来。这一步的边际成本几乎是零带来的收益却非常稳定。说到底opencode 这类工具的定位从来不是替代你写代码而是把读代码、找问题、做重复修改这些环节压缩到最短。工具本身很轻真正值钱的是你给它配置的那套 Skills 和项目记忆。最后再提醒一句API Key 这类敏感信息一定用环境变量引用项目配置要提交到 Git 之前多看一眼有没有泄露痕迹。这部分花点时间打磨长期收益是实打实的。