最近 AI 编程助手里codex CLI 和 Claude Code 火得一塌糊涂但如果你在社区里多逛一圈会发现还有一个老牌开源项目一直被小圈子的人反复推荐就是 opencode。这玩意儿早就不只是又一个终端 AI 助手了它把模型接入、会话管理、技能扩展、数据本地化这些东西揉在一起做成了一个真正能日常上班用的 CLI 工具。这篇东西我就围绕 opencode 的 CLI 交互技巧展开从安装到模型配置从日常操作到报错排查把我实际踩过的坑和觉得好用的玩法一次性整理出来希望能帮正在折腾 CLI 编程助手的你少走点弯路。1. 前后排对比为什么我放着 codex CLI 不用选了 opencode先聊个实际问题现在终端 AI 编程助手的选择太多了。OpenAI 官方有 codex CLIAnthropic 有 Claude Code还有 Trae CLI、zcode CLI 这些新秀。那 opencode 的定位到底在哪我的结论是opencode 更像是一个模型无关的终端编码代理它不在底层绑定某一家模型厂商而是通过 provider 机制让你在同一个交互界面里随意切换 Anthropic、OpenAI、Google Gemini、OpenRouter、Ollama 本地模型等。这个思路跟 codex CLI 不一样codex CLI 核心是给 OpenAI 系模型服务的跟 Claude Code 也不一样Claude Code 强绑定 Claude 模型。opencode 对我这种工作流比较杂的人特别合适。我平时有复杂任务用 Claude 或 GPT 的高端模型简单任务想用便宜模型或者本地模型跑而且希望所有会话都在同一个终端工具里管理。如果每个模型都装一个官方 CLI对话记录分散、交互习惯还不一样维护成本太高。opencode 把这一层统一了我只需要维护一个工具。另外说一下底层实现。opencode 是用 Go 写的单二进制分发启动速度和资源占用明显比 Node.js 系的 CLI 工具要好。我实测在老的 Intel Mac 上codex CLI 冷启动要 1 秒多opencode 基本是毫秒级。做终端工具启动速度直接影响使用频率这是很实在的体验差异。还有一点opencode 的配置和数据都放在本地默认不做遥测数据安全性上相对可控。如果你所在的公司对代码有保密要求或者你自己比较在意代码不被第三方服务拿去训练这一点值得重视。Claude Code 和 codex CLI 数据都要过各自厂商的服务opencode 虽然请求模型时也会把上下文发送给模型提供商但中间环节少了厂商自己的额外采集通道。最后说下开源优势。opencode 的源码在 GitHub 上社区贡献者很多因此新模型支持速度很快。比如某个新模型刚出 APIopencode 的 provider 配置很快就会有对应的预设模板。你不需要等官方 CLI 更新改下配置就能用上这在 AI 模型迭代飞快的当下特别重要。2. 装好并跑通opencode 安装与初始化配置2.1 安装方式选择opencode 的安装方式有几种我分别说下适用场景。第一个是官方脚本安装适合 macOS 和 Linuxcurl -fsSL https://opencode.ai/install | bash这个命令会下载对应平台的二进制文件到~/.opencode/bin然后在 shell 配置里追加 PATH。装完重开终端执行opencode --version就能看到版本号。第二个是 npm 安装适合 Node.js 环境本来就齐全的同学npm install -g opencode-ai注意包名是opencode-ai不是opencode我一开始就装错了包浪费了几分钟。npm 方式的好处是升级方便一条命令搞定。缺点是依赖 Node 运行时如果你机器上没有 Node还得先装 Node不如直接二进制省事。第三个是 Homebrew 安装brew install sst/tap/opencode这个是社区维护的 tap更新速度还行适合习惯用 brew 管理工具链的 macOS 用户。第四个是 Go 源码编译适合要改源码的开发者go install github.com/sst/opencodelatest装好后放在$GOPATH/bin下注意确认这个目录在 PATH 里。Windows 用户特别注意官方推荐用 WSL2 跑 opencode原生 Windows 终端下有些 TUI 交互按键会不兼容。如果你在 Windows 命令行里装了 codex CLI 能跑但跑到 opencode 发现界面错乱别奇怪这不是你配置错了是终端渲染支持的问题。2.2 配置模型提供商安装好之后你首先要解决的是用哪个模型、走哪个提供商。opencode 支持两种层面的配置一种是环境变量一种是配置文件。环境变量负责存 API Key配置文件负责存交互偏好和 provider 细节。环境变量这块常用的几个# Anthropic 系列 export ANTHROPIC_API_KEYsk-ant-xxxx # OpenAI 系列 export OPENAI_API_KEYsk-xxxx # Google Gemini export GOOGLE_API_KEYAIzaXXXX # OpenRouter一个聚合平台能访问很多模型 export OPENROUTER_API_KEYsk-or-xxxx # 本地模型服务 export OLLAMA_API_KEYollama设置好之后打开终端输入opencode进入交互界面后输入/models你会看到当前可用的模型列表。如果配置了多个 provider列表里会分组展示比如 Anthropic 组、OpenAI 组、OpenRouter 组。用上下键选择回车确认。这里有个很多人忽略的细节opencode 默认的 model 配置写在~/.config/opencode/config.jsonmacOS/Linux或者通过opencode.json放在项目根目录里做项目级覆盖。我自己习惯在项目根目录放一个opencode.json内容是{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-20250514, theme: opencode, agent: build }这样每个项目的默认模型可以不一样比如前端项目默认用 Claude后端项目默认用 GPT互不干扰。$schema字段能让你在 VS Code 里编辑这个文件的时候有自动补全强烈建议写上。2.3 首次启动的登录流程如果你是第一次用 opencode而且想用 Anthropic 或 OpenAI 的模型除了设置 API Key还可以用opencode auth login走 OAuth 登录流程。执行后会弹浏览器让你授权授权完成后会自动写入凭证。我个人的建议是能用 API Key 就用 API Key。OAuth 方式虽然方便但会话的有效期、多设备迁移、团队共享这些场景都不如 API Key 灵活。API Key 只需要写入 shell 配置文件比如~/.zshrc所有终端会话自动生效。还有个小技巧如果你要在 CI/CD 环境里用 opencode记得不要交互式登录直接用环境变量注入 API Key避免凭证写入到镜像或者构件缓存里。3. 交互核心opencode 的日常操作和效率技巧3.1 会话与会话管理opencode 启动后默认进入一个会话session所有对话和操作都在这个会话里完成。会话管理有几个常用命令/new开启新会话/list列出所有历史会话/resume id恢复指定会话/delete id删除会话/compact压缩当前会话上下文上下文太长时用这个会话的保存是自动的你不需要手动保存。退出 opencode 之后重进用/list就能看到历史会话。这个设计比直接在终端里跑一次性的 AI 命令要实用得多因为是持久化的适合长时间跟踪一个复杂任务。一个我自己的经验给每个任务开一个独立会话不要复用。比如修登录页样式开一个会话重构 API 鉴权逻辑开另一个会话。虽然临时复用省了重新描述上下文的时间但到了后期你会发现上下文里掺杂了太多上个任务的对话模型会变得精神分裂回答质量明显下降。宁可多花 30 秒重新描述上下文也不要在一个汇聚了五个任务的会话里挣扎。3.2 交互模式与确认机制opencode 在对话时有两种主要模式plan 模式和 build 模式。plan 模式是只读模式AI 只会分析代码、给出修改建议不会真正动文件build 模式是执行模式AI 可以读文件、改文件、执行命令。默认是 build 模式但复杂任务我强烈建议先切到 plan 模式/plan让 AI 先输出一个完整的修改方案你审核通过后再执行/build这个习惯能避免大量无效修改。我自己早期用这类工具时直接 build 模式甩需求AI 理解偏差后直接把代码改坏了回滚浪费的时间比前期规划多得多。现在我的流程是plan 模式确认方案 - build 模式执行 - 人工 review diff。效率反而更高。opencode 还有一个很实用的特性TAB 键补全。你在输入框敲几个字按 TAB 会基于当前上下文生成一段建议回复再按 TAB 接受或者继续打字让建议更新。这跟 GitHub Copilot 在编辑器里的补全体验类似但在终端里做到这个体验的工具不多。如果你还没养成按 TAB 的习惯建议刻意练习一周熟练之后你会发现很多简单回复根本不用打完整句子。3.3 常用斜杠命令速查opencode 的斜杠命令体系是它的核心效率组件。除了上面提到的还有几个我每天都会用到的/model快速切换模型。写代码时用高端模型聊方案时换便宜模型能省不少钱/read让 AI 读取指定文件。注意这里需要给相对路径或者绝对路径比如/read src/index.ts/search在项目里搜索代码。比只能在当前会话上下文里翻找要强很多/help查看所有命令帮助/agents切换不同的 agent 角色opencode 内置了 build、plan 等 agent/yolo开启全自动模式所有对文件的修改和命令的执行不再需要你逐个确认/yolo这个命令要特别提醒一下全自动模式下 AI 会直接改文件、直接跑命令如果 AI 理解错了需求后果是灾难性的。我每次用/yolo之前都要确认自己在干什么用的模型是不是可靠改的代码是不是在版本控制里。如果你用 git 管理代码建议在开/yolo前确保当前分支干净或者已经 commit 了一个可回滚的快照。3.4 让 AI 主动读文件 引用与上下文注入opencode 支持用符号直接引用文件或者目录让它成为 AI 的上下文。比如src/main.ts 分析一下这个文件里有没有潜在的内存泄漏你也可以引用目录src/components/ 帮我把这些组件的 props 接口统一一下这个功能比/read更灵活的地方在于引用是显式上下文AI 会把引用的内容作为优先级最高的上下文来处理而/read更像是让 AI 去读文件这个动作AI 需要自己决定怎么解读。日常对话我更喜欢用直接注入指令清晰AI 误解的概率小。另外opencode 有自动文件发现机制。当你问登录页的按钮颜色在哪里定义的AI 会自己搜索项目、定位文件。如果它没找到你可以用手动指定效率会高很多。3.5 多 Agent 与并行的思路opencode 的 agent 概念可以简单理解为不同角色的 AI 配置。build agent 负责写代码plan agent 负责出方案。你可以通过/agents查看当前可用的 agent。如果你想把一个复杂任务拆给不同 agent 做我的建议是不要试图在一个会话里并行而是开多个终端窗口每个窗口跑一个 opencode 会话各自负责一个子任务。因为单个会话的上下文窗口是有限的聚合太多内容反而会让 AI 犯迷糊。多会话多窗口的方式每个任务上下文干净互不干扰最终在 git 里合并就行。不过这里也有个协调成本任务之间的接口需要你作为人来对齐。比如 A 会话改前端组件接口B 会话改后端 API两者命名不一致就会出问题。我在多会话协作时会先在项目根目录写一个docs/architecture.md把接口约定写清楚然后让不同会话都docs/architecture.md引用它这样能最大程度减少各说各话。4. 模型接入与免费额度问题4.1 provider 选择和免费模型的坑opencode 目前主流的模型 provider 有 Anthropic、OpenAI、OpenRouter、Google、Ollama 这几类。OpenRouter 是比较特殊的一个它是聚合平台一个 API Key 能访问几百个模型包括很多免费模型。免费模型这块很多人一上来就想着零成本用大模型于是直接配 OpenRouter 的免费模型或者某些厂商的免费 tier。但这里有一个很大的坑就是热词里提到的报错error from provider (console): opencodes free tier can only be used from within opencode这个报错我之前折腾了好久。它的意思是opencode 自带的免费模型通道只允许在 opencode 官方环境中使用不允许被外部的 console 调试工具或者其他 GUI 客户端调用。换句话说如果你在 opencode 里选了某个标着free的模型它会走 opencode 项目方提供的免费代理这个代理做了来源校验外部工具连不上。解决办法有几个如果你确实想白嫖 opencode 的免费通道就在 opencode 自己的交互界面里用不要去外部客户端调用如果你想在外部工具里用那就不要选 free 模型自己配一个真实的 API Key可以是 OpenRouter 的免费模型也可以是自己付费的模型如果你有 Ollama 本地模型直接走本地就不受这个限制我的建议是免费模型拿来做 demo、学玩法可以但正经干活别依赖免费 model。免费模型要么有速率限制要么上下文短要么推理质量不稳定。省下来的钱不够你多花的时间。用 OpenRouter 上按量计费的低价模型比如 DeepSeek、Gemini Flash 这类性价比远高于折腾免费额度。4.2 接入本地模型Ollama 与 granite如果你对数据隐私要求高或者想在完全断网的环境下使用接入本地模型是必选项。opencode 对 Ollama 的支持很完善配置流程也不复杂。第一步确保 Ollama 服务在跑然后拉取一个模型。granite 是 IBM 推出的开源模型系列最近在开源社区很火非常适合作为本地编码助手ollama pull granite3.3-dense:8b第二步在 opencode 里配置 Ollama provider。opencode 会自动识别本机的 Ollama 服务通常不需要额外配置。如果有问题手动指定一下{ provider: { ollama: { options: { baseURL: http://localhost:11434/v1 } } } }第三步在 opencode 里运行/models找到 Ollama 组下面的 granite 模型选中即可。实测下来granite3.3-dense 8B 这个模型在代码补全、小规模重构上表现还可以但跟云端的大模型比复杂逻辑生成还是有差距。它最大的优势是快、免费、数据不出本机。我通常用它来处理一些简单任务比如写正则、格式化代码、写单元测试模板这种。4.3 用 CC Switch 管理多 Provider如果你同时用 opencode、Claude Code、codex CLI 等多个工具一个个配置 API Key 会很烦。CC Switch 这个工具可以帮你统一管理 Anthropic 和 OpenAI 系列的 API 配置切换时只需点一下。opencode 和 Claude Code 都兼容它生成的环境变量配置。这背后的原因很简单opencode 读取ANTHROPIC_API_KEY和OPENAI_API_KEY等标准环境变量而 CC Switch 就是帮你切换这些环境变量的工具。两者天然兼容。我的实际经验是把 CC Switch 的配置目录和 opencode 的配置目录分开管理别混在一起。CC Switch 管 API Key 切换opencode 管项目级模型选择。分工明确出了问题时排查也容易。4.4 自建 API 网关与代理接入如果你有团队协作需求或者想统一审计所有 AI 请求可以考虑自建一个 API 网关。opencode 支持自定义 baseURL所以理论上任何兼容 OpenAI 或 Anthropic API 格式的网关都可以接入。典型的配置{ provider: { custom: { npm: ai-sdk/openai-compatible, name: My Gateway, options: { baseURL: https://your-gateway.example.com/v1, apiKey: your-api-key } } } }这样配置之后团队里每个人的 opencode 都走同一个网关方便统一计量、限制和审计。不过这种方案需要你自己维护网关服务如果你只有一个人用我不建议上直接用官方 API 就好省心。5. 技能扩展与数据管理5.1 Skills 是什么怎么用opencode 的 skills 功能是后来加上的重头戏相当于给 AI 预置了一组技能包。你可以把它理解成给 AI 提供的一份说明书告诉它在特定场景下应该怎么做。安装 skill 很简单。opencode 会读取项目根目录下的.opencode/skills或者全局配置目录下的skills里面的每个子目录对应一个 skill。每个 skill 目录下放一个SKILL.md文件写清楚这个技能的触发条件和执行步骤。举个例子我写一个前端重构的技能文件.opencode/skills/frontend-refactor/SKILL.md--- name: frontend-refactor description: 前端组件重构助手用于拆分过大的 React 组件、提取公共逻辑、统一样式方案。 --- ## 触发条件 当用户提出以下类型的需求时使用 - 拆分组件 - 提取 Hook - 统一样式 - React 性能优化 ## 执行步骤 1. 分析目标组件的 props、state、副作用 2. 梳理组件依赖关系 3. 按功能边界拆分子组件保持 API 兼容 4. 输出重构方案等待用户确认后再动手改代码配置好之后opencode 会在合适的时机自动加载这个 skill。用户也可以在对话里主动要求用 frontend-refactor 的方式处理。这个功能特别适合沉淀团队的编码规范比如后端接口怎么写错误处理怎么统一日志打点规范是什么这些都能写成 skill让 AI 自动遵循。5.2 对话归档与找回opencode 会自动把每个会话保存为本地文件默认存储目录是~/.local/share/opencodeLinux/macOS或%APPDATA%\opencodeWindows。在这个目录下你会看到以会话 ID 命名的 JSON 文件里面存了完整的对话记录。如果你在/list里执行了某个会话的归档操作归档后的对话会移动到一个archive子目录。我之前一度找不到归档的对话在哪后来才发现是这个问题归档之后opencode的列表界面会把它隐藏起来但文件确实还在磁盘上。如果你想把某个会话导出成可读的 Markdown 给同事看opencode 支持在会话内使用 export 相关的命令或者直接从存储目录里复制 JSON 文件手工解析。日常使用上我自己更常用的是写脚本定期把~/.local/share/opencode下的 JSON 导出成 Markdown放到一个私有仓库里做知识沉淀。时间长了你会发现自己给 AI 描述过的项目背景、技术方案其实是一份很有价值的文档资产。5.3 数据安全与清理opencode 的数据都是本地存储这有一个好处你可以完全控制它。删掉存储目录里的 JSON 文件所有对话记录就没了。同理备份也简单把~/.local/share/opencode整个目录打个包就行。不过也正因为数据是本地明文存储如果你在公共电脑上使用 opencode记得在离开前清理存储目录或者至少把 API Key 从 shell 配置文件里删掉。虽然对话内容一般不涉及 API Key 本身但代码片段和项目结构信息对敏感项目来说也可能构成泄露。还有一点opencode 在请求模型时会把相关代码片段发送给模型提供商。如果你的项目有保密要求要么用本地模型Ollama granite要么至少关掉那些把数据用于训练的模型选项并确认你使用的模型提供商的隐私政策允许处理代码数据。6. 实战问题与调试排查6.1 常见报错与解决方案我用 opencode 过程中遇到过不少问题挑几个典型整理成下表现象原因解决方案报错error from provider (console): opencodes free tier can only be used from within opencode使用了 opencode 内置免费通道但被外部工具调用在 opencode 界面内使用免费模型或改用自己配的 API Key / 本地模型报错unable to locate the codex CLI binaryopencode 某些功能依赖 codex CLI比如调用 codex 专属模型但环境里没装安装 codex CLI如果你明确不用 codex 模型检查配置里是否误引用了相关 provideropencode命令找不到安装后 PATH 未更新或安装目录不在 shell 的 PATH 里重开终端或手动执行export PATH$HOME/.opencode/bin:$PATH并写入 shell 配置从 cursor 或 VS Code 扩展市场搜不到 opencode 插件插件发布名和工具名不一致或者当前扩展市场源不同在扩展市场搜索opencode的具体扩展 ID或从 opencode 官网的安装页直接安装归档的会话在界面里消失了归档操作默认从主列表隐藏到存储目录的 archive 文件夹下查看 JSON 文件或从文件系统中找回Windows 原生终端下界面渲染错乱TUI 对 Windows 终端兼容性不佳使用 WSL2 运行 opencode或在 Windows Terminal 里配置 UTF-8 和虚拟终端序列支持context 过长导致回答质量下降单个会话塞入了过多内容使用/compact压缩上下文或开新会话用注入必要文件6.2 排查通用方法论遇到 opencode 相关的问题我的排查顺序一般是这样第一步看报错信息本身。opencode 的报错大多数情况下写得很直白比如 free tier can only be used from within opencode直接就是告诉你使用场景不对。不要急着改配置先理解它到底在抱怨什么。第二步看 provider 配置。如果你用了自定义 baseURL、自定义 provider优先检查 JSON 格式是否正确、字段名是否写对。最常见的错误是baseURL忘记加/v1后缀导致请求 404。第三步开启调试日志。opencode 支持调试模式可以用以下方式启动opencode --print-logs或者设置环境变量OPENCODE_LOG_LEVELdebug。日志会打出每个请求的细节包括请求了哪个 URL、返回了什么状态码。看到 401 就是 API Key 问题看到 404 就是 baseURL 问题看到 429 就是速率限制基本能定位 90% 的问题。第四步检查版本。opencode 迭代很快有些 bug 在新版本里已经修了遇到问题先升级到最新版再排查。升级命令看你的安装方式brew 装的就brew upgrade opencodenpm 装的就npm update -g opencode-ai。6.3 我的日常调试小脚本最后分享一个我日常排查 opencode 问题时用的小脚本用 shell 快速查看当前配置和服务连通性#!/bin/bash echo ---- opencode version ---- opencode --version echo ---- config file ---- cat ~/.config/opencode/config.json 2/dev/null || echo no global config echo ---- env keys ---- for key in ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY GOOGLE_API_KEY; do if [ -n ${!key} ]; then echo $key is set else echo $key is NOT set fi done echo ---- ollama ---- curl -s http://localhost:11434/api/tags | head -c 200 || echo ollama not reachable这个脚本不打印 API Key 本身只显示是否设置避免在共享屏幕上泄露敏感信息。我通常在遇到某个模型突然报错时先跑一遍快速确认是不是环境变量被别的工具覆盖了、Ollama 服务有没有挂这种低级问题。写在最后opencode 这套 CLI 交互方式本质上是在终端 AI 助手这个方向上做得很克制的产品它没有强行造一个复杂的 GUI而是把重点放在多模型接入、会话持久化、技能扩展、本地数据这些对开发者真正重要的能力上。我用了几个月下来最大的感受是如果你愿意花一周时间把斜杠命令、TAB 补全、plan/build 切换这些交互习惯练熟工作效率的提升是实打实的。尤其是 plan 模式和 TAB 补全这两个功能前者帮我避免了大量无效代码修改后者让日常对话变得异常顺手。如果你刚开始接触 opencode我建议先别急着配一堆模型和技能就用默认配置认真用三天把这几个核心交互玩透再逐步加上多模型、skills 这些进阶能力体验会顺畅很多。