1. 为什么我最终选择了 OpenCode 这个 AI 编码工具
1.1 它到底是什么：终端里的 Agent，而不只是补全工具
先说结论：OpenCode 不是传统意义上的 IDE 插件或“代码补全”工具，它是一个跑在终端里的 AI 编程代理（agent）。你启动它之后，不是像 Copilot 那样在你敲代码时给一个灰色建议，而是给你一个命令行界面，你可以直接跟它说“帮我把这个接口改成 POST 方式，顺便把调用它的所有前端文件一起改掉”。它会在后台读取整个项目的代码结构，分析仓库里的上下文，然后自己去改文件、运行测试、甚至执行构建命令，最后把结果和日志展示给你。
这个概念最早由 Claude Code 带火，现在大家把这个品类叫“终端 AI 编程代理”。OpenCode 就是这个赛道里非常具有代表性的开源实现。它把这个概念进一步开放了：底层不锁定某个特定模型，支持接 Anthropic 的 Claude、OpenAI 的 GPT、Google 的 Gemini，也可以接本地部署的 Ollama 模型或者任何 OpenAI 兼容的 API。
我记得第一次用它打开一个三个月没碰过的旧项目时，直接说了一句“帮我看看这个仓库现在能不能跑起来”。它自己去读 package.json、找启动脚本、跑了一次 dev server，然后把报错信息整理出来给我看。那一刻我突然意识到，这已经不是“下一行代码填什么”的工具，而是一个能对着整个代码库干活的数字打工仔。
1.2 和 Claude Code、Codex 这些工具比，它的优势在哪
很多人问过我：都是终端 agent，OpenCode 和 Claude Code、Codex 到底差在哪？我的真实感受是，OpenCode 最大的特点是“开放”。
先说模型层面。Claude Code 绑定 Claude 系模型，Codex 主要是 OpenAI 系的，而 OpenCode 是“一碗水端平”。你在同一个交互界面里，可以用 /model 命令随时切换不同的模型提供商。这个体验在做模型 A/B 对比的时候非常爽。我常用 Claude Sonnet 跑一些逻辑密集的重构，再用 GPT 系跑一些偏代码生成的内容，最后本地 Ollama 模型用来处理那种不方便上传给云端的内部代码片段。
然后是开源本身带来的好处。代码开源意味着社区可以给它的能力做很多外挂式的扩展，比如各种 skills 技能包。这是我特别喜欢它的一个点：Claude Code 这边虽然也有 skills，但 OpenCode 这边可以直接在项目里放一个 .opencode/skills 目录，把常用的操作流程写成可复用的提示模板，团队所有人用 git 同步，这个体验非常贴合工程团队的工作方式。
再者，OpenCode 提供了完整的多端点形态。除了终端 TUI 之外，有 VS Code 插件、JetBrains IDEA 插件，还出了桌面版（opencode desktop）。这些形态不是包装概念，而是为了让不同岗位的人都能用同一套底层能力。程序员喜欢终端，就直接用 TUI；产品经理想试试，就开桌面版点一点；习惯了 IDE 内嵌的，就用插件。同一个项目、同一套配置文件，换界面不换逻辑。
1.3 适合谁来用，怎么把它放进现有工作流
从我的实践看，以下几类人群最适合入手 OpenCode：
- 独立开发者或小团队。没有人专职做脚手架、修 bug，可以让 agent 在构建失败后替我检查日志，或者把重复的 CRUD 代码交给它批量生成。
- 需要同时运营多个模型账号的人。不想被一家模型绑定死，想在不同模型之间比价、比质量。
- 经常要接手别人遗留项目的开发。仓库上下文很复杂，用 OpenCode 做“先读后改”比让同事从零解释成本低得多。
- 对成本敏感、想试试免费模型的用户。OpenCode 不强制绑定官方付费 API，可以接 OpenAI 兼容的各种服务地址，这部分我下面会展开讲。
不适合的人也有：完全不用终端、不习惯看报错日志、对“让 AI 直接改代码”这件事没有心理准备的人，可能会觉得很别扭。它的核心操作界面仍然是命令行，这不是一款纯图形化的“傻瓜式”工具。
把 OpenCode 放进现有工作流，我的建议是先从一个低频、低风险的任务开始。比如让它先只负责“解释代码”和“生成测试用例”，这些任务就算出问题也不至于搞坏生产代码。等摸清楚它的脾气，再逐步放权到让它跑命令、执行修改。下面文章就从安装开始，一步步带你把它跑起来。
2. 安装 OpenCode：三种方式对比与踩坑
2.1 官方推荐：安装脚本与包管理器
OpenCode 的安装方式不像某些商业软件只有一条路。我整理下来，主流的有三种：安装脚本、包管理器、以及 Go 工具链直接编译安装。
第一种是官方安装脚本，也是我最推荐给新手的。打开终端执行：
curl -fsSL https://opencode.ai/install | bash脚本会自动检测你的操作系统、下载对应平台的可执行文件，然后放到系统 PATH 里。装完以后新开一个终端窗口，输入：
opencode --version能看到版本号就说明成功了。这个方式的好处是省心，脚本同时处理了路径和权限问题，基本不会出现“装完找不到命令”的尴尬。
第二种方式是通过包管理器。macOS 用户用 Homebrew：
brew install sst/tap/opencodeLinux 或 Windows 可以用 npm：
npm install -g opencode-ai用 npm 的优点是对前端工程师来说特别熟悉，而且可以配合 nvm 管理不同 Node 版本，缺点是有时候 npm 镜像源同步不及时，装到的可能不是最新版。如果你发现版本老得离谱，可以换成官方脚本重装。
第三种是 Go 工具链编译安装。这种适合那些喜欢自己掌控构建过程的人：
go install github.com/sst/opencode@latest需要注意，用 Go 安装要求本机 Go 版本在 1.22 以上，而且如果你的 GOPATH 没配置到 PATH 里，装完之后还是找不到命令。这种方式的优势是可以直接装到当前用户目录，不需要 root 权限，也不污染系统全局。
我的建议是这样的：快速体验用第一种，长期使用且正好有 Homebrew / npm 环境的用第二种，有 Go 开发需求、喜欢折腾的用第三种。安装方式之间没有本质区别，最终都是一个可执行文件摆在那里，关键看你的环境变量和权限配置。
2.2 Windows 下“无法识别 opencode”错误的实际解决思路
我搜了一下网络上问 OpenCode 安装问题的高频词，排在最前面的就是这条：
opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名...这个错误在 Windows PowerShell 里非常经典。看到它的第一反应不要慌，这是系统在你当前终端的 PATH 路径里找不到 opencode 这个可执行文件，不代表安装失败。常见原因有三种：
一是安装脚本下载完成后，没有把安装目录加入 PATH。这种情况你检查一下 C:\Users\你的用户名\bin 或类似目录下有没有 opencode.exe 文件，如果有，手动把它所在目录加入系统环境变量 Path 就行。加完之后记得关掉当前终端窗口，重新打开一个新的。
二是执行安装脚本时终端权限不够，某些步骤被安全软件拦截，导致文件不完整。最简单的做法是换个安装方式，比如直接用 npm 全局安装。PowerShell 下执行：
npm install -g opencode-ainpm 会把可执行文件放到 Node 的全局 bin 目录，而这个目录通常已经在 PATH 里了。
三是你手动下载了 zip 压缩包，解压后放在某个文件夹里，但忘了把它加进 PATH。我见过很多人卡在这一步。正确做法是把解压出来的 opencode.exe 放到一个你熟悉的目录，比如 C:\opencode\，然后在系统环境变量里把 C:\opencode 加进去。
这里有一个非常实用的小经验：如果在 Windows 上实在不想折腾 PATH，可以在 PowerShell 里直接定义别名，把完整路径写死：
Set-Alias opencode "C:\opencode\opencode.exe"别名只在当前会话里生效，想持久化就把它加到 $PROFILE 文件里。虽然治标不治本，但至少能立刻开始用，不用临时去改系统变量。
2.3 通过 Go 或 npm 安装时的注意事项
Go 安装方式遇到的坑，最典型的是这样：执行完 go install 之后，终端提示“command not found”。原因很直接，就是 GOPATH 下的 bin 目录不在 PATH 里。你先执行：
go env GOPATH看输出出来的路径，一般是 ~/go，那么二进制文件就会在 ~/go/bin/opencode。然后把 ~/go/bin 加入 PATH 即可。Linux 和 macOS 可以编辑 ~/.bashrc 或 ~/.zshrc，加入：
export PATH="$PATH:$(go env GOPATH)/bin"Windows 的话在用户环境变量的 Path 里手动追加 %USERPROFILE%\go\bin。
npm 方式还有一个小细节：一定要看清包名。NPM 仓库里叫 opencode 的包有很多，但官方维护的包名是 opencode-ai，别装错了。装成同名或近似名字的第三方包，轻则版本对不上，重则从 npm 上拉下来一段你不认识的可执行脚本，这是有安全隐患的。所以安装完第一件事，运行 opencode --version 确认版本，再运行 opencode /help 看主界面能否正常打开。
到这里安装环节基本结束了。但装好并不代表能直接干活，因为 OpenCode 本身是一个“模型客户端”，你得先告诉它模型服务端的地址和密钥，它才知道找谁干活。这一步也是很多人卡住的地方，下一节专门讲。
3. 配置模型：密钥、Provider 与配置文件
3.1 支持的模型提供商与密钥配置
OpenCode 的模型接入设计思路很清晰：它把模型服务抽象成了两层。第一层是内置的 provider，像 Anthropic Claude、OpenAI、Google Gemini，官方已经帮你写好了接入逻辑，只要提供 API Key 就能用。第二层是所有兼容 OpenAI API 的服务端，不管你是用云服务商提供的模型网关、企业内部搭建的模型代理，还是本地的 Ollama / vLLM，只要遵循 OpenAI 的接口格式，都可以在配置里自定义。
具体的 Key 配置方式有两种。第一种是通过环境变量，这是大多数情况下的首选：
export ANTHROPIC_API_KEY="sk-ant-xxxxx" export OPENAI_API_KEY="sk-proj-xxxxx" export OPENCODE_MODEL="claude-sonnet-4-20250514"把密钥写进环境变量，好处是跟配置文件分离，你可以在不同机器间同步 opencode.json 而不用担心泄露密钥。缺点是如果同时配了多个模型，每次切模型都得重新设置环境变量，有点麻烦。
第二种是在 opencode.json 里通过 provider 配置直接指定，适合想要把完整配置版本化的场景。我后面会展示一个完整的配置示例。
对于只想快速试用的人，我建议直接配一个 Anthropic 的 Key，因为 OpenCode 对 Claude 系模型的兼容性最好，很多 TUI 功能和工具调用都是围绕 Claude 的消息格式设计的。如果你用的是其他厂商模型，不是不能用，但有些高级功能可能表现为“模型能跑、工具调用偶尔抽风”，这个在对比测试时要心里有数。
3.2 opencode.json 配置文件详解
无论你用哪种方式安装，OpenCode 在首次启动时都会在当前项目目录生成一份默认的 opencode.json。这个文件是 OpenCode 的“总控制台”，支持全局配置和项目级配置，项目级配置会覆盖全局配置。下面是一份我认为覆盖了日常主要需求的配置模板：
{ "$schema": "https://opencode.ai/config.json", "provider": { "my-openrouter": { "npm": "@ai-sdk/openai-compatible", "name": "OpenRouter (OpenAI compatible)", "options": { "baseURL": "https://openrouter.ai/api/v1" }, "models": { "my-deepseek": { "name": "DeepSeek V3", "options": { "apiKey": "{env:OPENROUTER_API_KEY}" } } } } }, "model": "my-deepseek", "theme": "opencode", "instruction": "默认情况下，请用中文回答，修改代码前先解释计划。", "permission": { "edit": "ask", "run": "ask", "bash": "ask", "webfetch": "allow" }, "skills": { "rust": false, "typescript": true } }简单解释几个关键字段。provider 字段用于定义你自定义的模型提供商，在 provider 下面可以写多个不同类型的服务。model 字段指定默认使用哪个模型。theme 控制终端配色。instruction 相当于全局“行动纲领”，我建议把自己的偏好写在这里，比如“所有代码注释用中文”“提交信息遵循 Conventional Commits”，这些约束会让 Agent 的输出风格稳定很多。
permission 字段是权限控制的灵魂。我把 edit、run、bash 都设成 ask，意思是它每次要修改文件、执行命令之前，都必须先经过我确认。我们可以把这个理解为“文件修改确认模式”，适合初期不信任 stage。等跑熟了，可以把某些项改成 allow 提高自动化程度。这部分我建议安全第一，宁可多确认一次，也别让 Agent 在你不注意的时候把生产环境脚本跑了。
3.3 免费模型与模型服务商变更的注意事项
“免费模型”是社区里搜索 OpenCode 的核心热词之一，同时我也看到一些用户在问某个免费模型已经下线的问题。我的判断是：不用完全迷信某个免费渠道，更不要在一棵树上吊死，要理解免费模型变动快背后反映的本质——模型 API 的供应方为了控制成本和合规，随时可能调整服务策略。
如果你的目的是体验 OpenCode 的完整功能，我建议至少准备两个渠道：一个付费官方渠道，比如直接开通 Claude 或 OpenAI 的 API 按量付费；一个 OpenAI 兼容的第三方网关，用来做模型对比测试。这样做的理由是，OpenCode 是一个调用模型服务端的“客户端”，它本身不生产模型，也没有哪个模型是绑定在它身上的。万一某个渠道挂了，你要做的不是在社区里问“是不是下线了”，而是去改配置里的 baseURL 和模型名，换到另一个可用渠道。
切换模型提供商时有一个小坑，就是不同提供方可能对同一个模型名采用不同的命名，比如“Qwen2.5-72B-Instruct”在某些平台叫“qwen2.5:72b”，在另一些平台又加了厂商前缀。写错模型名会导致接口直接报错，这就是很多“unexpected server error”的真实来源，并不一定是服务商挂了。当你收到这类错误时，第一步不是怀疑服务器，而是去查你配置里的模型名是否和服务商文档完全一致。
4. 高频实操：命令、Skills 与 IDE 整合
4.1 必掌握的命令与 TUI 操作
把 OpenCode 装好、密钥配置好之后，第一次进入它的交互界面，你可能会被满屏信息吓到。别怕，核心操作就几个。
在项目目录下直接输入：
opencode启动后进入交互模式。界面最底下的输入框可以输入指令，你可以直接说自然语言需求，也可以输入斜杠命令。最常用的几个：
| 命令 | 作用 |
|---|---|
| /model | 在当前会话中切换模型 |
| /init | 让 Agent 分析当前项目，生成/更新项目说明书（类似 AGENTS.md） |
| /new | 开启一个新会话，清空当前上下文 |
| /resume | 恢复之前的某个会话，配合 opencode sessions 查看历史 |
| /permission | 修改权限模式，比如从 ask 切换到 auto-accept |
| /undo | 回退 Agent 最近一次的文件变更 |
交互模式下比较重要的技巧是“按住 Shift 选中多行代码再提问”。比如你选中一段代码然后问“这段代码有没有内存泄漏”，Agent 会只针对你选中的部分进行上下文分析，避免加载整个文件导致 token 浪费。这对控制成本和保持回答精准度特别有用。
如果你不想进入交互界面，可以用一次性模式直接跑任务：
opencode run "给这个仓库写一个 README，包含项目概述、快速开始和常见命令"这个模式适合写脚本、做 CI 集成。比如我就在 GitHub Actions 里跑过类似opencode run "运行测试并统计失败用例，把结果整理成 markdown"这样的任务。它跑完就退出，十分干净。
4.2 Skills：把团队的流程固化成技能包
Skills 是 OpenCode 中最能体现“团队协作”价值的功能。它的本质是把一段固定的分析/操作流程写成“技能”，然后像插件一样让 Agent 在不同项目里复用。很多从 Claude Code 转过来的朋友喜欢拿它跟 oh-my-claudecode 的技能包对比，实际上 OpenCode 的技能机制和它十分相似，甚至可以迁移使用。
在项目根目录创建 .opencode/skills 目录，里面每个子目录就是一个技能。技能目录下需要有一个 SKILL.md 文件来定义技能内容。我举个例子，我给自己写的一个“前端路由审查”技能：
--- name: frontend-route-review description: 审查前端路由配置，找出路径冲突、权限缺失和重复路由 --- ## 审查步骤 1. 找到项目中的路由配置文件（如 router.ts、routes.ts、app router 目录） 2. 列出所有路由路径，关注动态参数和嵌套路由 3. 检查每个路由是否配置了访问权限和页面标题 4. 输出审查结果，按“冲突”“权限缺失”“建议”三类分组启动 OpenCode 后，你只要说“用前端路由审查技能帮我 scan 一下 app 目录”，Agent 就会按照这个流程去执行，而不是每次你都要手动念一遍长篇提示词。团队里可以把技能放在 git 管理的共享目录里，新人拉下来就自动拥有老手的分析套路。我甚至看到有团队把“代码评审 checklist”做成了技能，让 Agent 在每次提交前自动跑一遍，效果非常直观。
Skills 的注意点在于：技能内容要写“步骤化”的指令，少写模糊的形容词。像“认真检查”“仔细分析”这种词，模型很难转化为具体行动。好的技能应该是“打开 X 文件 → 查找 Y 模式 → 生成 Z 报告”这样一步一步可执行的动作。
4.3 VS Code 插件与 IDEA 插件使用心得
终端 TUI 虽然强大，但有些场景还是离不开 IDE，最常见的就是查看代码高亮、跳转定义、以及同时对比多个文件的修改。OpenCode 官方出了 VS Code 插件和 JetBrains 插件，这是很多用户最早接触它的入口。
VS Code 插件安装很简单，在扩展商店搜索 OpenCode 安装后，它会出现在侧边栏。使用起来和终端版的核心逻辑一致，但多了一个“在当前文件上下文提问”的便利能力。你可以不选中任何内容，直接在打开的代码文件旁让它解释整个文件的功能；也可以选中几行，让它针对选中片段做重构。因为 IDE 本身知道光标位置和选中内容，插件会自动把这些位置信息传递给 Agent，效果比在终端里手打文件路径直观很多。
JetBrains 系插件（比如 IDEA）用法类似，集成度也很高。需要注意的一点是，插件版本和命令行版本的兼容性：如果插件提示“需要更新核心组件”，最好是让插件自动下载匹配的 opencode 核心库，不要手动指定一个旧版本，否则可能报协议不匹配的错误。
插件形态解决了一个我一直觉得 TUI 体验不够好的痛点：修改 diff 的查看。在 IDE 插件里，Agent 改完文件后，你可以直接用 IDEA 的版本控制面板看 diff，逐行确认哪些改动要留、哪些要回退。这种“改动审计”体验在纯终端里很难做到。
4.4 桌面版适合谁
桌面版（opencode desktop）和 IDE 插件不是一回事。它是独立应用，更像是给不太熟悉终端的人准备的可视化入口。界面里集成了项目选择、会话管理和模型开关，底层还是调用同样的 opencode 核心引擎。
我建议桌面版的主要使用场景是：你在项目开会、写文档或者做代码 review 的时候，旁边开一个桌面版窗口当作“AI 助手”随时问问题，不必切到终端。这个形态对产品经理、技术负责人这类“不天天写代码但需要理解代码”的人很友好。不过说实话，对于天天泡在终端里的开发者，桌面版只是锦上添花，TUI 才是效率之王。两者可以共存，同一个配置文件和密钥，互不干扰。
5. 实战配置：接老项目、Playwright 排查与社区技能
5.1 用 OpenCode 接手一个陌生老项目
很多人的第一个真实需求不是写新代码，而是“接手别人留下的项目”。这种场景下 OpenCode 的价值特别大，因为它的定位本来就包含“项目级理解”。
第一次打开老项目时，我建议执行：
opencode /init这个命令会让 Agent 通读一遍项目文件结构、关键配置文件、入口文件和测试命令，然后生成一份类似 AGENTS.md 的项目说明。这个文件会作为后续所有会话的全局上下文，让 Agent 不用每次都从头探索。它本质上是在给 AI 建一个项目的“知识地图”。
然后，我会再手动补充一段话，类似：
先不要修改任何代码。请阅读项目的 README、docs 目录和最近 5 次 git commit message，总结一下这个项目的架构和当前开发状态。这个“先读后改”的步骤非常重要。很多人一上来就让 Agent 直接改 bug，结果它对项目结构完全没概念，改出来的东西既不符合代码风格，又破坏了既有行为。正确的做法是给 Agent 一个“勘探期”，让它先把仓库的地图画出来，再谈动手。
接手老项目时权限控制格外重要。老项目常常有历史遗留的数据库迁移脚本、危险的构建命令，不小心执行可能造成不可逆损失。所以我把 permission 里的 run 和 bash 都设为 ask，只有确认过 Script 内容后才放行。另外，任何改动都先让 Agent 用 git diff 输出汇总，人工确认后再提交。
5.2 用 Playwright 真实地测试前端 Bug
另一个很有代表性的场景是“让 Agent 解决前端 bug”。这里的痛点在于：AI 能改代码，但它怎么知道按钮到底能不能点？页面到底长什么样？OpenCode 集成了 Playwright 之后，这个问题有了标准答案。
实操上我会这样说：
用 Playwright 打开本地 dev server 的 /login 页面，点击登录按钮，把 console 报错和网络请求失败信息截图下来，然后分析原因。Agent 会启动一个无头浏览器，访问页面，模拟点击，抓取控制台报错，再把内容整合进它的推理过程。这比自己开浏览器手动复现快很多，尤其是在需要重复多次“修改 → 验证”的循环里，Agent 可以直接跑一遍 Playwright，根据报错继续改，改完再跑一遍，直到通过。
用 Playwright 测试时我踩过几个坑。第一是本地 dev server 必须已经启动，否则 Agent 会访问一个空地址，误以为页面白屏是代码问题。我在指令里通常会明确写“先启动 npm run dev，等端口监听成功后再用 Playwright 访问”。第二是要限定测试范围，不要让 Agent 对生产环境执行点击操作，特别是涉及支付、删除这类危险动作，应该用 mock 数据或 staging 环境。第三是无头浏览器可能测不出某些交互细节，比如 hover 状态、滚动加载，这些我自己会先手动确认一遍再交给 Agent 看日志。
5.3 用 ccswitch 管理多套模型配置
如果你经常在多个模型服务之间切换，手动改 opencode.json 会非常烦躁。社区里常见的做法是利用配置切换工具，其中 ccswitch 是被提起比较多的一个。
ccswitch 原本的目标是给 Claude Code 做多 Provider 配置管理，支持把不同 API 地址、密钥、模型打包成一个个“配置档”，然后一键切换。因为 OpenCode 的配置模型也是文件式的，所以 ccswitch 也能兼容管理 opencode 的配置。你可以把“公司内部模型”“个人付费账号”“本地 Ollama”分别存成几个配置档，在项目之间或不同时段快速切换。
这类配置切换工具的使用思路都是一样的：本质是维护一组环境变量或配置文件模板，切换时重写当前激活的版本。所以我建议不要把密钥明文写在配置文件里，而是用类似 {env:XXX_API_KEY} 的占位符，让工具只切换 API 地址和模型名，密钥统一从环境变量读取。这样即使配置档被误分享，也不会泄露密钥。
5.4 社区技能包：superpowers、memory 与长会话维护
在 OpenCode 的生态里，社区贡献是它比商业产品活跃得多的一个原因。比如有开发者把 Claude Code 圈的“superpowers”插件理念移植到 OpenCode，让 Agent 具备更强的自我规划能力；也有像 oh-my-claudecode 这样的项目专门整理了大量质量较高的技能包。安装这些技能包的方式很简单：把对应仓库里的技能目录复制到项目的 .opencode/skills 下，重启 OpenCode 就能生效。
另外一个常被讨论的功能是 memory，也就是让 Agent 在多个会话之间记住项目偏好和历史决策。OpenCode 会把长期记忆写入项目说明文件或者独立的记忆目录。默认情况下我不建议无限积累记忆，因为无关记忆越多，模型被干扰的概率越大，token 消耗也越高。我的经验是，长会话超过三四十轮之后，主动开一个新会话，把之前的结论性内容手动总结给新会话。
memory 和技能的区别要澄清一下：技能是“操作方法”，告诉模型遇到什么场景怎么做；memory 是“历史事实”，告诉它项目之前做了什么决策、为什么这么做。两者配合能让 Agent 表现得更像团队里的老成员，但这个“老成员”的记忆上限是有限的，你要学会帮它定期归档和丢弃。
6. 错误排查：常见报错、性能问题和处理锦囊
6.1 “无法识别 cmdlet”类问题全解析
开头章节已经重点讲了安装时 PATH 的问题，这里把它和另外两个类似的坑放在一起做成速查表：
| 报错信息 | 出现场景 | 处理方式 |
|---|---|---|
| 无法将“opencode”项识别为 cmdlet... | Windows PowerShell 首次运行 | 检查 PATH；重装；用 Set-Alias 临时顶上 |
| zsh: command not found: opencode | macOS/Linux 新装后 | 执行 source ~/.zshrc 或重启终端；检查安装目录 |
| bash: opencode: command not found | Linux 通过 Go 安装后 | 检查 ~/go/bin 是否在 PATH |
| Unsupported version / invalid protocol | IDE 插件版本不匹配 | 卸载插件重装，让插件自动拉取配套核心组件 |
| 版本信息显示 old version | npm 装到旧版 | npm update -g opencode-ai 或重跑安装脚本 |
这一类问题的共同点：不是 OpenCode 本身坏了，而是环境变量、版本匹配的问题。排查思路是先从“命令能不能被找到”开始，再到“版本是否匹配”，最后才轮到“程序逻辑是否出错”。
6.2 “unexpected server error”与模型服务异常
我看到有很多人搜过这样一条报错：
opencode error: unexpected server error. check server log这个报错在 OpenCode 启动或运行任务时出现，直接翻译就是“意外的服务器错误，请检查服务器日志”。结合上下文，绝大多数时候它和你的本地代码无关，而是模型 API 端返回了非正常响应。
常见的具体情况有这么几类：
- API Key 无效或已过期，服务端返回 401，但客户端把它当作“意外错误”展示。
- 模型名不存在或者已经被服务商下架，返回 404。
- 请求量超过限额，返回 429。
- 服务商临时故障，返回 5xx。
排查的步骤我建议按这个顺序来做：
- 打开 OpenCode 的日志目录，找到最近的 log 文件，看里面记录的 HTTP 状态码。
- 用 curl 手动请求一次同样的 API 地址，确认服务端是否可达、Key 是否有效。
- 检查模型名是否与 config 完全一致，注意大小写和前后缀。
- 确认当前网络环境能正常访问对应的 API 域名。
- 如果几天前还正常、今天突然报错，优先怀疑服务商调整或免费额度到期。
说到“免费模型下线”这一点，我用一句话总结：模型 API 服务本质是在线服务，下线和变更都很正常，不要把你的工作流变成单点依赖。有价值的不是某一条免费通道，而是你的配置系统能在一小时内切换到新的服务商。
6.3 长会话变慢与上下文膨胀
用了几个星期之后，你可能会发现：同一个会话里，问题越到后面，Agent 回复越慢、越容易答非所问。这不是模型变笨了，而是上下文窗口里的历史内容不断增加，既占了 token 额度，又干扰了模型的注意力。
解决方法分两个层次。第一层，主动换新会话。重要结论和中间产物及时用文字确认并记录，然后 /new 开新会话。新会话清爽很多。第二层，利用 /compact 或等价命令压缩上下文。这个命令会把冗长的历史对话压缩成摘要，再接续当前任务。它适合那些暂时不能中断的场景，比如 Agent 正在分多个步骤重构一个大模块，我不想让它忘掉上下文。
另外一个容易被忽略的问题是 memory 文件和项目说明文件越写越长。这些文件虽然不在对话里，但每次请求都会被作为上下文一起发送，也会占用 token。我建议每两周 review 一次 AGENTS.md 或全局指令文件，删掉过期内容，保持精简。
6.4 弱网、超时与断线重连
终端 agent 工具对网络的敏感度比 IDE 插件高不少，因为它的整个工作流都要和服务端交互。我在弱网环境下遇到最多的是“请求超时”和“连接被重置”。这类问题一般不是 OpenCode 自己的 bug，而是 API 服务端响应太慢，客户端走了超时逻辑。
遇到这种情况，我一般先看日志确认是服务端慢还是网络丢包。如果是单次大文件或复杂项目分析造成的超时，可以把任务拆小，分几次让 Agent 做，避免一次对话里塞入大量代码。如果是网络不稳定，比起反复重试，更推荐用断点续传式的会话恢复：重新执行 opencode 后用 /resume 回到之前的会话，让上下文按已经分析的部分继续，而不是从头再来。
此外，把超时时间调大也是可行的。在 opencode.json 里可以配置请求相关参数，比如把超时从默认值调到 120 秒甚至更长，适配某些响应特别慢的大模型。这里没有通用标准，你可以根据自己常用模型的平均响应时间来做微调，原则是“能容忍偶尔慢，但不能因为慢而频繁断流”。
7. 使用一段时间后，我自己的几点体会
我不太喜欢在文章最后写那种“总之这个工具很好”的总结，还是说几个真实感受吧。
第一个体会是，这类终端 agent 工具的上限，很大程度上取决于你对它的“放手程度”和“信任边界”的平衡。刚开始我几乎每一步都确认，虽然安全，但效率提升有限。后来我把文件名修改、类型定义这类低风险动作设为自动允许，把执行测试、改动生产配置这类高风险动作保留手动确认，整个配合节奏顺畅很多。这个“信任阶梯”建议一边用一边调。
第二个体会是，配置文件一定要纳入版本控制。我的 opencode.json 和 .opencode/skills 目录都在 git 里，团队成员拉下来就能用同一套规则。这带来的隐性好处是：新同学入职第一天打开仓库，不用听我讲半小时项目背景，直接用 OpenCode 就能大致了解项目结构，这种“以工具为载体传承上下文”的方式，比文档和口头交流都更接近实操。
第三个体会是关于成本。很多人一想到 AI 编程就担心 API 费用，但我的实际经验是，把 OpenCode 用在“读代码”“写测试”“批量重构”这些场景，性价比其实很高。真正费钱的往往是你放任 Agent 进入无限循环还不检查，让它反复改同一个问题改了几十轮。方法就是前面说的：定期开新会话、压缩上下文、明确任务边界。工具很重要，但用工具的方法和约束，永远比工具本身更值钱。
最后再补充一个小技巧：如果你从 Claude Code 迁移过来，最舒服的上手方式是先把原来项目里的 CLAUDE.md 内容迁移到 opencode 的 instruction 字段或 AGENTS.md，这样 Agent 对你的代码风格和项目约束的适应成本会低很多。迁移之后微调一下语气和规则，基本无缝衔接。OpenCode 这个生态还在快速迭代，今天的功能过了两个月可能又有大变化，保持配置文件的简洁、技能包的模块化，才能在大版本升级的时候少踩坑。
