OpenCode 这个名字最近在 AI 编程圈子的出现频率肉眼可见地在涨。有人拿它和 Codex 比有人把它当 Claude Code 的平替还有人单纯想找一个能装在自己电脑上、模型随便换的开源方案。我前后把 OpenCode 从安装到深度使用整个流程走了一遍这篇就把 OpenCode 的安装与使用经验一次性讲清楚包括几个特别容易卡住新人的报错、免费额度的真实规则、以及很多人忽略的 Skill 扩展机制。简单交代一下背景OpenCode 是一个运行在终端里的开源 AI 编码代理你给它一句自然语言指令它能自己读项目代码、修改文件、执行命令中途遇到报错还会尝试自己修。它适合三类人第一类是常年在终端里工作的开发者习惯用 Vim/Neovim 或纯命令行工作流第二类是想要一个不锁定特定 IDE、底层模型可以自由切换的 AI 编程工具第三类是喜欢把重复性工作提炼成固定流程的人OpenCode 的 Skill 机制能帮你把这些流程沉淀成可复用的能力。1. OpenCode 到底是什么——先和 Cursor、Codex 划清边界1.1 一个跑在终端里的 AI 代理而不是又一个 AI 编辑器很多人第一次用 OpenCode 会下意识找编辑器窗口然后发现它根本没有传统意义的图形界面。它的工作场景就是终端你在命令行里敲opencode回车进入一个类似聊天框的交互界面底部输入提示词顶部是模型给出的回复模型能发起文件读写、命令执行等操作。这个定位和 Cursor 完全不同。Cursor 是给编辑器加 AI核心是补全、问答、在编辑器里内嵌一个对话面板OpenCode 是给终端加 AI 代理核心是你把一项任务整体交给它它自己规划步骤并动手执行。打个不那么准确的比方Cursor 更像一个随身副驾OpenCode 更像一个你说完需求就自己去干活、干完活回来找你汇报的临时工。和 Codex 相比OpenCode 最大的差异点在于开源和模型无关。Codex 本身就是绑定 OpenAI 模型的想换 Claude 或本地模型基本绕不开魔改OpenCode 这边的 Provider 配置非常灵活Anthropic、OpenAI、本地 Ollama、所有兼容 OpenAI 协议的网关都能接。这也是它在开源社区里能快速起量的一个重要原因。1.2 它凭什么值得装从实操角度看OpenCode 有几个很抓人的点开源可审计代码全部在 GitHub 上安装之后本地跑什么、数据写到哪个目录全都能查不存在私有闭源工具偷偷上传整个仓库的顾虑。模型无关同一个客户端今天用 Claude 干活明天想试试 Codex 的风味改配置就行不需要迁移工作流。原生终端体验对熟悉命令行的人来说它的效率上限非常高。你可以用opencode run 修复某个测试用例这种非交互方式把它接进自己的脚本或 CI 流程里这一点是图形界面工具很难做到的。可扩展的 Skill 机制把团队的代码规范、审查流程、发版检查清单封装成一个个 Skill让模型在特定场景下自动套用这些规则。这些特性叠加起来决定了它不是一个玩具而是能真正嵌入日常工作流的生产力工具。1.3 归档风波与社区继任提到 OpenCode避不开那个让不少人困惑过的问题项目归档后去哪了大概在 2025 年年中原维护团队把最初的 OpenCode 仓库标记为归档很多关注者一度以为项目凉了。实际的情况是社区在opencode-ai这个账号下继续接过了维护工作新仓库保持了非常高的活跃度版本更新速度和 issue 响应都比想象中好。这个背景对使用者有一个直接影响你在网上搜资料时会看到大量基于旧仓库的教程里面提到的安装命令、配置路径很可能已经过时。建议以官网 opencode.ai 和 GitHub 上opencode-ai/opencode仓库的 README 为准遇到教程和官方文档冲突时优先信官方文档。2. 安装全流程命令行、桌面端、VSCode 插件三条路线2.1 前置环境先把 Node.js 准备好OpenCode 的 CLI 版本本质是一个 Node.js 应用安装前需要本机有可用的 Node.js 环境。我这里用的是 Node.js 20 LTSOpenCode 对 Node 版本的要求不算苛刻但建议至少 18 以上太老的版本容易在安装依赖时出问题。检查本机 Node 版本的命令node -v npm -v如果node命令不存在先去 Node 官网下载 LTS 版本安装。这里有一个很常见的坑直接用系统包管理器装的 Node版本可能很旧导致 OpenCode 装上之后一启动就报语法错误。我自己在 Ubuntu 上遇到过一次后来改用 nvm 管理 Node 版本才消停。提示如果你之前用sudo npm install -g装包时遇到过 EACCES 权限错误说明你的 npm 全局目录权限有问题建议先装好 nvm再用 nvm 来管理 Node而不是硬着头皮用 sudo 全局装包。2.2 两种主流安装方式官方脚本与 npmOpenCode 官网提供了一键安装脚本也支持 npm 全局安装两种方式我都实测过# 方式一官方安装脚本macOS / Linux curl -fsSL https://opencode.ai/install | bash # 方式二npm 全局安装 npm install -g opencode-ai安装脚本的优点是省事它会自动把可执行文件放到你的用户目录下并写入 PATHnpm 方式的优点是版本管理直观以后想升级直接npm update -g opencode-ai就行。我个人最终留在 npm 方式理由是升级链路更统一也方便用 npx 临时跑某个版本。安装完成后命令行里验证一下opencode --version能输出版本号就说明环境基本没问题。如果提示command not found大概率是 npm 全局 bin 目录没在 PATH 里定位方式我放在后面的排查章节细说。2.3 Windows 和 VSCode 插件路线Windows 用户有两个选择一是用 WSL 里的 Linux 环境安装二是直接装桌面版。桌面版是图形化打包好的应用官方下载页有 Windows 安装包拿到之后一路下一步即可。安装过程中如果 Windows SmartScreen 弹了你的组织使用适用于企业的应用控制阻止此应用这类提示先确认安装包来源是不是官网然后在确认安全的情况下选择仍要运行。这个拦截其实和 OpenCode 本身没有关系是 Windows 对未签名应用的默认策略很多人第一次遇到会误以为是安装包有问题。VSCode 生态也有对应的 OpenCode 插件在扩展市场直接搜 OpenCode 就能找到。装好之后左侧活动栏会出现 OpenCode 图标打开就能在编辑器里直接进入对话。这里有一个很容易忽略的细节VSCode 插件本质上还是会调用本机的opencode命令。如果你只装了插件、没装 CLI打开插件时会报找不到命令。所以正确顺序是先装好 CLI再装 VSCode 扩展。插件还会在第一次使用时询问 OpenCode 的可执行文件路径如果 CLI 不是通过安装脚本装的建议手动确认路径是否配置正确。为了方便对比我把三条安装路线的特点整理如下安装方式适用场景优点注意点命令行 / npm日常终端使用者灵活支持非交互模式可接入脚本需要 Node.js 环境桌面版Windows / 不习惯终端的人群图形化界面安装简单体积比 CLI 大更新依赖应用商店VSCode 插件编辑器用户和编辑器集成度高依赖本机 CLI必须先装 CLI2.4 安装后的第一次启动体验在前面这些步骤都完成后进到一个测试项目目录直接运行opencode第一次启动会做一些初始化然后进入交互界面。界面底部是一个输入框顶部是模型回复区。首次使用会让你选择模型 Provider这个环节很多人会被绕晕我放在下一章详细讲。输入/help可以查看内置命令列表建议第一件事先把这个列表扫一遍至少记住/models查看和切换模型、/init生成项目全局规则、/undo撤销模型最近一次操作这几个高频命令。3. 模型接入与免费额度规则那个报错到底在说什么3.1 首次启动的模型选择逻辑OpenCode 的模型不是写死的而是通过 Provider 机制接入。所谓 Provider就是模型服务来源可以理解为负责输出回复的后端。官方内置了 Anthropic、OpenAI、OpenCode 免费通道等常见 Provider同时也支持通过配置 opencode.json 来自定义兼容 OpenAI 协议的网关。首次启动时交互界面会引导你选择一个 Provider。如果你没有现成的 API Key可以直接选 OpenCode 官方的免费通道也就是界面里标注了 free 字样的模型选项。这个免费通道是 OpenCode 给用户提供的一个入门方案不需要自己申请各类模型服务的 API Key在客户端里就能直接发起对话。3.2 深度拆解 error from provider (console) 这个报错社区和热搜里非常高频的一条报错是error from provider (console): opencodes free tier can only be used from within opencode这条报错让很多人一头雾水既然是免费模型为什么我调不通问题出在调用的方式上。这个免费额度的设计初衷是限定在 OpenCode 客户端内部使用。OpenCode 的免费通道本质是一个受保护的转发服务它只接受来自 OpenCode 客户端发起的请求。如果你尝试把这个通道的接口地址或参数扒出来放到浏览器控制台、Postman、curl 或者其他第三方工具里手动调用服务端就会返回上面这句报错直白点说就是免费额度只能在 opencode 里用不允许绕过客户端当公共 API 用。我见过有人把这个 Provider 的配置填到其他编程工具里想给别的应用白嫖算力结果同样是这个报错。这其实是一种防滥用手段不是 OpenCode 出了 bug。遇到这条报错时正确的处理思路只有两个如果你确实想用免费通道那就老老实实在 OpenCode 客户端内使用不要把它提取出来搬到别处。如果你想在其他工具里用模型去申请对应模型服务自己的 API Key或者跑一个本地模型不要打 OpenCode 免费通道的主意。3.3 OpenCode Go 套餐与 Codex 接入除了免费通道OpenCode 生态里还有一个付费订阅叫 OpenCode Go。我目前了解到的情况是它主要解决的是省去你自己去各个模型厂商单独申请和配置 API Key的麻烦订阅之后能在客户端内直接获得包括 Claude、Codex 等更强模型在内的使用通道。对个人开发者来说这比分别去几个平台注册、充值、管理多个 Key 要省心不少。接入手感上开通 OpenCode Go 之后模型的 Provider 列表里会多出对应选项选中就能用不需要自己往配置文件里写复杂参数。不过这个套餐的具体定价、模型列表变动比较频繁我的建议是以上官网最新的订阅页说明为准别轻信二手信息。这里也要多说一句Codex 的名字最近在热词里出现频率很高很多人问 OpenCode 能不能接 Codex。答案是可以的。不管是通过 OpenCode Go 的通道还是你自己配置 OpenAI 相关的 Provider都能在 OpenCode 客户端里获得使用 Codex 系列模型的能力。这和把 Codex 命令行工具单独装一套是两条不同路径前者是把模型接到 OpenCode 里用后者是直接用 Codex 自己的 CLI各有各的适用场景。3.4 免费替代方案本地模型与兼容网关如果你既不想订阅又不想用免费通道的客户端绑定限制本地模型是另一个可靠方向。OpenCode 支持通过 Ollama 接入本地模型配置方式是在 opencode.json 里声明一个本地 Provider{ $schema: https://opencode.ai/config.json, provider: { ollama: { npm: ai-sdk/ollama, name: Ollama, options: { baseURL: http://localhost:11434/v1 }, models: { qwen2.5-coder:14b: { name: Qwen2.5 Coder 14b } } } } }本地模型的好处是数据完全不出机器隐私边界清晰代价是模型能力相比云端旗舰模型有明显差距复杂重构类任务会吃力。我现在的用法是日常简单问答和低风险任务走本地模型真正要动大手术的重构任务再切到云端强模型。4. 核心使用路径从一句提示到一次可靠的代码改动4.1 交互式会话与任务回滚安装配置好之后日常使用的主场景是在项目目录下运行opencode进入交互式会话。你输入一个任务描述比如帮我看看这个项目的依赖版本有什么问题模型会自己开始读代码、分析并在需要时向你发起操作请求。这里要重点提一下操作确认机制。OpenCode 的模型在执行文件写入、命令运行时会请求你的授权你需要在界面上确认。这个过程不要一路无脑回车尤其是模型准备执行命令之前看一眼它要跑什么。如果模型做了你不满意的改动/undo命令能回滚最近一次操作。我一开始没太重视这个命令直到有一次让模型批量改文件它改完之后我发现 import 顺序全乱了一个/undo全撤回来这才发现这个功能有多救命。与之配套的还有/redo重做被撤销的操作以及/compact压缩上下文——当对话太长、模型开始忘记前面内容时用 compact 能缓解。4.2 权限控制防止模型执行危险操作OpenCode 的权限模型是模型发起用户确认但每个操作都弹确认框也会烦。它允许你对不同操作设置策略比如读取文件允许,编辑文件允许,执行命令每次都询问。我个人的建议是执行命令这个动作保持每次询问至少在你不完全信任项目的环境下这样做。有一次模型在帮我排查测试失败时想跑一条rm -rf相关命令虽然它的意图是清理构建产物但这种命令一旦路径拼接出错后果很严重。我当时因为正忙着看另一个文件差点直接按了确认反应过来之后立刻取消了。从那以后我就把命令执行权限调成了每次询问。你可能觉得这是小事等真出一次事就明白了。4.3 非交互模式把 OpenCode 接进脚本OpenCode 最有别于图形工具的地方是它的非交互模式opencode run 检查当前分支上所有改动找出潜在的空指针风险opencode run会直接执行任务并退出不需要你进入交互界面。这意味着你可以把它写进 shell 脚本、接到 Git hooks 里、甚至放进 CI 流程。比如我自己的一个习惯是用一条命令让模型对 git 暂存区的改动做一次快速 review输出结论然后再考虑要不要把建议应用到代码里。这种先给结论、再动手改的模式相当于给命令行加了一个 AI 审查员而且完全不影响原来的人工代码流程。4.4 让模型长期记住项目规则/init 与 AGENTS.md很多人用了很久 OpenCode可能都没发现/init命令的价值。/init会在项目目录下生成一份AGENTS.md文件你可以把项目的架构约定、代码风格、常用命令写进去。之后模型每次在这个项目里工作时都会自动读取这份文件相当于一个项目入职手册。我接手一个老项目时会花 10 分钟把项目启动命令、测试命令、目录结构说明、命名规则写进AGENTS.md之后模型的所有操作都会更贴合项目实际而不是给出泛泛的、不符合项目约定的建议。这个习惯值得刻意养成它对提升任务成功率非常明显。5. Skill 机制把重复劳动封装成可复用的能力5.1 Skill 是怎么工作的Skill 是 OpenCode 的扩展体系你可以把它理解成给模型预置的一套专业流程。一个 Skill 本质上是一个包含说明文档的目录说明文档里写清楚当用户触发这个 Skill 时模型应当按什么步骤做什么事。维基百科式的定义不重要重要的是它能解决什么问题你希望模型每次做代码审查时都按团队的 Checklist 来而不是随心所欲地看。你希望模型每次发版前都自动检查版本号、更新日志、依赖锁定文件。你希望模型在写提交信息时统一使用 Conventional Commits 规范。这些都能通过 Skill 固化下来。第一次配置需要花点时间但配置一次之后团队每个人都能复用同一套规则产出质量稳定得多。5.2 Skill 的存放位置与安装现成 SkillOpenCode 会从固定的目录读取 Skill常用的是全局 Skill 目录和项目级 Skill 目录全局~/.config/opencode/skills/项目级项目根目录/.opencode/skills/每个 Skill 是一个子目录目录里必须有一个SKILL.md文件这个文件是 Skill 的核心。找到需要的 Skill 后把整个目录放到上面两个路径之一即可。安装完成后在交互界面里输入/skills能查看当前所有可用的 Skill。5.3 手写一个最简单的 Skill自己写一个 Skill 一点都不神秘我来演示一个最简的代码审查Skill目录结构~/.config/opencode/skills/code-review/ └── SKILL.mdSKILL.md内容--- name: code-review description: 对当前分支相对主分支的所有改动进行代码审查按固定清单输出结果。 --- 当用户请求进行代码审查时请严格按照以下步骤执行 1. 使用 git diff 获取当前分支相对主分支的改动。 2. 按下面的清单逐项检查改动不要遗漏 - 是否存在明显的前端显示问题 - 是否缺少必要的错误处理 - 是否存在调试遗留代码 - 命名是否符合项目约定 - 是否引入了不必要的依赖 3. 输出格式先给总体结论通过 / 不通过 / 需要修改再按严重程度列出问题清单每个问题必须给出文件路径和行号。 4. 除非用户明确要求否则不要直接修改代码只输出审查报告。这里的 YAML frontmatter 部分定义了 Skill 的名称和描述正文则是给模型的完整指令。保存之后同一个会话里新发起的请求如果匹配到这段描述模型就会自动激活这个流程。Skill 的日志输出能力也很实用。比如我写过一个小 Skill要求模型每次完成任务后用中文输出变更摘要和建议的测试范围这让团队在多人协同时能快速知道 AI 做了什么、下一步该人工做什么。封装重复事项这件事一旦开始就停不下来因为边际成本太低了。6. 配置、数据安全与高频问题排查6.1 配置文件与备份OpenCode 的全局配置文件在~/.config/opencode/opencode.jsonWindows 下一般是%USERPROFILE%\.config\opencode\opencode.json。模型列表、Provider 参数、界面主题、API Key 信息都存在这里面。一个很实用的迁移经验换新电脑时只需要备份这个配置目录和会话数据目录恢复后 OpenCode 的模型配置、历史会话就都回来了。如果你也配置了 Skill记得把skills目录一起打包。备份命令示例tar -czf opencode-backup.tar.gz ~/.config/opencode ~/.local/share/opencode我习惯每两周备份一次放在自己的备份目录里虽然不是天天变化但真到换机或重装系统时能省大量重新配置的时间。6.2 数据安全本地能控制什么云端会发送什么OpenCode 的数据安全边界是所有认真用它做正经项目的人都会关心的点。需要区分两种情况配置、会话记录、日志、Skill 文件这些默认存储在本地目录由你自己掌握。模型请求内容当你使用云端模型Anthropic、OpenAI、OpenCode 免费通道等时你的提问和代码片段会被发送到对应模型服务商进行处理这是所有云端 AI 工具的共同特性不是 OpenCode 特有的风险。所以如果你的项目涉及核心商业代码、客户隐私数据或者处于安全合规要求很高的环境里建议优先使用本地模型或私有化网关。如果你用云端模型至少要了解你的数据会流向哪里不要在一个涉及机密的仓库里随意使用任何云端 AI 工具。OpenCode 本身也有一些可以关闭的遥测选项在配置里能找到对应开关在意隐私的可以主动关掉。6.3 高频问题排查清单我把实际使用中遇到过的和社区里高频出现的问题整理成一个清单方便你直接对照解决现象可能原因处理办法command not found: opencodenpm 全局 bin 目录不在 PATH 里执行npm bin -g找到全局目录把它加到 shell 的 PATH 变量中启动报 Node.js 语法错误Node 版本太旧用 nvm 装当前 LTS 版 Node.jsVSCode 插件打不开提示找不到命令只装了插件没装 CLI先全局安装opencode-ai再重启 VSCode模型不回复卡在转圈网络无法连通模型服务检查是否能访问对应模型服务的接口地址再检查 API Key 是否有效提示 key 未配置配置文件里缺少对应 Provider 的 key在opencode.json里补全provider配置或用/models重新选择error from provider (console)试图在 OpenCode 客户端外调用免费额度回到客户端内使用其他工具要接模型请使用自己的 API KeyWindows 安装桌面版被拦截SmartScreen 对未签名应用的默认策略确认安装包来自官网后选择仍要运行模型修改了不打算改的文件没在任务里明确边界在提示词里写清楚约束范围或者用/undo回滚长时间对话后模型记忆力下降上下文过长用/compact压缩上下文或开新会话并重新补充关键背景信息最后分享一个我自己的使用习惯。我每周五下午会固定让 OpenCode 做一次收尾第一步opencode run git diff 主分支总结这一周的所有改动要点输出一周工作摘要第二步让它跑一遍我项目的测试命令把失败用例列出来。整个过程都是只读和低风险操作既不会让模型乱改代码又能快速掌握项目全貌。如果你想把 OpenCode 推荐给团队我也建议从这类低风险、只读的任务开始让同事先感受到效率提升再逐步放开文件编辑和命令执行的权限。这个节奏比一上来就让它做大规模重构要稳妥得多。