1. 先搞懂 OpenCode SDK 到底在解决什么问题
你可能已经用过 ChatGPT、Claude 或者本地跑过 Llama，聊天确实流畅。但真要让 AI 帮你查一次数据库、跑一条 Shell 命令、调一次内部 API，你会发现光有模型根本不够——模型只会输出文字，它没有“手”。
OpenCode SDK 就是给模型装“手”的那层运行时框架。你可以把它理解成 AI Agent 的操作系统：模型负责思考，SDK 负责调度工具、管理权限、记录日志、处理失败重试。没有它，你得自己写一堆胶水代码去解析模型输出、校验参数、拼接请求；有了它，这些脏活累活都被封装成标准接口。
它适合谁？三类人最该关注：一是想给公司内部系统加 AI 能力的后端开发者，二是做智能体应用但不想重复造轮子的独立开发者，三是刚接触 Agent 概念、想找一个能跑起来的最小示例来建立认知的零基础同学。这篇就按“先跑通、再理解、后排查”的顺序来，每一步都给可复制的配置和命令。
核心检索词先记住三个：OpenCode SDK 是运行时框架，AI Agent 是它调度的对象，工具调用链路是它最核心的能力。下面从环境准备开始，一步步把 Agent 启动起来。
2. TaoToken 前置准备：拿到模型接入的三件套
OpenCode SDK 本身不绑定任何模型厂商，它通过标准接口去调用大模型。所以你需要先有一个能用的模型接入点。这里我用 TaoToken 来做演示，因为它同时支持对话模型和编码类模型，配置方式统一，适合作为 Agent 运行时的后端。
先明确三件套：Base URL、API Key、Model ID。这三样缺一不可，后面所有配置文件都围绕它们展开。
Base URL 填https://taotoken.net/api，注意不要带多余路径。API Key 去控制台创建，路径是 console。创建时给它起个能认出来的名字，比如opencode-agent-dev，方便后面区分环境。Model ID 根据你要跑的任务选：做对话和工具调度用通用对话模型，做代码生成和 Agent 长任务用编码类模型。
如果你还没决定用哪个模型，可以先到 模型对话 页面手动试几句，确认响应正常再写进配置。这一步别跳过，很多人后面报 401 就是因为 Key 复制时带了空格，或者 Base URL 写成了带/v1的旧格式。
注意：API Key 只显示一次，创建后立刻复制到安全的地方。不要提交到 Git 仓库，建议用环境变量注入。
拿到三件套后，先做一次最简验证，确认网络和鉴权没问题。用 curl 发一条最小请求：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "你的Model ID", "messages": [{"role": "user", "content": "回复ok"}] }'如果返回里能看到choices字段和正常内容，说明前置准备完成。如果报 401，先检查 Key；如果报连接失败，检查 Base URL 是否写成了https://taotoken.net/api而不是别的路径。这一步过了，再进 OpenCode SDK 的配置。
3. 可复制配置：OpenCode SDK 初始化与 Agent 注册
OpenCode SDK 的配置分两层：一层是运行时配置，告诉 SDK 用哪个模型、日志写哪里；另一层是 Agent 定义，告诉它有哪些工具可用、权限边界在哪。下面给一份可以直接复制的最小配置。
先建项目目录并初始化：
mkdir opencode-agent-demo && cd opencode-agent-demo npm init -y npm install @opencode-ai/sdk然后创建opencode.config.json，这是运行时配置：
{ "runtime": { "name": "demo-agent-runtime", "logLevel": "debug", "logFile": "./logs/agent.log" }, "model": { "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "modelId": "你的Model ID", "timeoutMs": 60000 }, "tools": { "allow": ["shell", "http", "file-read"], "deny": ["file-write", "db-write"] } }这里几个关键点解释一下。baseUrl固定用https://taotoken.net/api，不要加/v1，SDK 内部会拼。apiKey用${TAOTOKEN_API_KEY}占位，运行时从环境变量读，避免硬编码。tools.allow是白名单，只放你确认安全的工具；tools.deny优先级更高，用来兜底禁止危险操作。日志级别先开debug，方便看工具调用链路。
接着创建 Agent 定义文件agent.json：
{ "agentId": "sales-report-agent", "description": "生成销售报表的示例 Agent", "systemPrompt": "你是一个销售报表助手，只能读取数据并生成汇总，不能修改任何数据。", "tools": ["shell", "http"], "maxSteps": 8, "retry": { "maxAttempts": 3, "backoffMs": 500 } }maxSteps控制 Agent 最多执行多少轮工具调用，防止死循环。retry是失败重试策略，工具调用失败会自动重试三次，每次间隔递增。这两个参数在企业场景里很重要，后面排障会用到。
最后写入口文件index.js：
import { OpenCodeSDK } from '@opencode-ai/sdk'; import config from './opencode.config.json' assert { type: 'json' }; import agentDef from './agent.json' assert { type: 'json' }; const sdk = new OpenCodeSDK({ ...config, apiKey: process.env.TAOTOKEN_API_KEY }); const agent = await sdk.registerAgent(agentDef); const result = await agent.run({ input: '读取 ./data/sales.csv，汇总本月销售额，输出一行结论' }); console.log('Agent 输出:', result.output); console.log('执行步骤:', result.steps.length);运行前设置环境变量：
export TAOTOKEN_API_KEY="你的Key" node index.js这份配置里，Base URL、Key、Model ID 三件套齐全，工具白名单和重试策略也给了。你可以先原样跑，再按需改tools.allow和systemPrompt。
4. 验证请求：Agent 启动、任务执行与日志输出
配置写完后，按下面清单逐步验证，每一步都有明确的成功标志。
第一步，验证 SDK 能加载配置。运行node -e "import('./opencode.config.json', {assert:{type:'json'}}).then(c=>console.log(c.model.baseUrl))"，输出应该是https://taotoken.net/api。如果报模块错误，检查 Node 版本是否支持 JSON import，建议 18 以上。
第二步，验证 Agent 注册成功。在index.js里registerAgent后面加一行console.log('Agent 已注册:', agent.id)，运行后应看到Agent 已注册: sales-report-agent。如果报agentId重复，说明之前注册过，换个 ID 或清理运行时状态。
第三步，验证任务执行。准备一个data/sales.csv：
date,amount 2024-01-01,1200 2024-01-02,800 2024-01-03,1500运行node index.js，正常输出类似：
Agent 输出: 本月销售额合计 3500 执行步骤: 3执行步骤: 3说明 Agent 走了三轮：读文件、计算、生成结论。如果步骤数是 0，说明模型没触发工具调用，检查systemPrompt是否明确要求使用工具。
第四步，验证日志。打开logs/agent.log，应该能看到每次工具调用的入参和出参，格式类似：
[debug] tool=file-read input={"path":"./data/sales.csv"} output={"rows":3} [debug] tool=shell input={"cmd":"awk ..."} output={"sum":3500}日志是排查问题的核心依据。如果日志里只有模型请求没有工具调用，说明工具注册没生效；如果工具调用报错，日志里会有具体错误码。
第五步，验证重试机制。故意把data/sales.csv改名，再运行，观察日志里是否出现三次重试记录，最后 Agent 是否给出友好错误提示。这一步能确认retry配置生效。
走完这五步，你对 OpenCode SDK 的运行时、Agent 调度、工具调用链路就有了完整认知。接下来看常见报错。
5. 本篇常见错排查：401、local proxy failed、reading choices
实际跑的时候，报错集中在几个地方。下面按真实错误信息对照排查。
401 Unauthorized。最常见。原因有三个：Key 没设置、Key 带空格、Base URL 写错。先echo $TAOTOKEN_API_KEY确认环境变量有值且无空格。再检查opencode.config.json里baseUrl是不是https://taotoken.net/api，不要写成https://taotoken.net/api/v1或带尾斜杠。如果用的是配置文件里的${TAOTOKEN_API_KEY}，确认 SDK 版本支持环境变量插值，不支持就直接在代码里process.env.TAOTOKEN_API_KEY传入。
local proxy failed。这个报错通常出现在 SDK 尝试走本地代理但代理没启动。OpenCode SDK 默认不走代理，如果你环境里有HTTP_PROXY或HTTPS_PROXY变量，SDK 可能会误用。排查方法：env | grep -i proxy，如果有值，临时unset HTTP_PROXY HTTPS_PROXY再跑。另外确认baseUrl是直连地址，不要填任何本地转发端口。
reading 'choices'。这个报错说明 SDK 拿到了响应，但响应结构里没有choices字段。原因通常是模型返回了错误信息而不是正常补全。打开logs/agent.log，看原始响应体。常见情况是 Model ID 写错，或者该模型不支持当前调用方式。回到 模型对话 页面确认 Model ID 拼写，再检查请求体里messages格式是否正确。
OAuth 相关报错。如果你在配置里启用了需要 OAuth 的工具插件，但没配回调地址，会报 OAuth 失败。排查：检查agent.json里tools是否包含需要鉴权的插件，如果有，先在插件配置里补全clientId、clientSecret、redirectUri。不需要 OAuth 的工具先从白名单移除，跑通主流程再加回来。
Agent 不调用工具。日志里只有模型请求，没有tool=记录。原因通常是systemPrompt没明确要求用工具，或者tools.allow里没有模型想用的工具。改法：在systemPrompt里加一句“必须使用 shell 工具读取文件”，并确认tools.allow包含shell。
步骤数超限。报maxSteps exceeded。说明 Agent 在循环调用工具。检查systemPrompt是否给了明确终止条件，比如“汇总完成后直接输出结论，不要再调用工具”。同时把maxSteps从 8 调到 5 试试，逼它收敛。
排查顺序建议：先看日志级别是否debug，再看原始响应体，最后对照配置逐项检查三件套。大部分问题都在 Key、Base URL、Model ID 这三个点上。
6. 从最小示例到企业级 Agent：下一步怎么走
跑通最小示例后，你手里已经有一个能读文件、能执行命令、能输出结论的 Agent。接下来往企业级走，重点补三块。
第一块是工具生态。把内部 API、数据库查询、消息通知都封装成插件，注册到tools.allow里。每个插件单独写权限边界，比如数据库插件只给只读账号。OpenCode SDK 的插件机制支持独立配置，一个插件出问题不影响其他插件。
第二块是模型路由。不同任务用不同模型：简单汇总用轻量模型，复杂推理用强模型。在opencode.config.json里可以配多个模型，Agent 定义里指定用哪个。TaoToken 的 Coding Plan 适合长期跑编码类 Agent 任务，按量计费比单次调用更划算。
第三块是观测。把logFile接到集中日志系统，每次工具调用都打点。重点关注三个指标：工具调用成功率、平均步骤数、重试次数。这三个指标异常，说明 Agent 的提示词或工具定义需要调优。
如果你要接 Claude Code 这类编码 Agent，配置方式类似，把 Base URL 和 Key 填到对应配置文件里，Model ID 选编码类模型即可。具体接入文档在 接入文档 里有完整说明。API Key 管理在 API Keys 页面，建议给每个 Agent 单独建 Key，方便审计和吊销。
最后提醒一句：Agent 的权限白名单一定要从最小集合开始，跑通后再逐步放开。我见过太多因为一开始就给了写权限，结果 Agent 误删数据的案例。先只读，再只写特定目录，最后才考虑全量权限。这个顺序不能反。
