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 这些工具比它的优势在哪很多人问过我都是终端 agentOpenCode 和 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 用户用 Homebrewbrew install sst/tap/opencodeLinux 或 Windows 可以用 npmnpm install -g opencode-ai用 npm 的优点是对前端工程师来说特别熟悉而且可以配合 nvm 管理不同 Node 版本缺点是有时候 npm 镜像源同步不及时装到的可能不是最新版。如果你发现版本老得离谱可以换成官方脚本重装。第三种是 Go 工具链编译安装。这种适合那些喜欢自己掌控构建过程的人go install github.com/sst/opencodelatest需要注意用 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)/binWindows 的话在用户环境变量的 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_KEYsk-ant-xxxxx export OPENAI_API_KEYsk-proj-xxxxx export OPENCODE_MODELclaude-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: opencodemacOS/Linux 新装后执行 source ~/.zshrc 或重启终端检查安装目录bash: opencode: command not foundLinux 通过 Go 安装后检查 ~/go/bin 是否在 PATHUnsupported version / invalid protocolIDE 插件版本不匹配卸载插件重装让插件自动拉取配套核心组件版本信息显示 old versionnpm 装到旧版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 这个生态还在快速迭代今天的功能过了两个月可能又有大变化保持配置文件的简洁、技能包的模块化才能在大版本升级的时候少踩坑。