1. 为什么我要在本地跑一个 AI Coding Agent
OpenCode 是一个开源的 AI Coding Agent，能读懂项目结构、执行命令、改文件、跑测试，适合想在终端里自建编程代理的开发者。它最吸引我的地方不是“又一个 AI 写代码工具”，而是 Plan/Build 双模式加供应商中立这两件事——前者把“想清楚”和“动手改”拆成两个阶段，后者让你随时换模型而不被某一家绑死。
我最初是在一个 3 万行的 TypeScript 老项目里试它的。当时的需求很朴素：让 AI 帮我把一批散落的any类型收敛掉，同时别把现有测试搞崩。用闭源 IDE 插件的体验是，它改得很快，但改完你不敢直接信，得一行行 review，最后发现它顺手重构了两个不相关的模块。OpenCode 的 Plan 模式正好治这个毛病：先只读分析，把要改哪些文件、每个文件改什么、有什么风险列出来，你确认了再切 Build 动手。
供应商中立则是另一个刚需。团队里有人用 Claude，有人用 GPT，本地还有一台跑 Ollama 的机器。OpenCode 通过统一的 provider 配置层把这些都抽象掉，你写一份配置，换模型只改一个字段。这对想自建 Agent 的开发者来说，意味着不用把架构和某家 API 的 SDK 深度耦合。
这篇文章我会按“装好 → 接模型 → 切模式 → 验证 → 排错”的顺序走一遍，配置片段都可以直接复制。模型接入部分我用 TaoToken 做统一入口来演示，因为它兼容 OpenAI 风格的接口，配置起来和接官方 API 没区别，但省去了维护多个 key 的麻烦。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。
先说清楚适合谁：如果你习惯终端、想让 AI 直接操作文件系统和 shell、又不想被单一模型供应商锁死，那 OpenCode 值得花半小时搭起来。如果你只想在 IDE 里要个补全，那它可能偏重了。
2. 前置准备：装 OpenCode 并理解它的配置分层
在写任何配置之前，先把 OpenCode 装起来，并搞清楚它的配置文件放在哪、优先级怎么排。这一步不做扎实，后面接模型时会出现“我明明改了配置却不生效”的经典问题。
安装方式取决于你的系统。macOS 和 Linux 上最省事的是官方安装脚本，Windows 建议走 WSL2，因为 OpenCode 的 TUI 和 shell 工具链在类 Unix 环境下最顺。我用的是 macOS，命令如下：
curl -fsSL https://opencode.ai/install | bash装完验证一下版本，确认二进制在 PATH 里：
opencode --version which opencode如果which找不到，多半是安装脚本把二进制放到了~/.opencode/bin之类的位置，手动加进 PATH 即可。Windows 用户在 WSL2 里跑同样的命令，注意别在 PowerShell 里直接装，TUI 的按键处理会出问题。
接下来是配置分层，这是 OpenCode 设计里很关键的一点。它支持多个层级的配置，优先级从低到高大致是：全局配置（用户级）→ 项目级配置 → 环境变量覆盖。全局配置放在用户主目录下，项目级配置放在项目根目录，通常命名为opencode.json或opencode.jsonc。项目级配置会覆盖全局里同名的字段，这样你可以给不同项目配不同的模型和权限。
我建议的实践是：全局配置里放你的默认 provider 和 key 引用，项目配置里只放这个项目特有的东西，比如禁用某个工具、指定本地模型。这样换项目时不用重复写一堆 provider 定义。
还有一个概念要提前建立：OpenCode 的 provider 配置和 model 配置是分开的。provider 描述“怎么连”（base URL、认证方式），model 描述“用哪个”（模型 ID、上下文窗口、成本）。很多人第一次配错就是把模型 ID 写进了 provider 段，或者反过来。记住这个区分，后面看配置就清楚了。
权限方面，OpenCode 默认对破坏性操作（删文件、改系统配置）会要求确认，这个行为可以在配置里调整，但我不建议一上来就全放开。先按默认跑通，再根据信任程度逐步放宽。
最后确认一下运行时依赖。OpenCode 的后端跑在 Bun 上，安装脚本一般会带上，但如果你的环境里 Bun 版本太老，可能出现启动即崩。用bun --version检查一下，太老就单独升级。LSP 相关功能需要你项目里本来就有对应的语言服务器，比如 TypeScript 项目要有tsserver，这个通常随项目依赖装好了，不用额外操心。
3. 可复制配置：用 TaoToken 统一接入多模型
这一节是全文的核心，我给你一份可以直接抄的配置，把 TaoToken 作为统一入口接进 OpenCode，同时演示怎么在 Plan 和 Build 两种模式下用不同模型。配置写对了，后面切换模型就是改一个字符串的事。
先解释思路。TaoToken 提供 OpenAI 兼容的接口，所以 OpenCode 里可以把它当成一个 OpenAI 风格的 provider 来配。base URL 用 https://taotoken.net/api ，认证走 Bearer token。你需要在 TaoToken 控制台生成一个 API Key，然后通过环境变量注入，别把 key 硬编码进配置文件——这是基本安全习惯。
先设环境变量，写进你的 shell 配置（~/.zshrc或~/.bashrc）：
export TAOTOKEN_API_KEY="sk-你的key"然后写全局配置。路径是~/.config/opencode/opencode.json，内容如下：
{ "$schema": "https://opencode.ai/config.json", "provider": { "taotoken": { "npm": "@ai-sdk/openai-compatible", "name": "TaoToken", "options": { "baseURL": "https://taotoken.net/api", "apiKey": "{env:TAOTOKEN_API_KEY}" }, "models": { "claude-sonnet-4-5": { "name": "Claude Sonnet 4.5" }, "gpt-5.2": { "name": "GPT 5.2" }, "glm-4.7": { "name": "GLM 4.7" } } } }, "model": "taotoken/claude-sonnet-4-5" }这里有几个点要讲清楚。npm字段指定用哪个 AI SDK 适配器，OpenAI 兼容的接口统一用@ai-sdk/openai-compatible。options.baseURL就是 TaoToken 的 API 地址，注意不要带 UTM 参数，接口地址保持干净。apiKey用{env:TAOTOKEN_API_KEY}的语法引用环境变量，OpenCode 会在启动时解析。models段里列出的模型 ID 要和你实际能调用的模型对上，写错了会在请求时报模型不存在。
model字段是默认模型，格式是provider/model。我默认用 Claude Sonnet 4.5，因为它在代码修改任务上比较稳。如果你想默认用便宜点的，把这里改成taotoken/glm-4.7就行。
接下来是项目级配置，演示 Plan/Build 双模式用不同模型。在项目根目录建opencode.json：
{ "$schema": "https://opencode.ai/config.json", "model": "taotoken/claude-sonnet-4-5", "agent": { "plan": { "model": "taotoken/gpt-5.2", "tools": { "write": false, "edit": false, "bash": false } }, "build": { "model": "taotoken/claude-sonnet-4-5", "tools": { "write": true, "edit": true, "bash": true } } } }这段配置的意图很明确：Plan 模式用 GPT 5.2 做分析，并且把写文件、编辑、执行 bash 三个工具全关掉，从机制上保证它只能读不能改；Build 模式用 Claude Sonnet 4.5，工具全开。这样你在 Plan 阶段拿到的是一份纯分析报告，不用担心它偷偷动你的代码。
如果你本地有 Ollama，想加一个完全离线的选项，可以在 provider 里再加一段：
{ "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama (local)", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "qwen2.5-coder:7b": { "name": "Qwen2.5 Coder 7B" } } } } }这样你就有了三套模型来源：TaoToken 上的云端模型、本地 Ollama 模型，切换时只改model字段。这就是供应商中立的实际价值——架构不变，模型可换。
配置写完，用opencode启动，在 TUI 里输入/models应该能看到你配的所有模型，输入/connect可以管理 provider 认证。如果列表里没有你配的模型，八成是 JSON 语法错了或者路径不对，下一节讲怎么验证。
4. 验证请求：从启动到一次完整的 Plan/Build 切换
配置写完不代表能用，得实际发一次请求验证链路通不通。这一节我带你走一遍完整流程：启动、确认模型、跑一次 Plan、切 Build、看结果。
启动 OpenCode，在项目根目录执行：
opencodeTUI 起来后，先别急着发提示，用/models命令确认模型列表。你应该能看到taotoken/claude-sonnet-4-5、taotoken/gpt-5.2、taotoken/glm-4.7这些条目。如果只看到默认模型没有你配的，检查全局配置路径是否正确——macOS 和 Linux 是~/.config/opencode/opencode.json，有些版本会读~/.opencode.json，以你版本的实际文档为准。
确认模型后，先测一次最简单的请求，验证 TaoToken 的连通性。在 TUI 里输入：
请用一句话说明这个项目是做什么的，不要读任何文件。如果模型正常返回，说明 provider 配置、base URL、API key 三件套都对。如果这里就报错，直接跳到第 5 节排错，别往下走。
连通性没问题后，测 Plan 模式。按 Tab 键切换到 Plan，或者用命令显式指定。Plan 模式下我让它分析一个真实任务：
分析 src/utils 目录下的类型定义，列出所有使用了 any 的地方，给出收敛方案，不要修改任何文件。观察它的行为：它应该只调用读文件、搜索类工具，不会触发写操作。如果配置里write、edit、bash都设成了 false，它即使想改也会被拦下来。这一步的输出应该是一份清单，包含文件路径、行号、建议的类型。这就是 Plan 模式的价值——先看清楚再动手。
确认方案合理后，按 Tab 切到 Build 模式，发一条执行指令：
按照刚才的方案，逐个文件收敛 any 类型，每改完一个文件运行一次相关测试。Build 模式下它会真正调用编辑工具改文件，并执行测试命令。你会在 TUI 里看到实时的文件变更 diff 和命令输出。如果测试挂了，它会读到错误信息并尝试修正，这就是 LSP 加工具闭环在起作用。
验证成功的标志有三个：一是 Plan 阶段确实没有文件被修改（可以用git status确认）；二是 Build 阶段有真实的 diff 产生；三是测试命令的输出被正确读取并反馈。三个都满足，说明你的 Plan/Build 双模式配置是生效的。
再补一个多模型切换的验证。把项目配置里的model临时改成taotoken/glm-4.7，重启 OpenCode，发同样的提示，对比一下输出风格和速度。GLM 4.7 在 TaoToken 上有免费额度，适合做这种对比测试。这一步能让你直观感受到供应商中立的好处——同一个工作流，底层模型随便换。
如果你还想验证本地模型，把model改成ollama/qwen2.5-coder:7b，前提是 Ollama 在跑且模型已 pull 下来。本地模型响应会慢一些，但完全离线，适合敏感代码。
5. 常见报错排查：401、模型不存在、工具被拒
配置和验证过程中最容易踩的坑就那么几个，我把真实遇到过的报错和对应解法列出来，你对着改就行。
401 Unauthorized 或 invalid api key。这是最高频的。原因通常是环境变量没生效。OpenCode 启动时读取TAOTOKEN_API_KEY，如果你是在配置写完之后才export的，当前 shell 会话可能没继承。解决方法是确认echo $TAOTOKEN_API_KEY有输出，没有就重新 source 一下 shell 配置，或者干脆重开终端。另一个可能是 key 本身失效或额度用尽，去 TaoToken 控制台确认一下 key 状态。还有一种情况是配置里写成了{env:TAOTOKEN_API_KEY}但变量名拼错，仔细核对。
model not found 或 404。说明你配置里的模型 ID 和实际可调用的对不上。OpenCode 报这个错时会把请求的模型 ID 打出来，拿这个 ID 去 TaoToken 的模型列表里核对。常见错误是把展示名当成了 ID，比如配置里写"Claude Sonnet 4.5"而不是"claude-sonnet-4-5"。模型 ID 是接口层用的标识，展示名只是给你看的。
local proxy failed 或 connection refused。这个一般出现在配本地模型时，比如 Ollama 没启动，或者 base URL 端口写错。Ollama 默认端口是 11434，路径是/v1。先用curl http://localhost:11434/v1/models确认服务活着，再检查 OpenCode 配置里的 baseURL。如果你用了某种本地转发工具，确认它监听的端口和配置一致。
reading 'choices' of undefined。这个报错通常意味着返回体结构不符合 OpenAI 兼容格式，OpenCode 解析响应时拿不到choices字段。原因可能是 base URL 指向了一个非兼容端点，或者中间有东西改写了响应。确认 base URL 是 https://taotoken.net/api 这个根路径，不要多加/chat/completions之类的后缀，OpenCode 会自己拼。
工具被拒绝执行 / tool not permitted。如果你在 Plan 模式下让它改文件，它会拒绝，这是设计行为不是 bug。检查项目配置里agent.plan.tools的开关。反过来，如果 Build 模式下工具也用不了，检查是不是全局配置里把工具禁用了，项目配置没覆盖到。
OAuth 或认证跳转失败。如果你用的是需要 OAuth 的 provider（比如某些 GitHub 集成），/connect流程可能因为网络或回调地址问题卡住。这种情况先确认你的网络能正常访问认证端点，然后重试/connect。如果反复失败，改用 API key 方式接入，绕开 OAuth。
配置改了不生效。OpenCode 有些配置是启动时读取的，改完要重启进程。另外确认你改的是正确的层级——项目配置覆盖全局配置，如果你在全局改了但项目里有同名配置，项目配置会赢。用/models和/connect在 TUI 里实时确认当前生效的配置。
排错的核心思路是分层定位：先确认网络和 key（能不能连上），再确认模型 ID（连上后认不认），最后确认工具权限（认了之后让不让干）。按这个顺序查，基本不会绕弯路。
6. 把 OpenCode 接进你的日常工作流
跑通之后，真正决定效率的是你怎么用它。我分享几个实测下来比较顺的用法。
Plan 模式不要只用来“看看”，把它当成写方案的工具。我现在的习惯是，接到一个不熟的任务，先在 Plan 模式下让 AI 输出一份带文件路径和风险点的实施计划，我把这份计划当草稿改一改，再切 Build 执行。这样 AI 的产出有了人的判断兜底，返工率明显下降。
模型分层用起来。简单任务用便宜或免费的模型，比如 GLM 4.7；复杂重构和架构决策用 Claude Sonnet 4.5 或 GPT 5.2。在项目配置里给 Plan 和 Build 配不同模型，就是把这个策略固化下来。TaoToken 这种统一入口的好处是，你换模型不用改代码，只改配置里的一个字符串。
本地模型留给敏感场景。涉及未公开的业务逻辑或客户数据时，切到 Ollama 上的本地模型，整个链路不出机器。虽然能力弱一些，但合规上踏实。
最后，把 OpenCode 的配置纳入版本管理。项目级的opencode.json提交到仓库，团队共享同一套模型和权限策略；个人的 key 走环境变量，不进仓库。这样新人 clone 下来，设个环境变量就能用，省去口口相传的配置说明。
如果你还没生成 API Key，去 TaoToken 控制台建一个，接入文档在 https://taotoken.net/api-keys 和 https://taotoken.net/doc 可以对照着看。想先试试模型对话效果，https://taotoken.net/model-chat 能直接体验。长期跑编码任务或搭 Agent 的话，Coding Plan 在 https://taotoken.net/coding-plan 有更划算的额度方案。配置过程中卡住了，回头对照第 5 节的报错清单，基本都能定位到。
