说实话我一开始对 OpenCode 是有点“又一个终端 AI 工具”的冷淡态度的毕竟 Claude Code、Codex CLI 已经够折腾了。但真正把 OpenCode 安装到 Linux 工作机上、又跑完一个真实项目的 bug 修复之后我改观了它确实是一个更开放、更适合“自己掌控模型”的终端 AI 编程助手。这篇内容我就围绕 OpenCode 安装与使用把我从零开始到日常使用过程中所有值得记下来的点都写出来包括免费模型接入、OpenCode Go 套餐、本地 Skills、VSCode/JetBrains 插件、局域网 serve、还有各种报错的处理方式。如果你最近正被“opencodes free tier can only be used from within opencode”这类报错卡住或者想知道归档的对话到底跑哪去了这篇可以直接照着排查。1. OpenCode 是什么先搞清楚再安装1.1 一个运行在终端里的 AI 编程代理OpenCode 是 SST 团队开源的一个 AI 编程代理主要形态是终端里的交互式 TUI 程序。你进入项目目录后执行opencode它就启动一个命令行界面你能像和 ChatGPT 聊天一样让它读代码、改代码、跑命令、提交 git甚至在一个多文件任务里连续工作。但 OpenCode 和普通聊天网页不一样的地方在于它能感知你本地仓库的上下文。启动时会读取 git 状态、文件结构还会主动去翻你指定的文件。配合AGENTS.md这类项目说明它能在不把整个仓库塞进上下文的情况下按需去查看相关文件。这一点对真实项目非常重要因为现在的大模型上下文窗口再大也不可能把几万行代码一次性塞进去必须靠工具主动检索。我比较喜欢它的插件化设计。官方提供了一个 provider 抽象层你可以很清楚地配置 OpenAI、Anthropic、Ollama、本地模型等不同来源。对比 Claude Code 基本绑定 Anthropic 系模型OpenCode 的“模型自由”对经常要切换便宜模型、本地模型的人来说很友好。1.2 和 Claude Code、Cursor 相比为什么要选它网上总有“谁取代谁”的争论但工具选择本质上是在看场景。我把几个常用选项放在一个表里方便你判断。维度OpenCodeClaude CodeCursor运行载体终端 TUI终端 TUI独立编辑器 / IDE 插件开源情况开源闭源闭源主体是商业产品模型接入OpenAI、Anthropic、Ollama、兼容端点等主推 Anthropic 系也可配其他端点自带模型订阅也支持 BYOK上下文管理按文件/命令动态读取类似有自动工具调用IDE 索引 手动引用Skills / 自定义指令支持 SKILL.md有 Skills有 Rules但封闭团队复用可serve暴露服务不太方便商业套餐我个人的结论是如果你常年待在终端里用 tmux / zellij 工作那 OpenCode 会让你觉得顺手。如果你想要多模型切换尤其想用 Ollama 跑本地模型处理敏感代码OpenCode 比 Cursor 更透明。如果你团队里有统一的 API Key想给同事提供一个轻量客户端OpenCode 的 serve 模式很有用。当然Cursor 在 IDE 内的交互体验依然有优势比如可视化 diff、精准代码补全OpenCode 不是来替代 IDE 补全的它更像是“干活代理”而不是“打字机”。2. OpenCode 安装Linux、macOS、Windows 的完整姿势2.1 一行脚本安装和二进制包安装OpenCode 的安装方式比较多我按优先级说一下我常用的几种。第一种官方一键脚本适合 Linux 和 macOScurl -fsSL https://opencode.ai/install | bash这个脚本会检测系统架构下载对应压缩包并解压到~/.opencode/bin之类的目录然后提示你把它加到 PATH。如果你在 CI 环境或容器里也建议先看脚本内容再执行毕竟是管道到 bash谨慎一点没坏处。第二种HomebrewmacOS 用户会比较熟悉brew install sst/tap/opencode因为 OpenCode 更新很勤快Homebrew 方式升版本方便brew upgrade opencode一下就行。第三种npm 全局安装。如果你本机本来就有 Node.js 环境这是最省事的方式之一npm install -g opencode-ai安装后opencode --version能直接打印版本那就没问题。Windows 用户在 PowerShell 里如果不想开 WSL也可以把 npm 的全局 bin 目录加到环境变量里使用不过我个人建议 Windows 下还是优先用 WSL因为 OpenCode 的终端交互在 Windows Terminal WSL 里更顺原生的 PowerShell 偶尔会遇到 ANSI 渲染和路径兼容问题。如果你不想用包管理器也可以直接去 GitHub Releases 下载对应平台的 zip/tar.gz 压缩包解压后把可执行文件丢到任意 PATH 目录里。这是最“裸”的安装方式适合内网环境。2.2 安装后必做的三件事版本检查、目录确认、登录入口安装完成不是终点我第一次装完就卡在“怎么没有模型列表”上。后来总结出三个必做步骤。先检查版本opencode --version如果输出opencode version x.x.x说明命令可用。如果提示 command not found多半是 PATH 没配置好去~/.bashrc或~/.zshrc里加一行export PATH$HOME/.opencode/bin:$PATH。然后确认配置目录opencode auth list这个命令会列出当前已登录/已配置的认证信息。如果没有输出说明你还没接模型服务。OpenCode 的全局配置在~/.config/opencode/opencode.json历史会话和归档数据一般在~/.local/share/opencode/下具体路径在不同系统上略有差异后面我会单独讲。第三件事才是登录。如果你打算用官方 Console 的免费额度可以执行opencode auth login它会打开浏览器让你完成授权。如果你有自己的 Anthropic 或 OpenAI API Key也可以直接用环境变量方式设置不需要走登录。我踩过的一个小坑是很多人以为安装完打开就能像 ChatGPT 网页版一样直接聊天结果发现界面里一个模型都没有。这不是安装坏了而是你还没有配置任何模型来源。所以“安装完成”和“可以用”之间还差一个模型接入的步骤。3. 模型接入与免费额度别让报错劝退你3.1 先分清 providerOpenCode 控制台、OpenAI、Anthropic、OllamaOpenCode 把模型来源统称为 provider。常见的几种情况官方 Console provider你可以通过opencode auth login登录获得一些免费模型的调用额度。这类模型只在 OpenCode 内部使用限制比较多。自带的 API Key通过环境变量或配置文件指定ANTHROPIC_API_KEY、OPENAI_API_KEY等。例如 Anthropic 的模型export ANTHROPIC_API_KEYsk-ant-xxxx然后启动 OpenCode在模型列表里选 Claude 系列。Ollama 本地模型如果你机器上装了 Ollama并在本地拉好了模型OpenCode 可以在 provider 里配置 ollama 地址直接调用本地模型。兼容 OpenAI 协议的网关很多公司内部会有统一的 API 网关OpenCode 支持自定义 baseURL指向这些网关。我的经验是先用自带 API Key 跑通最简单的链路再考虑本地模型。很多新手一上来就想用 Ollama 跑大模型结果发现速度慢、效果差以为工具不行其实是模型能力和显存问题。3.2 “opencodes free tier can only be used from within opencode” 到底在说什么这是一个出现频率非常高的报错你甚至能在搜 OpenCode 相关问题时直接看到这个长句子。我第一次看到是在 VSCode 插件里心想“我不是正在 opencode 里吗”结果死活不给我用。这个报错的实际含义是你当前使用的“免费模型/Console provider”只能在 OpenCode 官方终端界面内部使用。也就是说如果你用桌面客户端、VSCode 插件、JetBrains 插件、局域网 serve 模式或者通过其他中间层代理去调用这个免费 provider服务端会拒绝。解决方式有三种回到 OpenCode 的 TUI 里直接使用不经过其他插件。最简单但是最受限制。换成你自己的 API Key。在环境变量里配置或者opencode.json里写 provider。这样无论是插件还是 serve 模式都不会触发这个限制。如果你一定要在插件里用免费额度就只能检查插件是否支持透传某个“内置登录态”。以我目前看到的情况官方插件并未开放这种能力别浪费时间去折腾。这个报错本质上不是在说你的网络有问题而是授权范围问题。所以排查的时候不要去看网络代理也别去调什么 DNS先把 provider 来源换掉。3.3 OpenCode Go 订阅套餐和接入 Codex 的实操OpenCode Go 是官方生态里面向需要“一站式模型服务”的订阅方案你可以把它理解成 OpenCode 团队帮你把多个模型 API 做了聚合和计费管理。订阅之后你能得到一个专属密钥不用自己分别去注册 OpenAI、Anthropic 等平台一个 key 就能在 OpenCode 里切换多种模型。我第一次弄的时候也搞不清“有密钥怎么连接”。其实步骤很直接在 OpenCode Go 后台完成订阅创建访问密钥。把密钥配置到环境变量或opencode.json里。在 OpenCode 的模型列表里选择 Go 服务提供的那几个模型名如果列表里没有检查密钥是否绑定成功或者手动指定--model参数。接入 Codex 模型也是类似思路。只要你订阅的套餐里包含 Codex 相关的模型端点就不需要再去单独拿一份 Codex API Key。实际使用时在模型选择里找到对应 Codex 模型即可。不过要提醒一点订阅类服务都会涉及费用模型价格和套餐内容可能随时调整。官方文档里写得最清楚别只听二手信息。我自己是小额订阅试了一个月确认我日常用的 Claude 和 Codex 模型都能覆盖才继续保留。3.4 免费模型到底怎么选Granite、Ollama 本地模型的配置示例“免费模型”在 OpenCode 里分两层意思。一是官方 Console 的免费额度二是在本地跑开源模型不产生 API 费用。如果你因为隐私问题必须在本地跑我建议从 IBM Granite 这类对开放权重友好的模型试起。比如用 Ollama 拉一个 Granite 小模型ollama pull granite3.2:8b然后在 OpenCode 的配置文件里加入 ollama provider{ $schema: https://opencode.ai/config.json, provider: { ollama: { models: { granite3.2:8b: {} } } } }启动opencode后用/models切换到 granite 模型。如果模型列表里还是看不到可以检查 Ollama 服务是否在跑访问默认端口 11434 是否通curl http://localhost:11434/api/tags本地模型最大的优点是数据不出机器但要注意你的 CPU/GPU 性能决定了体验。8B 级别模型在带 16GB 以上内存/显存的机器上可以跑但复杂推理任务会比较慢。如果你只是拿来做代码片段解释、补注释那完全够用真要靠它原生修复大型项目 bug大概率会让你等得想砸键盘。4. 跑本地项目、自动改 Bug 和 Skills 实战4.1 首次打开项目让 AI 先“认识”代码库很多人在项目根目录直接运行opencode上来就贴报错让它修结果 AI 对项目结构一无所知改得牛头不对马嘴。正确的做法是先帮助它建立“项目地图”。进入项目目录后启动cd /path/to/your/project opencode会话开始后第一段对话不要急着让它改代码先描述项目背景。比如“这是一个使用 React TypeScript 的前端项目主要目录在 src 下路由配置在 src/router状态管理用的是 zustand。请你先看一遍 package.json 和 README然后给我一份项目结构和可能存在技术债的地方。”OpenCode 会自己去读文件然后输出它的理解。如果项目里有AGENTS.md或CLAUDE.md这类说明文件它也会读取。我更推荐你把长期有用的约束写成AGENTS.md比如“禁止直接修改公共组件”“测试必须使用 vitest”等。这样每次新开会话AI 都能通过这个文件快速了解项目规矩不用你反复叮嘱。第一次会话也可以让 OpenCode 生成一份AGENTS.md草稿然后你手动删改。实测下来这一步花费十分钟后面能省下很多沟通成本。4.2 用 OpenCode 自动改 Bug 的最小闭环自动改 Bug 不是把报错丢给它然后坐等奇迹而是需要形成一个闭环。我现在的流程是先复现问题拿到稳定可复现步骤或错误日志。运行测试/构建命令把失败输出复制到 OpenCode 会话里。明确限制 AI 的工作范围比如一句 prompt “请只修改 src/utils/format.ts 文件修复日期格式错误不要重构其他代码不要改动无关依赖。”AI 给出修改方案并落地后我立即运行测试验证。如果还是失败就把新的报错继续丢回去。验证通过后用git diff审查改动有疑问的地方直接让 AI 解释。这个闭环最关键的一步其实是 prompt 里的“限制范围”。我见过太多次 AI 顺手帮你把一整个模块重写了导致 review 成本比手工修 bug 还高。建议你在执行任何修改前给它一个“小步走”的约束。比如让它先只输出 diff不要直接写入文件你确认思路没问题后再跟一句“现在按刚才的方案修改”。OpenCode 支持动态调整回滚也有办法但是提前控制明显更省事。如果改了之后又后悔了可以用/undo撤销最近一次文件变更。但注意这个操作是有限度的如果你中间夹了多次手动修改或者 AI 已经执行了 git 提交那 /undo 可能不会完全恢复最好依赖 git 分支来做安全网。4.3 Skills 安装与使用从零到能跑通一个 SkillOpenCode 的 Skills 是它让我觉得最“可扩展”的地方。简单理解Skills 就是一套预置指令/技能包你可以把一些重复性的工作流程变成一个命令之后在会话里通过#skill名唤起。Skills 的路径分为全局和项目级。全局放在~/.config/opencode/skills/下项目级放在.opencode/skills/下。每个 skill 就是一个包含SKILL.md的目录例如~/.config/opencode/skills/ review/ SKILL.mdSKILL.md 的内容可以很简单--- name: review description: 对当前改动做代码审查重点看安全和错误处理 --- 请从以下三个维度审查代码 1. 是否存在安全问题 2. 异常分支是否处理完整 3. 并发访问是否可能产生竞态 只输出问题和修改建议不要直接改代码。然后在 OpenCode 会话里输入#review它就会把这个 Skill 作为指令加载。你可以把常用的“前端页面接入规范”“后端接口排错流程”做成各种 SKILL.md团队之间甚至可以直接拷贝目录同步。如果你想省事社区里有现成的合集比如 oh-my-opencode 项目类似 oh-my-zsh 的思路一次性给你配置好快捷命令、主题和一批常用 skills。安装后你可以快速查看有哪些 skill不需要就删掉。我自己用下来最常用的是 code-review 和 explain 这两个因为它们能强制 AI 按固定结构输出减少废话。5. 把 OpenCode 用到日常开发环境里5.1 VSCode、JetBrains、PyCharm 插件装好后要注意什么OpenCode 不是只能活在终端里VSCode 和 JetBrains 生态都有集成方式。VSCode 用户在扩展市场搜 OpenCode 就能找到官方扩展。安装后你可以在侧边栏打开一个 OpenCode 面板和在终端里会话互通。我第一次在 VSCode 里用它的时候踩到一个问题模型列表是空的。折腾半天发现因为我在扩展面板里调用的是官方 Console 免费模型触发了前面说的 “free tier can only be used from within opencode”。后来我把 provider 切换成自己的ANTHROPIC_API_KEY模型列表立刻正常了。JetBrains 家族IDEA、PyCharm 等也有 OpenCode 插件安装方式类似在插件市场搜索后 Install。装好后要留意插件使用的可执行文件路径有时候它默认找不到你通过 Homebrew 安装的opencode需要在插件设置里手动指向。如果你用 Cursor会发现在扩展市场里搜不到 OpenCode。这不算异常Cursor 的扩展市场并不完全等于 VSCode 市场很多第三方扩展需要下载 vsix 文件后通过“Install from VSIX”手动安装。不过就算装上也建议重点使用终端方式因为 IDE 插件的体验目前还做不到和原生 TUI 完全一致。还有一点如果你在插件里经常遇到“一个模型也没有”先不要怀疑插件坏了优先检查两件事一是有没有配置任何 provider二是当前 provider 是不是被限制为 “console free tier”。排查顺序对了问题就好解决。5.2 opencode serve 在局域网里当团队服务用OpenCode 支持以服务方式启动也就是opencode serve。这让你可以把 OpenCode 的能力通过 HTTP 暴露到局域网团队内部可以共用同一个服务端和统一的模型配置。简单启动方式opencode serve --host 0.0.0.0 --port 8080这样它监听所有网卡其他机器可以通过http://你的IP:8080访问。如果你的同事用的也是 OpenCode可以在配置里把这个服务地址作为 provider 端点指向进来。但这里我要非常认真地提醒不要直接把serve暴露到公网。这个服务本质上是在帮你执行代码里的命令如果被恶意调用等于是把你电脑的“操作权限”开了个口子。准确做法是只在可控的内网使用或者用带身份验证的反向代理包一层。我在实际使用中只会绑内网 IP例如opencode serve --host 192.168.1.100 --port 8080另外serve模式同样受 provider 限制免费控制台模型大概率没法在服务模式下工作。所以如果你规划团队共用务必配置好 API Key 或 OpenCode Go 密钥并且给同事设置不同的会话目录避免相互干扰。5.3 对话记录归档到哪里去了很多人在 OpenCode 里聊完一波后想找历史会话会疑惑“归档的对话到底去哪了”。其实 OpenCode 默认就把会话数据保存在本地磁盘按时间记录。在 Linux 上常见路径是~/.local/share/opencode/macOS 上通常是~/Library/Application Support/opencode/Windows 上通过 WSL 或原生使用时可能在%USERPROFILE%\.local\share\opencode\里面会有 message、session、archive 之类的目录或数据文件。你可以在 TUI 里通过会话管理功能切换到历史对话也可以直接去这些目录里翻 JSON/Markdown 文件做备份。我的习惯是每周导出一次关键会话尤其是那些包含复杂排错过程的内容。这些记录对后来写技术方案、复盘故障很有帮助。也不要忽略这些文件可能包含敏感代码片段如果电脑会借给别人或者要同步到云盘先想清楚隐私风险。6. 高频报错与排查一张表解决 90% 问题6.1 各种环境和工具链的报错速查表我整理了自己和身边同事遇到过的高频问题做成一张速查表遇到类似情况直接对着看。报错 / 现象可能原因处理方法error from provider (console): opencodes free tier can only be used from within opencode在非 OpenCode TUI 环境使用免费控制台模型换 API Key provider或在 TUI 内使用模型列表为空没有配置 provider或只配置了免费模型但环境受限配置ANTHROPIC_API_KEY/OPENAI_API_KEY或添加 Ollama provideropencode: command not foundPATH 未包含安装目录检查安装目录并添加 PATH重新打开终端Ollama 连接失败Ollama 服务没启动或 host 配置不对执行ollama serve用curl localhost:11434/api/tags验证VSCode 扩展里搜不到模型免费控制台模型限制换成自己的 API KeyCursor 搜不到 OpenCode 扩展Cursor 扩展市场不包含该扩展下载 vsix 手动安装或直接用终端JetBrains 插件提示找不到 opencode插件里可执行文件路径未配置在设置里指定which opencode的路径opencode serve局域网无法访问绑定地址默认不是 0.0.0.0或防火墙拦截显式绑定--host 0.0.0.0放行端口OpenCode 2.0 升级后配置不生效配置 schema 变化查看官方配置文档重写opencode.jsoncc-switch 连接 OpenCode / Ollama 不成功端点和模型名不匹配在 cc-switch 里确认 baseURL 是 Ollama 或 OpenCode 的实际地址6.2 排查思路与日志查看遇到问题不要瞎猜。OpenCode 提供了调试级别的日志输出例如opencode --debug日志会打印出模型调用过程、请求耗时、HTTP 状态码等关键信息。如果你在插件里遇到问题也可以直接看插件所在目录的日志文件或者把问题放到终端里复现一次因为终端里的报错信息通常比 GUI 更完整。排查的顺序我建议是先分清楚是“模型接入问题”还是“OpenCode 客户端问题”。比如所有模型都报错大概率是客户端或网络只有某个模型报错大概率是 provider 配置或密钥权限。看配置是否生效。用opencode auth list和opencode models确认当前识别的账号和模型列表。看日志指向的请求地址。如果地址不是你以为的 API 服务检查环境变量是否被覆盖。6.3 我的几个避坑习惯最后分享几个我长期使用下来比较管用的习惯。第一所有 API Key 都通过环境变量注入不要写死在项目目录的配置文件里。哪怕只是个人项目也避免哪天把.opencode.json提交到 git 里导致密钥泄露。可以在.gitignore里把opencode.json.local这类本地配置排除掉。第二重要项目一定先建好AGENTS.md。让 AI 理解项目规则比每次反复解释省力得多而且能明显减少“答非所问”的情况。第三让 AI 修改代码时我会先让它只用 git 分支工作git checkout -b ai-fix-20250618这样即便改砸了也不会污染主分支。审完 diff 之后再合并回主分支。第四不要在同一会话里无限堆任务。OpenCode 会话上下文再长也有瓶颈任务越堆越多AI 越往后越容易“忘”开头的内容。我会在完成一个耦合紧密的任务后用/new开启新会话然后通过AGENTS.md和之前的归档记录保持连续性。第五涉及敏感代码时直接用 Ollama 本地模型。虽然效果不如云端大模型但数据不出机器这个特性对我来说更重要。你可以根据不同任务切换模型解释代码用本地模型重大重构用云端强模型。我个人现在的工作流是日常轻量任务用 OpenCode 加本地 Granite 模型跑做多文件重构时切到 OpenCode Go 里的 Claude 模型所有关键会话每周归档一次长期项目则维护一份越来越厚的AGENTS.md。这个组合不能说最好但至少让我不再同时开着三四个编程助手互相切换。如果你也打算认真把 OpenCode 用起来建议先从小项目试把模型、Skills、归档这三件事理顺再上到真实的工作仓库里体验会稳很多。