过去几个月我把日常的主力 AI 编程工具从 IDE 插件换成了终端里的 opencode。试过 Claude Code、Codex CLI还有几个刚出的 agent最后留在终端里天天在用的就是它。这篇东西不是官方文档的翻译是我从安装、配置、接模型到真实项目里跑了好几个星期的实战记录包括踩过的坑和怎么绕开这些坑。opencode 是 SST 团队开源的一款终端 AI 编程助手你可以把它理解成一个跑在命令行里的 AI 工程师它能读你的项目、改代码、执行命令、跑测试、提交 git也能通过 MCP 去操作浏览器这类外部工具。它跟同类工具最大的不同有两点。第一模型无关Anthropic、OpenAI、Google、OpenRouter、Ollama 本地模型都能接不会被绑定在某一家厂商。第二交互不是一问一答的聊天框而是一整套 TUIagent 每一步在想什么、改了哪些文件、执行了什么命令全部实时可见。对需要在真实项目里调试复杂问题的人来说这种可见性太重要了——你永远知道它在干嘛而不是干等一个闪烁的光标。如果你正在纠结要不要入手 opencode或者已经装上了但只会最基础的操作这篇文章会从安装讲起一路讲到模型配置、Skills、Memory、MCP、编辑器插件、桌面端以及和 Codex、Claude Code 的选型对比。新手可以按顺序跟着做已经用起来的人可以直接跳到最后看踩坑部分。1. opencode 到底是什么它解决的并不只是“换个终端工具”的问题1.1 终端 AI 助手为什么会在这一年集中爆发2024 年下半年开始AI 编程的主战场从 IDE 插件慢慢转移到了终端 Agent。IDE 插件像 Copilot 那种本质是人在写AI 补全上下文基本局限在当前文件。但真实项目里的 bug 往往跨模块、跨服务一个报错要追到好几个文件之外甚至要跑命令才能复现。终端 Agent 的优势就在这里它拿到的是整个项目的上下文能读文件、能执行命令、能看测试结果还能自己改完代码再跑一遍验证。于是 Claude Code 出来了Codex CLI 也出来了opencode 也是这个赛道的产品。它们的共同点是给你一个命令行入口你用自然语言描述目标它自己规划步骤、改代码、跑命令、看结果循环直到搞定。1.2 opencode 的核心定位模型无锁定 TUI 优先opencode 跟 Claude Code 最大的区别是它不站队。Claude Code 官方版对 Anthropic 系的模型支持最好Codex CLI 天然偏向 OpenAI而 opencode 从设计上就是模型无关的。你可以今天用 Claude 写代码明天切到 Gemini后天试试本地 Ollama一套配置就能换。这不只是多一个选择的问题而是让你在模型评测、成本控制、团队统一工具链这些事情上有了主动权。另一个特色是 TUI。opencode 不是简单的命令行一问一答它跑起来是一个完整的终端交互界面左边是会话列表中间是对话和文件 diff底部是输入框顶部能看到当前模型和 agent 模式。这个设计在真实项目里非常舒服因为 AI agent 干活不是一句话就结束的它要改好几个文件、跑几次命令TUI 能让你像盯 IDE 一样盯住整个过程每一步都透明。1.3 一次真实的启动过程在项目目录下直接输入opencode几秒内就能起来。第一眼看到的是最近会话列表新建会话后底部输入框会提示当前模型。按/打开命令面板里面有/models、/agents、/mcp、/login、/skills这些常用命令。输入框里可以直接描述任务比如看一下这个仓库的 README告诉我整体架构和核心模块它就会进入工作状态。/agents可以切换 agent 模式常用的有 build、plan、ask 三种。plan 模式只做分析和规划不改代码build 模式会实际动手改ask 模式就是纯问答。这个划分非常重要后面实战部分我会细讲什么时候该用哪种。2. 安装 opencode从零到第一行命令跑通2.1 三条安装路径怎么选opencode 的安装方式主要有三种我挨个用过说下区别。# 官方脚本安装适合 Linux 和 macOS curl -fsSL https://opencode.ai/install | bash # npm 全局安装适合已有 Node.js 环境的开发者 npm install -g opencode-ai # Homebrew 安装macOS 用户最省心 brew install sst/tap/opencode我的建议是macOS 用户直接用 brew升级方便卸载也干净Linux 用户用官方脚本Windows 用户优先用 npm。npm 方式有个前提是 Node.js 版本要够新太老的版本装完可能报依赖问题。装完先验证一下opencode --version能打印出版本号就说明安装成功。另外 opencode 现在迭代非常快基本一两周就有一个新版本新功能经常只在最新版里才有所以我有事没事就会看一眼版本号。2.2 Windows 报错“无法将 opencode 项识别为 cmdlet”的根因与修复这个报错在 Windows 上太常见了热搜里也反复出现opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称...先说结论99% 的情况是因为 npm 的全局 bin 目录不在系统 PATH 里。npm 安装全局包后可执行文件放在一个单独的目录里这个目录如果没加到系统环境变量PowerShell 就找不到opencode命令。排查过程很简单。先看 npm 的全局 bin 目录在哪npm prefix -g输出类似C:\Users\你的用户名\AppData\Roaming\npm。然后手动把这个目录加到系统环境变量 PATH 里。操作路径是设置 - 系统 - 关于 - 高级系统设置 - 环境变量 - 双击 Path - 新建 - 粘贴上面那个路径 - 确定。改完之后务必重新打开一个终端窗口再试PowerShell 不会自动刷新 PATH。还有一种情况是 npm 装的时候报了权限错误这时候检查一下是不是用了管理员权限或者装到了奇怪的位置。用where.exe opencode可以看到它实际被安装到了哪个路径如果完全没输出基本就是没装上或者 PATH 没生效。2.3 升级与卸载别忽略这个命令opencode 的升级有两种方式。如果你是 brew 安装的brew upgrade opencode就行npm 装的重新执行npm install -g opencode-ailatest。新版其实内置了自升级命令我记不清具体版本号之后开始有的如果你在命令行里输入opencode upgrade新版会自己拉最新版本。这个命令在官方文档里有写如果你的版本比较老不支持就手动重新装一次。卸载倒是很简单brew 用brew uninstall opencodenpm 用npm uninstall -g opencode-ai。不过要注意卸载命令行工具不会删除配置文件全局配置在~/.config/opencode/目录下项目配置在项目里的.opencode/目录下想彻底清干净得手动删。3. 模型配置把 opencode 接到你想要的任何模型上3.1 内置 Provider 与首次登录启动 opencode 后第一次用需要先登录模型服务商。输入/login会列出支持的 provider包括 Anthropic、OpenAI、Google Gemini、OpenRouter、Ollama、Mistral 等。选择之后有的走浏览器 OAuth 登录有的直接用 API Key。如果你不想走交互式登录也可以直接设置环境变量比如ANTHROPIC_API_KEY或OPENAI_API_KEYopencode 启动时会自动读取。我个人更喜欢环境变量的方式因为这样 API Key 不会写进任何配置文件安全性好一些而且团队协作时每个人用自己的 key 也方便。3.2 用配置文件锁定默认模型和 Agent每次启动都手动切模型太麻烦所以要把默认配置写下来。opencode 的全局配置文件在~/.config/opencode/opencode.json项目级配置可以放在项目根目录下的opencode.json里项目级会覆盖全局级。我的一份典型配置长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, theme: opencode, provider: { openrouter: { options: { api_key: 你的OpenRouter Key } } } }注意$schema字段加上之后在 VSCode 里编辑配置会有自动补全和字段校验能帮你少踩很多拼写错误的坑。model字段的格式是服务商/模型名比如openai/gpt-4o、google/gemini-2.5-pro、openrouter/anthropic/claude-sonnet-4。这个格式很直观一看就知道当前用的是谁的什么模型。3.3 免费模型与社区中转渠道的取舍聊到免费模型先说结论社区里经常流传一些中转渠道比如以前有人提到的 hy3-free 之类的免费模型入口这类渠道最大的问题是稳定性没有保障今天能用明天可能就下线了。我自己见过好几个项目一开始图省事接了免费中转结果开发到一半渠道挂了agent 整个不可用反而浪费时间。所以免费渠道可以拿来尝鲜、跑测试但别作为日常主力。真正靠谱的免费方案有两个。一个是 OpenRouter 上标记为:free的模型虽然每天有请求限制但质量比很多杂牌中转稳定适合验证 opencode 本身的功能。另一个是本地 Ollama把模型拉下来之后完全本地推理没有网络依赖也不花钱。ollama pull qwen2.5-coder:14b然后在 opencode 里/login选择 Ollama或者直接配置{ model: ollama/qwen2.5-coder:14b }本地模型的好处是不用担心 API 费用和数据隐私缺点是模型能力跟云端顶级模型比还是有差距复杂任务容易卡壳。我的建议是日常重活用云端的 Claude 或 GPT 系列零成本的轻量任务用本地小模型两边互补。3.4 多 Provider 自由切换的日常配置好了多个 provider 之后平时用的时候用/models就能呼出模型列表上下选择直接切换。切换是即时的不需要重启agent 下一次对话就会用新模型。我现在的习惯是项目里写业务逻辑用 Claude 系列因为代码理解和多步推理确实强做总结、起名、写注释这类杂活用 Gemini便宜还快本地 Ollama 用来处理不方便出内网的代码片段。多模型切换这个能力是我离不开 opencode 的主要原因之一。4. 实战让 opencode 真正上手干活的三种姿势4.1 接手陌生项目先读懂再动手接手别人的代码永远是最头疼的事。我现在的做法是进入项目目录打开 opencode先切到 ask 模式问它这个项目的技术栈是什么目录结构怎么组织的核心业务模块有哪些数据流是怎样的opencode 会自己读 README、package.json、源码、配置文件然后给你一份相对完整的架构说明。这一步能省掉我大量肉眼翻代码的时间。更进一步的用法是让它生成一份项目架构文档把上面的分析整理成一份 Markdown 文档写到 docs/architecture.md包含模块划分、依赖关系、核心流程、关键入口文件。它会真的创建文件并写内容。拿到这份文档后再去改代码心里就有底了。注意这里我先用 ask 模式再切到 build 模式让它写文件分步走比一口气下命令要稳得多。用 opencode 接手陌生项目还有一个隐藏优势它在分析过程中会把读过的关键文件记录到上下文里后面你再问刚才提到的那个工具函数在哪它能直接指出来不用你重新描述。这种连续记忆能力在探索代码库时特别有价值。4.2 修复前端 Bug借助 Playwright 让 agent 拥有“眼睛”有一个场景让我对 opencode 的印象彻底改观修前端 bug。以前遇到那种只在这个页面出现、报错信息很隐晦、需要手动操作浏览器才能复现的 bug基本靠肉眼定位非常费时间。后来我给它配上 Playwright MCP server让 agent 能直接控制浏览器。opencode 支持 MCPModel Context Protocol可以理解为给它接外部工具的标准化接口。配 Playwright 的方法是在配置里加 mcp 字段{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest] } } }配置好之后再描述 bug 就完全是另一种体验了。比如登录页面点击提交按钮后控制台报 TypeError: cant read properties of undefined。请用 Playwright 打开本地开发服务器复现这个问题定位到具体代码位置并修复。接下来 opencode 会自己启动浏览器、访问页面、模拟点击、抓取控制台报错然后根据报错去代码里找问题改完再跑一遍验证。整个过程我只需要在旁边看着。这种能动手操作浏览器的能力让 opencode 处理前端问题的深度远超只能读代码的普通 agent。这里有个小技巧配置 MCP server 之前要确保本地的 Node.js 环境能正常运行 npx不然 agent 调不起浏览器。另外第一次启动 Playwright 会下载浏览器内核需要一点时间别以为卡死了。4.3 从零实现一个功能Plan 模式先行Build 模式动手日常开发中我收到一个新需求不会直接让 build 模式开干。真实项目的复杂度不在一段代码而在牵一发而动全身。我的流程是分两步。第一步用 plan 模式我要给用户模块新增一个导出功能支持导出 CSV 和 Excel 两种格式。先把实现方案列出来包括需要改哪些文件、接口怎么设计、后端用什么库、前端怎么触发下载还要考虑数据量大时的分页导出。plan 模式会先分析项目现有代码风格然后产出一份方案不碰任何文件。我会看一遍方案有不对的地方直接跟它讨论调整。方案确认了再切到 build 模式按刚才确认的方案实现注意保持现有代码风格完成后运行相关测试。这个时候它才会改代码并且会自己跑 lint、跑单测如果测试挂了会继续修。整个过程你要做的就是 review 它的 diff。这里最重要的经验是plan 和 build 两个模式的分工不是花架子而是防止 agent 跑偏的保险。跳过 plan 直接 build 也不是不行但十次里有三次会改出你不想看到的东西。5. Skills 与 Memory把私有经验沉淀给 opencode5.1 Skills 机制为什么说它是 opencode 的杀手级功能Skills 是 opencode 一个很核心的扩展机制类似 Claude Code 里的 skills。简单说你可以把一类工作的标准流程、注意事项、代码规范写成一个技能包放在指定目录里之后 opencode 在遇到对应场景时会自动加载并遵循这个技能包。技能包的目录结构是这样.opencode/skills/ code-review/ SKILL.md frontend-test/ SKILL.md每个 skill 是一个文件夹里面有一个SKILL.md文件用 Markdown 编写文件头部是 YAML frontmatter标注技能的名字和描述--- name: code-review description: 当需要审查代码质量、发现潜在 bug、检查命名规范时使用。重点检查空指针、资源泄漏、并发安全和异常处理。 --- # 代码审查规范 ## 审查步骤 1. 先阅读 diff理解改动意图 2. 检查边界条件和异常分支 3. ...关键在description字段它要写清楚这个技能在什么场景下被触发。opencode 会根据任务内容判断该不该加载哪个 skill。如果 description 写得太笼统就会出现技能文件存在但 agent 一直没用的尴尬情况。5.2 接入 superpowers直接白嫖一整套编码技能superpowers 是社区里一个挺有名的技能包合集项目作者把很多软件工程实践整理成了结构化技能比如先写测试再写实现、如何拆解大任务、如何做代码重构这些。原本是给 Claude Code 用的后来 opencode 的 skills 机制兼容了同样的格式所以可以直接复用。安装方式很简单把项目 clone 到 opencode 的全局 skills 目录git clone https://github.com/obra/superpowers ~/.config/opencode/skills/superpowers装好之后再让 opencode 实现复杂功能时它可能会自动按照 superpowers 里的流程来做比如先写测试、再实现、再重构。这个项目里的技能很多不是所有都适合你的场景我建议用的时候在对话里明确一句按照 superpowers 的 TDD 技能来执行比让它自动判断要准。5.3 Memory 用法让 opencode 记住项目的坑Memory 是另一个容易被忽略但实际价值很高的功能。它的作用是跨会话保存一些项目层面的结论。比如你花了一下午让 opencode 搞清楚这个项目的测试命令是npm run test:unit集成测试需要先启动 mock server如果不写进 Memory下次新会话它又得重新摸索一遍。平时我怎么用呢就是在对话里直接说记住这个项目的数据库迁移工具是 Prisma不要直接改数据库表结构所有变更写 migration。或者记住部署前必须执行npm run build并且保证构建产物在 dist 目录。opencode 会把这个信息写进 Memory。下次新开一个会话再聊到这个项目时它就自带了这些上下文。这相当于给 AI agent 建了一本项目的坑位笔记随着使用时间越长它对项目越懂。6. 编辑器与桌面端VSCode、IDEA 插件和 Desktop 体验6.1 VSCode 插件终端和 IDE 之间的桥opencode 的 VSCode 插件本质上是一个远程控制面板。在扩展市场搜 OpenCode 安装之后它可以识别你当前打开的项目并在侧边栏显示 opencode 会话。最大的价值在于你可以在编辑器里选中一段代码右键发送给 opencode它会带着这段代码和当前文件路径作为上下文。这个能力在调试时很实用。比如你看到一段可疑代码选中它右键选择解释或优化不用把代码复制粘贴到终端里再解释上下文。插件和终端会话是打通的你用插件发送的内容在终端里也能看到完整的上下文链。6.2 JetBrains IDEA 插件Java/Maven 项目配置要点IDEA 插件和 VSCode 插件思路类似但 Java 项目有一些特有的坑。最大的问题是环境变量。opencode 在 IDEA 自带的终端里启动时继承的是 IDEA 的 PATH 和 JDK 配置而不是系统默认的。如果你的 Maven、Java 配置只在 IDEA 里设置过终端里直接跑 mvn 可能会找不到命令。所以用 IDEA 插件前先确认一点在 IDEA Terminal 里你能手动敲通mvn -v再谈让 agent 帮你处理依赖问题。另外 Java 项目里 opencode 经常要读pom.xml来理解依赖如果项目比较大第一次分析会慢一些这个正常。6.3 opencode DesktopTUI 的桌面包到底值不值得用opencode 官方出了桌面版本质上是把 TUI 装进一个独立窗口附带了一些窗口管理能力比如多标签、独立字体设置、更友好的滚动条。我用过一段时间感受是如果你每天都在终端里工作桌面版的意义不大TUI 已经足够好但如果你用的是 Windows 默认的糟糕终端或者单纯不喜欢命令行界面桌面版会有更好的视觉体验和滚动体验。桌面版的资源占用比终端版略高胜在渲染更稳定。另外桌面版的更新节奏比 CLI 慢半拍有些新功能 CLI 先上桌面版要等几天。我的建议是主力还是用终端版桌面版当备用不要两个都开着容易有配置写冲突。7. 和 Codex、Claude Code、Pi 这些 agent 怎么选7.1 横向对比这个赛道的工具我基本上都试过一轮简单说说它们之间的差异。维度opencodeClaude CodeCodex CLIPi模型支持开放多厂商官方偏向 Anthropic偏向 OpenAI取决于实现是否开源开源部分开放开源不完全开源交互界面TUI信息密度高命令行为主命令行为主简洁 CLISkills/插件Skills MCP生态活跃Skills MCPMCP 支持扩展较少上手成本中功能多需要熟悉低开箱即用中低适合场景多功能、多模型团队Anthropic 生态用户OpenAI 生态用户轻量辅助Claude Code 的优势是跟 Claude 模型深度绑定很多 Anthropic 系特有的能力比如长上下文、工具调用优化在它上面表现最好。如果你整个团队都在用 Claude选它没毛病。Codex CLI 同理对 OpenAI 系模型支持最好跟 ChatGPT 账号联动也方便适合重度 OpenAI 用户。opencode 的优势在灵活性和开放性。它不绑定模型支持 Skills 自定义MCP 生态也兼容意味着你可以把整个工作流沉淀到 opencode 里换模型的时候不用换工具。这是我在团队里选它做主力的核心原因。至于 Pi 这类新工具我的评价是功能上还没有形成明显壁垒目前更适合作为备选观察。工具选型这件事不用太早下结论这个赛道更新太快半年可能就洗一轮牌。7.2 我的选择建议如果你让我给一个简单粗暴的结论我会说只用 Anthropic 模型、追求开箱即用选 Claude Code。重度 OpenAI 用户选 Codex CLI。想要模型自由、要 Skills 扩展能力、打算长期沉淀自己的 AI 工作流选 opencode。但这里有个很重要的点这些工具不是互斥的。我自己就是 opencode 为主偶尔切出来用 Claude Code 对比一下同一个任务的表现。agent 工具的核心价值是帮我们干活谁在具体项目里表现好就用谁没必要有工具洁癖。8. 踩坑记录我实际遇到过的问题与完整排查过程8.1 启动报错 unexpected server error先看日志再下结论有段时间在 Windows 上启动 opencode直接弹出一条错误opencode error: unexpected server error. check server logs这种提示特别让人抓狂因为根本没告诉你哪里错了。我的排查过程是这样的先看日志。opencode 的日志文件在~/.local/share/opencode/log/或者 Mac 上的~/Library/Logs/opencode/找到最近的那个日志文件打开看 stacktrace。那次的情况是 log 里出现了某个 provider 的 401 认证失败原因是 API Key 过期了。处理办法很简单重新登录或者更新 key。但如果你不看日志永远只能瞎猜是安装问题还是网络问题。所以记住opencode 报错第一件事看日志错误信息本身经常是废话。8.2 opencode go 版本和 npm 装出来的版本混用opencode 底层后来用 Go 重写了核心部分社区里管这个叫 opencode go我自己也踩过坑。现象是之前用 npm 装了一个版本某天看到新版本发布用go install又装了一次然后两个版本同时存在which opencode指向的路径不一样行为也不一样一度让我以为配置坏了。这个问题的本质是安装方式不统一。Go 版本装出来的二进制在$(go env GOPATH)/bin下npm 装的在全局 node_modules 下。排查方法很简单which opencode看看实际执行的是哪个然后统一用官方推荐的方式重新装一次。我个人现在统一用官方脚本安装避免多版本混在一起的混乱。8.3 ccswitch 切换配置后 opencode 不生效ccswitch 是个切换 AI 配置的小工具原本是给 Claude Code 用的后来也支持 opencode。有网友问过为什么 ccswitch 切换之后 opencode 好像没反应。这个我遇到过原因通常是opencode 已经在运行它启动时读取了旧的配置文件ccswitch 在外部改了文件但 running 中的进程不会自动重载。解决办法切换配置后彻底退出 opencode不是关掉会话是进程完全退出再重新启动。另外要分清 ccswitch 改的是全局配置还是项目配置如果你的项目根目录有opencode.json它的优先级比全局配置高ccswitch 只改了全局配置的情况下项目内打开 opencode 自然还是旧配置。8.4 Skills 文件存在但 agent 始终不加载这是我第一次配 Skills 时遇到的问题。照猫画虎建了.opencode/skills/目录放好了SKILL.md但让 agent 按技能执行时它完全无视。排查之后发现是我的description写得太泛了比如写着当需要写代码时使用这种描述对 agent 来说没有触发约束力几乎每次写代码都会被当成候选项反而不容易被选择。正确做法是把触发条件写具体比如当用户提到需要为 API 接口补充集成测试时使用重点覆盖鉴权和参数校验。另外还要检查文件名和目录名是否匹配有些版本对 skill 文件夹的命名有要求大小写不对也会被忽略。调试时用/skills命令可以列出当前已经加载了哪些技能。8.5 TUI 卡死后的自救方法用终端工具最怕的就是界面卡住。opencode 的 TUI 在长时间运行、或者终端窗口尺寸突然变化的时候偶尔会出现渲染错乱甚至卡死。我的处理经验是先按CtrlC中断当前任务看会不会回到输入框如果界面还是花的按CtrlL或者输入reset重置终端实在不行就结束进程重新启动。会话记录一般不会丢重开之后能在会话列表里找到历史记录。预防方面我现在的做法是重要任务在 tmux 里跑 opencode窗口大小变化不会影响渲染而且意外断连后还能恢复会话这对长任务来说几乎是必须的。最后分享一个让我非常受益的小习惯每次打开 opencode 做一件事之前我会花三十秒把目标写清楚——背景是什么、约束是什么、验收标准是什么。实践下来给 agent 的任务描述越具体它的完成质量越高。这个道理跟带新人一模一样需求说不清楚写代码的自然只能靠猜。opencode 再聪明也只是把你的意图听得更准而已。所以与其到处问哪个 agent 好用不如先把自己的工作流程梳理好再把 opencode 接进去这套组合拳下来的实际提升远比换个工具大得多。