最近AI编程Agent的赛道是真的热闹,Claude Code、Codex、Pi一个接一个往外冒,我一度以为命令行里写代码的终局就是某一家大厂的封闭工具。直到有个朋友甩给我一句"你试试opencode",我才发现这个用Go写的开源终端工具早就悄悄长成了完全不一样的东西。它不是某个模型的私有客户端,而是一个能接几乎所有主流模型、自带漂亮TUI、支持Skill扩展机制的开源Agent,最离谱的是,它跑在我那台服役五年的老笔记本上居然比一堆Electron壳子流畅得多。折腾了两周之后,我决定把从安装、配置模型到实战项目排查的经验全部写下来,给正在观望或者已经在踩坑的人一个完整参考。
1. opencode是什么:一个被严重低估的终端AI编程Agent
1.1 它和普通代码补全工具的区别在哪
如果只把opencode当成ChatGPT的终端套壳,那就完全搞错了它的定位。传统补全工具是你写代码它猜下一行,而opencode是一个真正能在你的仓库里独立干活的Agent。你给它一个任务,它会自己读目录结构、打开相关文件、分析依赖关系、执行终端命令、看命令输出、再根据报错修改代码,直到完成整个流程。
我举个具体例子。有次我需要把一个Python脚本改成异步版本,如果是普通补全工具,它只能看着我光标的位置,最多生成一个函数。但opencode的任务是"把整个脚本的同步IO部分改成asyncio并保证逻辑不变",它会先扫描所有文件,找到所有涉及文件读写和网络请求的地方,列出改造方案,再逐个文件修改,最后跑一遍测试给我看结果。这个过程里我基本没碰过一次键盘。
这种"端到端自主执行"的能力,才是它被称为Agent而不是"智能补全"的根本原因。而opencode把这件事做成了开源、可定制、不锁定任何一家模型厂商的产品,这在整个赛道里都算少见。
1.2 Charm团队的底子:为什么它的终端界面这么能打
opencode是Charm团队出的开源项目,MIT协议,代码全在GitHub上。如果你对Go语言的终端生态有了解,应该听过Bubble Tea、Lip Gloss、Glamour这些库,都是Charm家的作品,几乎所有Go写的漂亮终端工具都离不开这套组件。opencode的TUI界面正是建立在这些成熟组件之上,所以它跑起来的美观程度和交互流畅度,跟那些用文本硬怼出来的Agent工具完全不在一个层级。
我第一次在终端里敲opencode的时候,界面加载出来的一瞬间确实愣了一下。左侧是会话列表和文件树,中间是对话和代码改动区,右侧是Agent正在执行的命令面板,底部的输入框还有语法高亮。整个界面有分区、有色彩、有快捷键提示,但又不花哨到影响阅读。对一个每天要在终端里待十个小时的人来说,这种视觉体验本身就是效率的一部分。
1.3 开源协议和社区生态的隐藏价值
MIT协议意味着你可以把opencode嵌入到自己的内部工具链里,甚至改源码做定制。我在生产环境里见过有人把它做成了内部代码审查机器人,还有人把它接进了CI流程自动修编译错误。社区生态这段时间也长出了不少好东西,比如热词里反复出现的oh-my-claudecode这类配置增强项目,已经有人做了支持opencode的分支,还有各种Skill库可以直接安装。
就拿"opencode 2.0"来说,热词里能刷到这个版本,说明更新频率和社区关注度都挺高。2.x版本一个明显的变化是Agent模式比早期更稳定了,多轮工具调用不再那么容易跑飞,启动速度也有优化。对一个仍在快速迭代的开源工具,这种"社区能跟上、版本在进化"的状态,比一堆PPT概念重要得多。
2. 安装与环境准备:从一行命令到能跑通
2.1 各平台安装命令对比
opencode的安装方式在官方文档里给得很全,我这里把实际验证过的几条命令整理成表格:
| 平台 | 安装命令 | 备注 |
|---|---|---|
| macOS | brew install charmbracelet/tap/opencode | Homebrew方式最省心 |
| macOS / Linux | curl -fsSL https://opencode.ai/install | bash | 官方脚本,自动装到用户目录 |
| 任意平台(有Go环境) | go install github.com/charmbracelet/opencode@latest | 适合想固定版本的开发者 |
| Windows | iwr https://opencode.ai/install.ps1 | iex | PowerShell执行官方脚本 |
我个人的建议是,如果只是为了尝鲜,macOS直接走Homebrew,Windows直接走PowerShell的官方脚本。如果你已经装了Go并且平时有管理Go版本的习惯,go install那个方式更干净,因为二进制会进入$GOPATH/bin,和你现有的工具链统一管理。
安装完成后执行opencode --version,能输出版本号就说明这一步过了。这里提醒一句,opencode的TUI界面启动之后,如果发现是黑底白字没有任何样式,大概率是你终端的颜色配置有问题,装一个支持truecolor的终端模拟器(比如iTerm2、Windows Terminal、kitty)就能解决。
2.2 踩坑实录:Windows下"无法将opencode识别为cmdlet"
热词里那条"opencode : 无法将'opencode'项识别为 cmdlet、函数、脚本文件或可运行程序的名称"我能想象到提问的人有多崩溃,因为我自己在Windows机器上也遇到过一模一样的问题。原因其实特别简单:安装脚本把可执行文件放到了用户目录下的某个子文件夹,但那个文件夹没有被加入PowerShell的PATH环境变量。
常见的情况是,官方PowerShell安装脚本把二进制放到了%USERPROFILE%\.local\bin或%LOCALAPPDATA%\opencode,然后尝试往用户PATH里写入,但如果你终端是从旧窗口打开的,PATH不会自动刷新。解决步骤如下:
# 确认安装位置 dir $env:USERPROFILE\.local\bin\opencode* # 如果文件存在,手动把目录加进PATH [Environment]::SetEnvironmentVariable("Path", $env:USERPROFILE + "\.local\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")改完PATH之后关掉所有终端窗口重新打开一次,再执行opencode就正常了。另外有一种隐蔽情况是从Git Bash里装的脚本,PATH写进了~/.bashrc,换了PowerShell环境当然不认。这种就把上面的命令再执行一遍,问题自然消失。
2.3 初始化:第一次启动后必做的两件事
第一件是登录模型服务商,opencode auth login会列出支持的Provider,包括Anthropic、OpenAI、Google、Groq、OpenRouter等,选定之后会让你填API Key或者走OAuth流程。如果你不知道自己该选哪个,建议先用OpenRouter,一个Key可以访问几十种模型,后面切换模型也不用重新登录。
第二件事是打开配置文件看一眼。默认配置文件路径在~/.config/opencode/opencode.json(Windows是%USERPROFILE%\.config\opencode\opencode.json)。第一次启动时opencode会生成一个基础的JSON,里面大概长这样:
{ "$schema": "opencode.json", "provider": { "openrouter": { "models": [ "anthropic/claude-sonnet-4", "openai/gpt-4o-mini", "deepseek/deepseek-chat" ] } } }这里provider下面配置的是Provider名称,models列表是这个Provider下你计划经常用的模型。配置好之后在TUI里按快捷键就能在模型之间切换,不用重新登录。这个文件是后续所有模型接入和厂商切换的核心,值得花时间研究明白。
3. 模型怎么接:免费模型、Ollama本地模型、多供应商切换
3.1 opencode的模型接入逻辑:为什么不锁定任何一家
opencode没有自己的模型,它只是个外壳和大脑的调度器,底层对话走的是各家模型的API。这跟Claude Code绑定Claude、Codex绑定GPT逻辑上完全不同,反而让它成了我这种"哪种模型划算用哪种"的人的首选。
热词里"opencode免费模型"搜索量不低,这事确实可行,但实现路径上得动点脑筋。opencode本身没有内嵌免费额度,它只是把免费模型当成普通模型接进来用。免费模型的来源通常有三个:OpenRouter上标注:free的模型端点、Groq等平台的免费额度、以及本地跑的Ollama。
需要注意,免费模型和写代码的模型根本不是一个物种。OpenRouter上那些:free端点,不少是开源小模型,做文案润色没问题,让它们改一个复杂的TypeScript类型错误就会开始胡说八道。我的经验是,免费模型可以用来做代码解释、写测试注释、生成commit message这类低风险任务,真正改业务逻辑还是得上能力足够的商用模型或者本地大参数模型。
3.2 配置Ollama本地模型的完整示例
本地模型是目前唯一能做到完全免费且数据不出机器的方案,opencode对Ollama的原生支持做得很顺。前提是你先把Ollama装好,并且已经拉了一个代码能力过得去的模型,比如qwen2.5-coder:14b或者codellama:13b,硬件至少16G内存才能跑得像样。
配置文件这样写:
{ "$schema": "opencode.json", "provider": { "ollama": { "models": [ "qwen2.5-coder:14b", "codellama:13b" ] } } }Ollama的地址默认是http://localhost:11434,opencode默认就会连这个端口,不用额外配置。启动TUI之后切换到对应的本地模型就能用。我实测下来,14B级别的模型在32G内存的机器上,做"变量重命名、补齐测试、解释函数逻辑"这类轻量任务完全能顶住,但让它理解整个项目架构后做跨文件重构就比较吃力,会回复得比较慢,偶尔还需要你掰碎了给它讲清楚。
3.3 多供应商同时配置与CCSwitch联动
实际用起来,大多数人不会是单一模型用到底。我的日常是:GPT-4o写业务逻辑,Claude Sonnet做代码审查,本地Qwen处理那些不值得花API费用的重复任务。opencode支持在同一个配置文件里注册多个Provider,然后运行时随时切换。
{ "provider": { "openai": { "models": ["gpt-4o", "gpt-4o-mini"] }, "anthropic": { "models": ["claude-sonnet-4"] }, "ollama": { "models": ["qwen2.5-coder:14b"] } } }热词里那条"ccswitch配置opencode",说的是CCSwitch这个工具。它本质上是个配置和密钥管理器,可以在你本地点一下鼠标就切换不同场景下的API Key和模型组合。如果你手上有多个模型的Key、或者需要经常在不同"配置环境"之间切来切去,CCSwitch挺实用的。它跟opencode的联动原理也很简单,就是通过共享配置文件的形式,让opencode读取CCSwitch生成的那份JSON来识别当前应该用哪个Provider。明白这个原理之后,你甚至可以自己写脚本实现类似的功能,不一定非要用某个固定工具。
3.4 模型切换的隐藏判断标准
接模型时很多人只看名字,忽略了一个对实际体验影响极大的参数:上下文窗口。opencode的Agent模式会在对话中不断把工具执行结果、文件内容塞进上下文,如果模型上下文窗口太小,很快就"失忆"了。用配置里的maxTokens或者模型自带的上下文限制,把这些信息记进你的选型清单里。
我在配置里常用的组合是"大窗口模型做长会话+小模型做快速单项任务":比如Claude Sonnet或者Gemini大窗口版本跑Agent任务,GPT-4o-mini跑单文件解释和提交信息生成。这个搭配成本合理,也不容易跑着跑着就断片。
4. 核心机制拆解:Agent循环、Skills、Memory、LSP如何协同
4.1 一次对话背后的完整链路
opencode干活的基本循环,我把它拆成五步:
- 读取上下文:根据你的提示和当前目录,收集相关文件内容、项目结构、可能的Git历史信息。
- 规划动作:在内部推理下一步该做什么,是读文件、编辑文件、还是执行终端命令。
- 调用工具:执行具体动作,比如调用
read_file、write_file、session_execute。 - 观察结果:读取命令输出、编译报错、测试结果,判断是否达到目标。
- 迭代:没解决就回到第1步,解决就总结输出。
这整个循环都不是一次性的,而是持续到任务完成。所以你在TUI里能看到它在"思考"和"执行"之间跳来跳去,有时候还会自己修正之前的方案。opencode的工具集覆盖了写代码的核心诉求:读写文件、查找代码、执行终端命令、连LSP拿符号信息。它没有像某些工具那样什么都往Agent里塞,这种克制的设计反而让核心路径很稳定。
4.2 Skills扩展机制:给Agent装上新技能
Skill是opencode这套系统里最有想象力的部分,本质上是"通过一个目录加一份说明书,让Agent学会一种新的工作流"。一个Skill就是一个文件夹,里面必须有SKILL.md文件,里面写清楚这个技能是干什么的、在什么情况下触发、执行步骤是什么。你还可以放辅助脚本、模板文件、参考资料。
Skill放两个位置都行:全局位置~/.config/opencode/skills对所有项目生效,项目位置.opencode/skills只对当前仓库生效。我在团队里推广的时候,一般是把通用的代码规范、模板放全局,把项目专属的发布流程放在仓库里。
举个例子,我写过一个"前端修复"Skill,流程是:先让Agent用Playwright复现用户上报的bug → 看console报错 → 定位到具体组件 → 修改代码 → 跑相关单测 → 最后生成一份给QA的回归说明。写完之后,我只需要在对话里提一句"用前端修复流程处理这个bug",它就会自动按这套标准走,不用每次重新啰嗦提示词。
4.3 Memory:让Agent"记住"你的偏好
Memory解决的痛点是——每次新会话,Agent都像第一次认识你,你以前说过"别动那个文件""测试要用pytest不要用unittest",它转头就忘。opencode的Memory机制会把重要偏好持久化保存,后续对话开始时自动加载。
默认的memory文件在配置目录下,格式是纯文本或者JSON。你可以直接编辑文件写入长期记忆,也可以在对话里让它记住某件事,它会自己把内容写进记忆。我在新的机器人项目里跟它说过"数据库迁移文件不要自动生成,需要人工review",过了几天在处理另一个模块时它主动提到要注意这个约束,那种"它居然记得"的体验是真实存在的。
4.4 LSP集成:凭什么它比grep更懂代码
热词里有"opencode memory"也有"LSP"的隐含需求,其实这两个机制的协作才是我觉得它专业的地方。LSP(Language Server Protocol)就是让工具通过语言服务器获取"类型信息、定义跳转、查找引用"等专业能力,而不是靠纯文本搜索。普通文本搜索能搜到变量名,但搜不到"这个变量是从哪个类型推断出来的"。LSP能。
opencode通过LSP拿到了这些语义信息之后,在改代码的时候就能少犯"只看局部文本、改错重名变量"的毛病。这一点在大型前端项目或者Java项目里尤其明显,TypeScript的交叉引用和Java的继承体系用grep根本看不出来。如果你在配置里把对应语言的LSP server配好,Agent改代码的准确率会有一个质的提升。
5. 三类实战:接手存量项目、前端Bug复现修复、定制团队Skill
5.1 实战一:把一个没有文档的老项目交给opencode
那是个用Python Flask写的老服务,没有README、没有注释、模块间调用关系混乱。我的目标是先让它给我讲清楚这个系统大概是怎么运转的,再进行一处功能修改。
我的指令很简单:"扫描项目结构,先告诉我这个项目是干什么的、请求入口在哪、数据是怎么流转的。不要改任何代码。"它就自己开始看目录、读路由配置文件、找模型定义、理清视图函数和数据库表的映射关系。几分钟之后给了我一份像样的系统说明,还顺手标出了几个明显的死代码和重复定义的地方。
接下来我说"把用户注册接口的邮箱验证逻辑去掉,并同步修改对应的前端提示"。它先定位到注册接口,找到邮件发送代码,把验证流程移除,接着去搜索前端所有关于"邮箱验证"的文案,一并更新了对应的单测。整个过程我只需要确认关键改动,不用指挥每一个细节。对于"接手开发项目"这个热词,这条工作流几乎就是标准答案。
5.2 实战二:用Playwright复现并修复前端Bug
"opencode playwright 怎么测试前端bug"这个热词背后是个很实际的场景——前端Bug你光看代码往往看不出问题,必须先把Bug复现出来。opencode支持调用终端命令,于是我们可以让它用Playwright写自动化脚本来复现问题。
我遇到过一个真实案例:用户反馈某个表单在Safari下日期选择器点不动。我让opencode写一个Playwright脚本,在Safari模式下打开页面、点击日期输入框、尝试选择日期。它生成脚本跑了一遍,果然复现了点击后选择面板不弹出的问题。然后它接着分析可能是Safari对input[type=date]的事件委托处理有问题,又去翻项目里的日期组件源码,最后定位到是一个第三方库版本过旧导致的兼容性问题。升级库之后,它用Playwright重新跑了一遍全流程,确认修复有效才收工。
这个例子说明的核心点是:Agent的价值不只在写代码,把"验证"这一步自动化了,才能形成完整的闭环。opencode能跑终端命令和脚本,这个看似基础的能力,在"测试前端bug"这个场景里成了关键。
5.3 实战三:写一个团队专属Skill的过程记录
我来还原一个Skill从无到有的过程。第一步,建目录结构:
.opencode/skills/code-review/ ├── SKILL.md └── review_rules.md第二步写SKILL.md,内容大概是:技能名称、适用场景(提交PR前对代码进行自审)、执行步骤(先看Git diff → 按规范检查命名、错误处理、安全风险 → 输出问题清单和建议)。还可以在review_rules.md里放上团队自定义的规范细节。第三步就让opencode加载这个Skill,在对话里输入"按照code-review流程审查我当前的改动"。
它会严格按照SKILL.md里写的步骤逐一执行,最后输出的审查意见比我们以前开代码审查会让新人发言高效得多。这套方案的价值在于:它把"经验"固化成文件,新人加入团队时只需把Skill库clone下来,Agent就能代劳大部分基础审查工作。我们团队现在整个Skill目录已经积累了七八个这样的技能包,覆盖代码审查、接口联调检查、数据库迁移确认等场景。
6. IDE与桌面端:VSCode插件、JetBrains插件、Desktop版怎么选
6.1 VSCode插件的正确打开方式
热词里"opencode vscode插件""vscode opencode插件"指向的是同一个东西:官方VSCode扩展。这个插件不是把opencode重写成IDE插件,而是把terminal版作为后端,插件在前端提供一个图形化界面来操作Terminal里的Agent。
装上插件之后,你可以在VSCode侧边栏看到会话树、文件变更区、模型选择器,再也不用切到单独的终端窗口了。对VSCode用户来说,最顺滑的使用方式是:先把opencode的终端版装好、配置好模型,然后在VSCode插件里选择"连接到本机已有的opencode服务"。这样两边数据是通的,你在插件里发了指令,终端版那边也能看到完整的执行过程,排查问题更方便。
6.2 JetBrains全家桶的接入体验
"opencode jetbrains idea 插件"和"idea opencode插件"是同一个东西。JetBrains系插件目前覆盖IntelliJ IDEA、PyCharm、GoLand等主要IDE。安装路径是Settings → Plugins → 搜opencode,装完重启IDE之后,右侧会多一个工具窗口。
对比起来,VSCode插件更简洁,JetBrains插件在代码定位上做得更深入一点,能直接把Agent修改的代码以diff形式展示在编辑器里,点一下就能接受或拒绝,这个交互很符合JetBrains用户的使用习惯。另外你可以直接把光标停在某个方法上,右键让opencode"解释这个方法"或者"生成单测",它会把当前上下文自动带进对话,省去一大段描述。
6.3 桌面版到底多了什么
"opencode桌面版"或者"opencode desktop"指的是官方推出的桌面应用。跟终端版和IDE插件相比,桌面版的优势是独立窗口、有完整会话历史和项目列表管理。你可以同时开三四个项目,每个项目有自己的Agent会话,互不干扰,而且什么时候退出重开,会话记录都还在。
它的定位更像一个"Agent工作台",适合那些重度使用者。如果你每天要同时处理几个仓库、经常需要回溯以前跟Agent的对话,桌面版的体验确实比终端更舒适。但如果你只是偶尔用一下,终端版完全够了,没必要再多开一个Electron进程吃内存。我自己的实际选择是:写代码的主力场景用终端版,需要同时盯多个项目时开桌面版,IDE插件则是为了顺手选中代码解释一下才用。
7. 同赛道横评:opencode、Claude Code、Codex、Pi怎么选
7.1 四个主流Agent工具的硬对比
"opencode codex claude code"和"opencode codex pi哪个agent好用"这两个热词说明大家确实在认真比较这几款工具。我整理一个基于实际使用的表:
| 工具 | 开源协议 | 底层语言 | 界面形态 | 模型绑定 | 扩展机制 | 适合场景 |
|---|---|---|---|---|---|---|
| opencode | MIT | Go | 终端TUI / IDE插件 / 桌面版 | 不绑定,任意模型 | Skill + Memory + MCP | 全栈开发、自定义工作流、本地模型 |
| Claude Code | 商业 | TypeScript | 终端 | 主要绑Claude | 插件 / 命令 | Claude重度用户、企业级AI协作 |
| Codex | 商业 | Rust | 终端 / IDE | 主要绑OpenAI/GitHub | 插件 / Skills | GitHub深度集成、OpenAI生态 |
| Pi | 商业 | 未知 | 终端 | 主要绑自家模型 | 插件体系 | 追求开箱即用、轻量对话 |
这表里最核心的分野是"模型绑定"。opencode是唯一把"模型自由"作为默认设计原则的,其余几个基本都跟自己的模型生态绑定。当然,Claude Code也能配其他模型的API,Codex也开放给了更多模型,但从社区主流的用法来看,绑定关系在心里是根深蒂固的。
7.2 我选opencode的三个决定性理由
第一是模型自由。我的API Key来自多个渠道,有时候这个模型挂了马上切另一个,opencode的切换成本几乎为零。第二是扩展性。Skill这个机制让我能把团队的经验、规范、流程固化到Agent里,这是其他封闭工具做不到、或者做起来很别扭的。第三是开源透明。MIT协议意味着我可以放心地把它嵌进自己的自动化流程,出了问题能自己改,而不需要等厂商。
这不代表opencode没有短板。它的Agent在极端复杂的任务上,稳定性跟Claude Code这种闭源打磨的工具有差距;社区文档的完善度也还有提升空间;Skill生态虽然有社区贡献,但积累远不如商用工具的插件市场。而且,一旦你同时用了多个Skill和插件,配置文件的复杂度会快速上升,学习成本不算低。
7.3 什么情况下不要选opencode
如果你是一个只依赖Claude、也不想折腾配置的人,Claude Code的开箱即用体验确实更顺滑。如果你整个研发流程都在GitHub上,Codex和GitHub的深度集成能省不少事。如果你需要的是一个"下载就能聊"的工具,Pi这种轻量级产品会更合适。
反过来,如果你像我一样需要同时管理多个模型供应商、想把团队的开发规范固化到Agent里、或者对"代码Agent数据不出机器"有硬性要求(本地模型),那这个赛道里目前还真找不到比opencode更合适的选择。作为参考,我们团队现在的做法是给每位成员装好opencode,再配一份统一的团队Skill库,既保留了个人的模型选择自由,又保证了输出风格的一致。
8. 高频报错排查:两个让我花了整晚的坑
8.1 Windows下的cmdlet识别失败:不止PATH一个原因
前文提过Windows下最常见的识别问题,我这边再补一个后续排查的细节。有一次我明明确认文件在PATH目录里了,opencode命令依然报"无法将opencode项识别为cmdlet",最后发现是杀毒软件把刚下载的二进制隔离了。给opencode.exe加一个信任白名单,问题才真正解决。
另外,如果你看到的是"opencode : 无法加载文件,因为在此系统上禁止运行脚本",那是PowerShell执行策略在拦你,用下面的命令放开当前用户:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个错误跟opencode本身无关,是PowerShell的安全策略。执行完这行再试,基本就能跑起来。我在排查时还发现一个很隐蔽的情况:如果之前装过老版本的opencode,旧安装路径里的残留文件会干扰新版本的运行,表现为版本号错乱或者直接崩溃。遇到这种情况就把旧的opencode文件连同配置目录里的残留全删干净,重新装一遍。
8.2 error: unexpected server error. check server lo...
热词里那条"c:\windows\system32>opencode error: unexpected server error. check server lo"的报错,我在Mac上也遇到过,提示信息后半段通常被终端宽度截断,完整写出来类似于"unexpected server error. check server logs for more details"。根据我的排查经验,这个报错九成以上发生在两个地方:一是模型服务商API出问题,二是网络不通。
排查链路建议按这个顺序走:
- 检查API Key是否有效:去对应服务商的Dashboard看余额和使用量,很多报错其实是Key过期或者余额扣光了。
- 检查能否直连服务商API:用curl直接请求一下模型服务商的API接口,看返回是否正常。
- 查看opencode日志:
opencode通常在~/.local/share/opencode/log/或系统的日志目录写执行日志,打开最后几十行看具体的HTTP错误码。 - 切换模型再试:如果换一个模型马上能用,说明问题出在那个模型或服务商的接口上,而不是opencode本身。
- 升级opencode版本:这个问题在旧版本上出现过,更新到最新版之后基本就消失了。
如果你使用的是本地Ollama模型,遇到"unexpected server error"就要先确认Ollama的ollama serve是不是还活着。有一次我电脑休眠再唤醒后,Ollama的进程挂掉了,opencode这边就报这个错,重启Ollama服务马上恢复。
8.3 一个容易被忽略的配置坑:JSON格式的心情
opencode的很多诡异报错都跟配置文件里的JSON格式有关。多一个逗号、少一个引号、注释格式不对(它默认不认//注释),都会导致启动时读取配置失败,但错误提示往往不是"JSON格式错误",而是千奇百怪的后续症状。
我的经验是,改完配置文件之后,先用python -m json.tool opencode.json或者VS Code打开看一眼有没有格式校验报错,再启动opencode。不要直接在配置目录下对着一个纯文本文件硬改,那个出错率太高了。
最后再分享一个我日常用opencode的小习惯:我会在配置里固定放一个"代码审查"的Skill,提交PR之前先在本地让opencode过一遍我的diff,很多低级的命名问题、遗漏的错误处理、能提前发现的安全隐患,它一眼就能扫出来。如果你刚开始接触opencode,不用急着把一堆Skill和插件全装上,先把模型配好、跑通一次普普通通的Agent任务,然后去翻一翻社区里的Skill库,看看有没有现成的、适合你当前工作流的技能包。等什么时候你开始觉得"它在一些重复性环节上比我手动做更靠谱"了,你才算是真正入了这个工具的门。