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不要加/v1SDK 内部会拼。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.jsimport { 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(cconsole.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.csvdate,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] toolfile-read input{path:./data/sales.csv} output{rows:3} [debug] toolshell 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 误删数据的案例。先只读再只写特定目录最后才考虑全量权限。这个顺序不能反。