如果你最近在折腾终端里的 AI 编程助手大概会频繁看到一个名字opencode。我是在 Claude Code 和 Codex CLI 之间来回切换时被迫注意到它的——每个工具绑定一家模型厂商换一种模型就要换一套操作方式不同项目之间还不能共享一套工作流实在太折腾。opencode 是一个开源的、跑在终端里的 AI Agent你可以把它理解成“统一入口版”的 Codex CLI它不绑定某一家模型Anthropic、OpenAI、Gemini、DeepSeek、Ollama 本地模型全都能接而且把 Skills、MCP、Docker 沙箱、LSP 诊断这些能力都塞进了同一条会话流。这篇文章是我从零上手到日常使用的一个完整记录包括安装、配置、接免费模型、玩转 Skills、配合 IDE 插件还有我实际踩过的一些坑。1. opencode 到底是什么一个不绑定模型商的终端 Agent1.1 为什么已经有了 Claude Code 和 Codex CLI还需要 opencode先说说我的使用背景。Claude Code 在代码理解、长上下文和自动修改文件上确实强但它主要绑定 Anthropic 的模型Codex CLI 更适合 OpenAI 那套生态而且整体交互更“命令行工具”而不是“会话式队友”。问题是我手头有多个项目的 API 额度团队里有人用 DeepSeek有人用 Gemini还有人需要跑本地 Ollama 模型。如果每个模型都配一个专用 CLI那我要记住 N 套快捷键、N 套配置格式还要在不同项目间来回切换成本太高。opencode 的出现恰好解决这个痛点。它做了一层模型 Provider 抽象意思是你只需要配置好每个模型的 API Key 和模型名然后在同一套终端会话里用/models就可以快速切换。比如我上午用 Claude 写架构设计文档下午切到本地 Qwen 处理一些不敏感的内部数据晚上再用 DeepSeek 跑一下代码审查全程不需要离开同一个 opencode 会话。这个“统一入口”的设计才是它真正和别的终端 Agent 拉开差距的地方。另外opencode 是开源项目来自 SST 团队。这个团队以前主要做 Serverless 开发工具他们开发 opencode 时延续了“开发者工具应该可配置、可扩展”的思路。所以你能在它的配置里看到大量细粒度选项权限控制、沙箱、LSP、模型路由、自定义指令这些东西对个人开发者是加分项对团队统一管理更是刚需。1.2 核心能力拆解会话、Skills、MCP 与沙箱我第一次用 opencode 时最先注意到的并不是它有多智能而是它的核心能力设计非常“为干活而生”。我整理了一份清单这些能力基本决定了一个终端 Agent 的实用性上限会话式 TUI使用起来和 Claude Code 很像但更轻启动速度快窗口布局适合长时间阅读代码上下文。多 Provider 支持Anthropic、OpenAI、Azure OpenAI、Google Gemini、Mistral、DeepSeek、Groq、Ollama、LM Studio 等都能接入。免费模型也可以接只是有速率限制。Skills把常见操作流程写成 Markdown 指令让模型按照步骤执行适合沉淀团队规范或复杂操作。MCP 支持可以接入本地文件、数据库、浏览器、Playwright 等外部工具相当于给模型加“手脚”。Docker 沙箱让 AI 执行命令时跑在容器里不会直接污染宿主机这个对不安全代码尤其重要。LSP 诊断读取 IDE 或语言服务端提供的诊断信息让 AI 在动手前先知道哪里有语法错误和类型问题。Git 集成自动生成 commit message、回溯 diff甚至可以让 AI 按你的提交规范来提交代码。项目记忆通过项目根目录的说明文件自动加载约定让 AI 在每次会话里都记得测试命令和编码规范。这些能力单独拎出来别的工具多多少少也有但能像 opencode 这样默认放进一个 TUI 会话里的不多。尤其 Skills 和 MCP 配合起来基本可以做到“给 AI 一个任务它自己调用工具去复现、排查、修复、验证”。1.3 opencode、Codex CLI、Claude Code 与 Pi 怎么选最近总有人问我“opencode、Codex CLI、Claude Code、Pi 到底选哪个”。我自己的判断标准是看你的模型使用习惯和场景复杂度。工具定位模型绑定强项适合人群opencode开源终端 Agent通用模型入口不绑定多模型均可Skills、MCP、沙箱可定制性强多模型用户、团队需要统一工作流Claude CodeAnthropic 官方终端 Agent绑定 Anthropic 模型代码理解和长上下文好开箱即用深度使用 Claude 生态的开发者Codex CLIOpenAI 官方终端 Agent绑定 OpenAI 模型与 OpenAI 生态、GitHub 流程结合紧密日常主力是 GPT 系列模型的开发者Pi轻量级 AI 编程助手视具体指代通常绑定单一模型简单、快速、适合小任务不想折腾配置、只需辅助问答的用户我现在的日常是opencode 为主Claude Code 偶尔做深度重构。原因是 opencode 的 Skills 和 MCP 可以让团队把“提交规范”“测试流程”“Bug 复现步骤”沉淀成可复用资产而 Claude Code 更适合让我直接对话式地处理一次大的代码迁移。如果你大部分时间只用一个厂商的模型那直接用官方 CLI 更省心如果你像我一样需要在多个模型之间横跳opencode 的性价比就体现出来了。2. 安装与初始化从零到跑通第一个会话2.1 环境准备Node.js、系统要求与终端选择opencode 是基于 Node.js 开发的所以最先要确认的就是 Node 版本。我建议安装 Node.js 20 或更高版本太老的版本会遇到依赖安装失败或运行时崩溃。你可以先用node -v看一眼低于 20 就直接去官网下载 LTS 版本或者用 nvm 管理多版本。在 Windows 上我推荐优先用 Git Bash 或者 WSL 来跑 opencode。不是不能用自带的 PowerShell 或 cmd而是终端渲染和路径解析在 Windows 原生终端下偶尔会有小问题尤其在处理项目内符号链接和复杂参数时。如果你只有 Windows 原生环境也完全可以跑我在常见问题里会专门讲 Windows 上的坑。2.2 三种安装方式npm、脚本与桌面版opencode 的安装方式很主流我列三个我验证过的# 方式一npm 全局安装最推荐 npm install -g opencode-ai # 方式二官方安装脚本Linux/macOS curl -fsSL https://opencode.ai/install | bash # 方式三HomebrewmacOS brew install sst/tap/opencode安装完成之后终端里执行opencode --version能输出版本号就说明成功了。如果提示找不到命令大概率是 npm 全局目录没进 PATH后面常见问题里有详细解法。另外 opencode 也有桌面版。经常有人问“opencode 桌面版怎么用”其实桌面版本质上是把 TUI 聊天界面封装成一个桌面应用适合不想一直开终端的人。我会建议核心操作还是放终端里桌面版更适合你偶尔打开看看 Agent 跑任务的状态。2.3 配置 ProviderAPI Key 与环境变量opencode 支持两种主流配置方式环境变量和配置文件。我的建议是“环境变量存 Key配置文件存偏好”。先登录服务商运行opencode auth login它会让你选择 ProviderAnthropic、OpenAI、Google、DeepSeek、Ollama 等然后按提示填入 API Key。如果你不想用交互式登录也可以直接设置环境变量export ANTHROPIC_API_KEYsk-xxxx export OPENAI_API_KEYsk-xxxx export DEEPSEEK_API_KEYsk-xxxx然后写一个opencode.json放到项目根目录或者全局配置目录。我的全局配置在~/.config/opencode/opencode.json内容大致长这样{ $schema: https://opencode.ai/config.json, provider: { default: anthropic, anthropic: { api_key: env:ANTHROPIC_API_KEY, model: claude-sonnet-4-5 }, deepseek: { api_key: env:DEEPSEEK_API_KEY, model: deepseek-chat }, google: { api_key: env:GOOGLE_API_KEY, model: gemini-2.5-pro } } }注意这里default字段设的是默认 Provider不用每次会话都手动切。配置文件采用“项目配置覆盖全局配置环境变量覆盖配置文件”的优先级这个心里有数就好。2.4 不想花钱怎么办接入 Ollama 和免费模型很多初学者最关心的是“opencode 免费模型怎么接”。我的回答是优先接本地 Ollama其次接各家的免费额度或限免模型。Ollama 接入非常简单。首先本地安装 Ollama然后拉一个代码模型ollama pull qwen2.5-coder:14b接着在 opencode 配置里增加一个 Ollama Provider{ provider: { ollama: { type: ollama, api_base: http://localhost:11434, model: qwen2.5-coder:14b } } }这样你就能在 opencode 里切换到本地模型了。好处很明显不需要联网、没有 API 费用、数据不会出本机。但也要有心理准备14B 量级的本地模型在复杂代码推理上明显弱于 Claude 或 GPT 的旗舰模型适合处理重复性代码生成和简单修复。如果想效果好一点可以拉更大的量化模型但要确保内存足够。至于“免费模型”opencode 的 Provider 列表里能看到一部分支持限免额度的服务商。我的建议是免费模型拿来学习、测试、跑一些不太要紧的脚本可以但别在生产环境里依赖它。因为限免通常伴随速率限制你在跑批量代码审查或大文件重构时很容易被断流或者报错。3. 实战用 opencode 接手旧项目、修 Bug 和加功能3.1 第一次启动TUI 界面怎么操作配置好之后直接在项目根目录运行opencode你会进入一个类似 Claude Code 的终端界面。最下面一行是输入框直接输入自然语言即可。第一次使用建议先敲/help看一下当前版本的命令列表。不同版本命令略有差异但基本都会包含下面这些/models切换模型。/init根据项目自动生成规则文件。/sessions查看历史会话继续之前的对话。/undo撤销 AI 最近一次文件修改。文件名把指定文件内容加入上下文。!开头执行 Shell 命令比如!git status。这里要特别注意AI 在执行有副作用的操作前通常会在界面里请求权限。你会看到类似Y允许一次、A全部允许、E允许并编辑之类的按键操作。建议第一次跑不熟悉的任务时先不要按A而是逐个确认避免它一口气改掉你十几个文件。3.2 接手一个旧项目的标准流程我接手一个旧项目时最怕两种情况AI 看不懂项目结构乱改AI 在不知道测试命令的情况下“自作聪明”地跑了一堆无用操作。opencode 对这个问题有比较成熟的解法。我的标准流程是在项目根目录运行opencode先不急着给任务而是让它解读项目结构先看一下项目的 README、package.json或 pom.xml / go.mod然后告诉我 这个项目是干什么的 启动命令是什么 测试命令是什么 有哪些我需要注意的目录约定然后用/init让 opencode 生成项目规则文件。它会扫描项目代码总结出编码风格、目录约定、测试方式写入一个规则文件。之后每次会话都会自动加载这份规则。再问它最近一次 Git 提交改了什么确认上下文!git log --oneline -5最后才说具体任务比如修复某个模块、增加某个接口。这个流程看起来多花了几分钟但能显著减少 AI 瞎猜的次数。我实测下来跳过第二步直接给任务的话AI 经常会在测试命令和构建工具上犯低级错误走完流程之后它至少能“按项目自己的规矩”来干活。3.3 用 Playwright 让 Agent 自己复现前端 Bug前端 Bug 最让人头疼的地方在于“你得先把问题复现出来才能改”。opencode 接了 Playwright MCP 之后可以让 AI 自己打开浏览器、点击页面、截图、看控制台报错然后定位问题。先配置 Playwright MCP。在 opencode 的配置文件里增加{ mcp: { playwright: { type: npm, command: npx, args: [playwright/mcplatest] } } }然后在会话里给它一个带“前提”的任务项目已经在本地跑起来了地址是 http://localhost:5173。 请用 Playwright 打开这个页面尝试复现用户反馈的“点击提交按钮后没有任何响应”的问题。 复现过程中需要 1. 打开浏览器并访问页面 2. 填写表单 3. 点击提交按钮 4. 截图并查看控制台是否有报错。 最后告诉我根因以及你建议的修复位置。我看到它真正打开浏览器去操作时心里还是有点震撼的。最后它发现是表单校验函数抛了一个未捕获异常导致提交事件中断。这种“自动复现、自动定位”的能力用在回归测试和 Bug 排查上非常值。当然Playwright MCP 要正常工作项目本身得能本地启动而且你最好把登录态、Mock 数据准备好了否则 AI 会被登录流程卡住。3.4 Skills 实战把团队代码规范变成可执行步骤opencode 的 Skills 设计我很喜欢。官方解释很简单Skills 就是一组结构化的 Markdown 指令里面写了“什么时候用、怎么用、需要执行哪些步骤”。你可以在项目里建一个.opencode/skills目录里面每个 Skill 就是一个带 frontmatter 的 Markdown 文件。举个例子我团队里经常要加一个新的 API 路由流程很固定我就写了一个 Skill--- name: add-api-route description: 按照团队规范新增一个 API 路由 --- 当用户要求新增 API 路由时严格按下面步骤执行 1. 在 src/routes/ 下创建以新路径命名的文件 2. 从 src/routes/_template.ts 复制模板 3. 在 src/registry.ts 中注册路由 4. 在 tests/api 下添加对应测试测试数据用 fixtures/api.json 5. 运行 npm run test:api 确认全部通过。之后我在会话里说“使用 add-api-route 这个 Skill 加一个获取用户列表的接口”模型就会读取这个 Skill按照里面的步骤执行而不是自由发挥。团队里所有人在同一个项目里都能复用这套规范相当于把“老师傅的操作流程”固化成了 AI 的行为准则。你甚至可以把网上一些现成的 Claude Code Skills 拿过来改一改比如热词里提到的 oh-my-claudecode 这类技能包。只要文件结构符合 SKILL.md 的规范opencode 也能识别和加载。不过要注意版本差异有些技能用到了特定模型才有的能力切换到别的模型时不一定能完整跑通。3.5 Memory 与项目规则让 Agent 记住“潜规则”代码库里的“潜规则”往往不会写进 README比如“这个模块不允许直接操作数据库”“错误码必须用数字开头”“测试环境变量不要写在代码里”。这些其实非常适合放进项目规则文件。opencode 支持通过配置指定随时加载的说明文件。我会在项目根目录放一个AGENTS.md里面写清楚项目启动命令和测试命令目录结构约定常见陷阱和禁止事项代码风格要求。然后在opencode.json里配置{ instructions: [AGENTS.md] }这样每次会话开始模型都会读到这份文件相当于给它一份“员工手册”。我实测下来正确配置规则文件后AI 生成的代码在命名风格、目录放置、错误处理上会更贴合项目明显减少“代码能跑但不符合团队规范”的情况。4. 配置进阶与 IDE 联动4.1 opencode.json 高频配置项解释除了 Provider 和 MCPopencode.json 里还有几个高频配置项我逐个说说我的实际使用经验。{ provider: { default: anthropic }, permission: { edit: allow, bash: ask }, autoupdate: true, theme: dark, instructions: [AGENTS.md], mcp: {} }permission控制 AI 的行为权限。我一般把文件编辑设为allow把 Shell 命令执行设为ask这样它改文件不用每步都烦我但执行危险命令时仍然要确认一下。等充分信任某个项目后再把bash设为allow也不迟。autoupdate控制是否自动更新。我建议开发环境开着但生产环境或长期稳定服务的项目里关掉因为它隔几天就发一个新版本小版本之间配置格式偶尔会变自动更新可能打你一个措手不及。theme只是界面偏好不太影响功能但如果你长时间盯终端选一个舒服的主题比想象中重要。instructions是给模型的项目背景文件前面已经说过强烈推荐。4.2 opencode VS Code / JetBrains 插件有人觉得“终端 Agent 还要 IDE 插件干嘛”我的回答是终端适合批量操作但看 diff、断点调试、上下文高亮还是 IDE 更舒服。opencode 有对应的 VS Code 插件和 JetBrains 插件。在 VS Code 扩展市场里搜 opencode在 JetBrains 插件市场里也能找到。装完之后你可以在 IDE 侧边栏直接打开和终端同步的会话选中代码发送给 Agent也可以直接在插件里看 AI 改动过的文件。我的使用习惯是TUI 跑整体重构和跨文件修改IDE 插件用来做“选中这段代码帮我改”这种局部操作。两个入口共用同一份配置和会话历史至少我在切换时不需要重新交代项目背景。如果你用 VS Code 比较多还有个实用技巧可以配置同一个项目里同时打开 opencode 的“横向终端”和编辑器面板把 TUI 放在下方上面是代码。这样 AI 修改文件的时候你能实时看到 diff比切全屏终端再切回来高效得多。JetBrains 系我没那么重度使用但插件的基础体验是稳的尤其对 Java 项目的 LSP 支持比纯终端场景更好。4.3 配置同步、快捷键和“opencode go”到底指什么我的 opencode 配置会同步到 dotfiles 仓库里这样新机器拉下来执行一个opencode就能进入自己熟悉的工作环境。建议你至少同步这几样东西opencode.json全局配置项目级AGENTS.md如果有.opencode/skills/目录下的 Skills自定义命令脚本如果你用过/command把对应脚本也保存好。很多人在群里问“opencode go 需要配合 cc switch 等工具吗”我理解他们说的“opencode go”其实是指“开始使用 opencode”而不是某个官方子命令。cc switch 是一个用来管理多模型 API Key 的图形化工具可以把配置好的 Key 快速切换它很方便但不是 opencode 的必要依赖。opencode 自己就能通过环境变量或配置文件管理多套 Key我自己就没用 cc switch也跑得很顺。如果你喜欢折腾可以安装一些 Superpowers 之类的技能增强包。它本质上是一堆写好的 Skills导入到 opencode 的 Skills 目录后就能获得像“编写测试”“重构函数”“生成 commit message”这类开箱即用的流程。我个人不太建议第一次就用这种增强包先把原生 Skills 跑明白再按需引入更稳妥。4.4 自定义命令与工作流小技巧opencode 支持自定义斜杠命令具体能不能写脚本视版本而定。我的经验是把高频操作固化成命令能省很多重复沟通。比如我经常要“按团队规范生成 commit message”就在配置里加了一个/commit命令让它自动运行测试、查 diff、按规范生成 message。执行的时候我只需要输入/commit它就会自己跑完测试并生成提交信息我审查之后确认提交。另外还有一个非常实用的小技巧在会话里用!执行 Shell 命令时可以结合引用文件。比如我想知道某个文件的执行情况可以输入!node scripts/build.js这种组合能减少很多“先退出会话再跑命令再回来”的打断感。工作流是否流畅往往就差在这些小细节上。5. 常见问题与排查技巧实录5.1 Windows 下提示“opencode 不是内部或外部命令”怎么办这条是光热搜就出现多次的问题我朋友也踩过。原因很简单npm 全局安装目录没有加入系统 PATH。排查步骤npm config get prefix看到类似C:\Users\你的用户名\AppData\Roaming\npm的路径后把这个目录加入系统环境变量 PATH。加完重新开一个终端再运行opencode --version应该就能解决。如果 PATH 没问题那就是安装没成功。可以卸载重装npm uninstall -g opencode-ai npm install -g opencode-ai还有一种情况是 Node 版本太低。opencode 需要 Node.js 20 以上你用node -v确认一下低了就升级。升级完再装全局包基本就不会再出现“识别不了”的问题。此外如果你用的是 PowerShell可能会遇到执行策略限制报“无法加载文件...因为在此系统上禁止运行脚本”。这时要么用 cmd 运行要么在管理员 PowerShell 里执行一次Set-ExecutionPolicy RemoteSigned -Scope CurrentUser这不是 opencode 独有的问题是 Windows 对脚本执行的保护设置完对日常开发影响不大。5.2 报错“unexpected server error. check server logs”怎么查这个错误是热词里的高频问题我遇到时差点以为是工具坏了。其实绝大多数情况下问题出在 Provider 配置上。先按这个顺序排查看 API Key 是否有效。很多服务商的 Key 有期限过期后会报 server error。看模型名是否写对。比如 Anthropic 的模型名如果写成了旧版本或不存在的新版本服务端会报错。看服务商是否需要额外的 Base URL。接了第三方兼容接口时一定要确认api_base正确。看限流。免费模型经常因为请求太频繁导致服务端拒绝等一会儿再试往往就好了。查看 opencode 的日志。不同版本日志路径不同但一般可以在~/.local/share/opencode/log或~/.cache/opencode/log下面看到。日志里通常会有具体的 HTTP 状态码和错误信息。我建议你把日志打开然后在配置里把 Provider 切换到官方源先试一次。如果换官方源能跑说明问题大概率在第三方接口或网络环境上和 opencode 本身没关系。5.3 Maven 项目下 opencode 看不到 Java 依赖和类我自己用 Java 项目时有段时间特别无语opencode 让 AI 读源码文件没问题但让它分析依赖关系和编译错误就经常“失明”。后来发现是 LSP 环境的问题。opencode 的代码诊断能力依赖语言服务端Java 项目的 LSP 需要用到 JDTLS 或 IDE 的语言服务而纯终端环境里它没有足够的上下文支撑。我的解决办法是确保在项目根目录启动 opencode让模型先读pom.xml或build.gradle再问依赖关系如果涉及到具体编译错误最好配合 JetBrains 插件或者直接在 IDE 里看红标再把错误信息复制给 opencode。我个人经验是Java 项目里 opencode 更适合做“脚手架生成”“批量修改”“生成测试”不适合做实时依赖分析。前端、Python、Go 项目的体验通常要好很多。5.4 输出乱码、回复不符合预期怎么办如果 AI 回复里中文乱码或者回答风格不是你要的先别急着换工具。检查两件事第一确认终端编码。Windows 的 PowerShell 和 cmd 默认编码有时不是 UTF-8在启动 opencode 前执行chcp 65001可以切到 UTF-8 编码能解决大部分乱码问题。第二通过指令约束。在opencode.json的instructions文件里写清楚回答请使用中文。 解释问题先给结论再给详细步骤。 代码示例需要包含注释。模型是跟着指令走的你不说清楚它就按自己的习惯输出。这个跟人沟通是一样的逻辑。5.5 如何升级与避免升级后配置失效opencode 迭代速度极快热门搜索里已经有 2.0、桌面版、各种插件相关的问题。我自己的升级习惯是npm update -g opencode-ai升级完先跑一下opencode --version再打开一个简单的项目试一下常用功能。如果发现某个命令或配置字段失效去官方 changelog 看一下改动常见配置迁移其实都有文档。有时候新版本会改默认行为比如权限策略更严格了、某个 Provider 的配置方式变了。这种时候我建议保留旧版本的配置备份避免直接覆盖。我的做法是升级前把~/.config/opencode/opencode.json复制一份带日期的备份回滚时可随时恢复。最后说一个我自己的土办法在全局配置里只留一套最小可用的基础配置Provider 权限 自动更新剩下的都放项目级配置里。这样升级导致全局配置变化时影响面最小项目级特殊配置也能稳定保留。归根结底opencode 这类终端 Agent 的价值不在“哪个模型聪明”而在于它把多模型、工具链、项目规范这些碎片化的事情收敛到了一个入口里。我用这一段时间的体会是配置花半天后面每天省三小时。尤其是接入了自己的 Skills 和项目规则之后它才真正从一个“聊天窗口”变成了“会干活的组员”。如果你也想试建议从一个小型个人项目开始先把安装、配置、Skills 跑通再逐步扩大使用范围遇到问题不要怕多看日志多调整指令这套工具值得花时间去磨合。