企业官网建设流程全解析

1. 为什么我建议你从 opencode.json 开始折腾

opencode 这个终端里的 AI 编码工具，最近在开发者圈子里讨论度不低。它跟很多同类工具最大的区别在于：配置是显式的、可版本化的，所有 Agent 行为都落在opencode.json这一个文件里。你可以把它理解成「给 AI 编码助手写一份岗位说明书」——provider 决定它去哪家模型服务商拿能力，model 决定用哪个具体模型，agent 段落则定义每个智能体的性格和职责边界。

但第一次配置的人往往会卡在同一个地方：provider 的 endpoint 和 Key 到底怎么填。官方文档里列了一堆服务商，每家字段名还不完全一样，填错一个字母就是 401。更麻烦的是，如果你同时用 Claude、GLM、Gemini 几个模型，就得维护多套 Key，切换一次改一次配置，时间全耗在复制粘贴上。

这篇要解决的问题很具体：把 opencode 的 provider endpoint 统一指向 TaoToken 的兼容通道，用一把 Key 打通opencode.json里的模型配置，再配合 skill-creator 定义可复用技能，最后跑通一个多 Agent 协作任务。适合谁？适合已经装好 opencode、想认真用起来而不是随便试试的开发者；也适合被多服务商 Key 管理折磨过、想收敛配置的人。

我试过把 plan 和 build 两个 Agent 分开配置不同模型，一个负责出方案、一个负责改代码，上下文互不污染，效果比单 Agent 硬扛好不少。下面从零开始，一步步把配置写出来。

2. 前置准备：TaoToken 通道与 opencode 安装检查

在动opencode.json之前，先把两件事确认掉：opencode 本体装好了，TaoToken 的 Key 拿到了。

opencode 的安装按官方文档走就行，下载链接在 opencode.ai 的 download 页面，各平台都有对应包。装完之后在终端敲opencode --version，能打印版本号就说明 PATH 没问题。如果你还想用 oh my opencode 这套增强配置，装完后用cat ~/.config/opencode/oh-my-opencode.json检查一下，文件存在且内容正常就代表安装完成。这个检查动作别省，后面 Agent 配置出问题时，第一步就是回来确认这个文件还在不在。

接着是 TaoToken 这边。打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 注册后进控制台，在 API Keys 页面创建一个新 Key。这里有个细节：Key 只在创建时完整显示一次，记得当场复制到密码管理器或者本地环境变量文件里，别关掉页面再回来找。创建完 Key 之后，你还需要确认要用的模型 ID，比如 Claude 系列、GLM 系列，模型列表在文档页能查到，记下准确的模型标识，后面填model字段要用。

TaoToken 的 API 基地址是https://taotoken.net/api，这个地址在配置里会作为 provider 的baseURL出现。注意它跟官网首页不是一回事，别把带 UTM 参数的推广链接填进配置文件，那样请求会失败。配置里只写纯 API 地址。

环境变量这块建议单独处理。把 Key 写进 shell 的配置文件里，比如~/.zshrc或~/.bashrc，加一行export TAOTOKEN_API_KEY="你的Key"，然后source一下。这样做的好处是opencode.json里可以用变量引用，Key 不会明文躺在项目仓库里被误提交。如果你团队多人协作，这一点尤其重要。

到这里前置就齐了：opencode 能跑、Key 在手、模型 ID 记下、API 地址明确。接下来进配置文件。

3. 可复制配置：opencode.json 的 provider 与 model 字段怎么写

opencode.json的位置分全局和项目级两种。全局配置在~/.config/opencode/opencode.json，对所有项目生效；项目级配置放在项目根目录，优先级更高。我建议先写全局的，把 provider 和默认模型定下来，项目里需要特殊模型时再覆盖。

先看 provider 段落。核心是把自定义 provider 的baseURL指向 TaoToken 的 API 地址，apiKey用环境变量引用。下面这段可以直接复制，把模型 ID 换成你实际要用的：

{ "$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-20250514": { "name": "Claude Sonnet 4" }, "glm-4.6": { "name": "GLM-4.6" } } } }, "model": "taotoken/claude-sonnet-4-20250514" }

几个字段逐个说清楚。npm指定用哪个 SDK 适配器，OpenAI 兼容协议的服务商统一用@ai-sdk/openai-compatible，TaoToken 的通道走这个没问题。baseURL就是前面说的 API 地址，结尾不要多加斜杠。apiKey里的{env:TAOTOKEN_API_KEY}是 opencode 的变量语法，运行时从环境变量读取，这样配置文件可以放心提交。models里列出你要用的模型，键名必须是服务商侧准确的模型 ID，显示名可以自己起。最外层的model是默认模型，格式是provider名/模型ID。

然后是 agent 段落。opencode 内置了 plan 和 build 两种模式，plan 先出方案再拆任务，build 直接写改代码。你可以给它们分别指定模型和温度：

{ "agent": { "plan": { "model": "taotoken/claude-sonnet-4-20250514", "temperature": 0.1, "description": "负责需求分析与任务拆解，只出方案不改代码" }, "build": { "model": "taotoken/glm-4.6", "temperature": 0.3, "description": "负责按方案落地代码，专注实现" }, "creative": { "temperature": 0.8, "description": "负责文案与创意类任务，允许发散" } } }

temperature的取值逻辑值得展开。数值越小，输出越确定、越专一，适合 plan 这种需要严谨拆解的场景；数值越大，发散性和创造性越强，适合创意类任务。plan 给 0.1、build 给 0.3、creative 给 0.8，是我实测下来比较稳的一组值。description不是装饰，它会影响 Agent 的行为倾向，写清楚职责边界能减少跑偏。

多 Agent 协作的价值在这里体现出来：每个 Agent 工作时上下文是独立的。plan 拆完任务，build 接手时不会背着 plan 阶段那一大堆分析过程，专注度更高。任务复杂时，这种上下文隔离比单 Agent 一路扛到底效果好得多。配置好之后，在对话里用@agent名就能指定某个 Agent 干活。

最后补一个 skill-creator 的安装。最常用的方式是从 GitHub 直接装：

npx skills add https://github.com/anthropics/skills --skill skill-creator

如果这条命令失败，别死磕，直接把 skill-creator 目录复制到~/.config/opencode/skills/下面，效果一样。装完在 skills 目录里能看到 skill-creator 文件夹就说明就位了。技能定义好之后，Agent 在遇到匹配任务时会自动调用，可复用性比每次手写提示词强。

4. 验证请求：跑通第一个 Agent 任务并确认返回

配置写完不等于通了，得实际发一次请求验证。分两步：先验证 provider 通道，再验证 Agent 调用。

第一步，在终端里直接测 API 通道。用 curl 发一个最小请求，确认 Key 和地址都对：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "回复两个字：通了"}] }'

返回体里choices[0].message.content有内容，就说明通道没问题。如果这里就报错，先别往下走，回到第 5 节对照排查。

第二步，进 opencode 验证 Agent。在项目目录下启动 opencode，先看它有没有正确加载配置。输入一个简单任务，比如让它读一下当前目录的文件结构并给出说明。观察两点：一是请求有没有正常发出，二是返回内容是不是来自你配置的模型。如果 opencode 界面里显示了模型名，确认是taotoken/前缀的那个，说明 provider 映射生效了。

第三步，验证多 Agent 切换。在对话里用@plan让它拆一个任务，比如「把这个项目的 README 补全，先出方案」。plan Agent 应该只给方案不动文件。然后@build接手，让它按方案改。两次调用的上下文是隔离的，build 不会带着 plan 的完整推理过程，这就是前面说的上下文独立优势。

第四步，验证 skill-creator。让它创建一个简单技能，比如「生成 commit message」的技能，观察它是否按 skill 的结构输出。技能文件落到 skills 目录后，下次遇到相关任务时 Agent 会自动匹配。

整个验证过程里，成功结果的标志很明确：curl 返回正常 JSON、opencode 里模型名正确、Agent 按@指定响应、技能文件生成到位。四步都过，配置就算跑通了。

5. 常见报错排查：401、local proxy failed 与 reading choices

配置阶段最容易撞的几类错误，我按出现频率排一下，对照着看。

401 Unauthorized。这是最高频的。原因通常有三个：Key 没读到、Key 写错、Key 失效。先确认环境变量在当前 shell 里真的存在，echo $TAOTOKEN_API_KEY看有没有输出。如果为空，说明source没生效或者写错了文件。如果变量有值但还报 401，检查opencode.json里apiKey的变量语法是不是{env:TAOTOKEN_API_KEY}，花括号和冒号都不能少。还有一种情况是 Key 复制时带了首尾空格，肉眼看不出来，重新复制一次。

local proxy failed 或连接类错误。这类报错说明请求根本没到达服务端。先确认baseURL写的是https://taotoken.net/api，没有多余路径、没有结尾斜杠、没有把官网推广链接填进去。再确认本机网络能正常访问这个地址，用 curl 测一下根路径。如果 curl 通但 opencode 不通，检查 opencode 版本是否过旧，老版本对自定义 provider 的支持有差异，升级到最新版再试。

reading 'choices' 相关报错。这个错误的本质是返回体结构跟预期不符，代码去读choices字段时读不到。常见原因是模型 ID 填错了——服务端不认识这个模型，返回的是错误对象而不是标准补全结构。回去核对models里的键名跟服务商文档里的模型 ID 是否完全一致，大小写、连字符都要对上。另一个原因是npm适配器选错了，OpenAI 兼容通道必须用@ai-sdk/openai-compatible，用错适配器解析逻辑就不一样。

OAuth 相关报错。如果你之前配过其他需要 OAuth 登录的服务商，残留的认证状态可能干扰。检查~/.config/opencode/下有没有旧的认证缓存文件，清理掉再重启。自定义 provider 走的是 API Key 认证，不需要 OAuth 流程，两者混在一起容易出问题。

Agent 不响应@指定。先确认 agent 名拼写跟配置里一致，@plan对应配置里的plan键。再确认配置文件的层级没写错，agent是顶层字段，不要嵌到provider里面去。改完配置记得重启 opencode，配置是启动时加载的。

排查的通用思路是分层：先 curl 测通道，再测 opencode 加载，最后测 Agent 行为。哪一层断了就修哪一层，别一上来就改配置，容易越改越乱。

6. 把配置沉淀下来：后续接入与长期使用建议

配置跑通之后，建议做两件事让这套东西长期可用。

第一件，把opencode.json纳入版本管理。因为 Key 走的是环境变量引用，配置文件本身不含敏感信息，可以放心提交到仓库。团队里其他人拉下来，只需要自己配一下TAOTOKEN_API_KEY环境变量就能用同一套 Agent 定义。这比每个人各自维护一份配置要省心得多，Agent 的description和temperature也能统一，团队输出风格更一致。

第二件，把常用技能沉淀到 skills 目录。skill-creator 装好之后，遇到重复性任务就让它生成技能文件，比如代码审查清单、commit 规范、文档模板。技能积累多了，Agent 的自动化程度会明显提升。技能文件同样可以进版本库，跟配置一起管理。

如果你后续要长期跑编码任务或者搭多 Agent 工作流，可以关注 Coding Plan 这类方案，把调用额度规划好，避免高峰期临时抓瞎。模型能力验证阶段，直接用模型对话页面测一下不同模型的返回质量，确认哪个模型适合你的任务类型，再写进opencode.json的models列表。

接入文档在 https://taotoken.net/api 对应的文档页能查到，字段说明和模型列表都在那里。Key 管理在控制台的 API Keys 页面，建议定期轮换。这套配置的核心思路就一句话：endpoint 和 Key 收敛到一处，Agent 定义显式化，技能可复用。把这三件事做好，opencode 才算真正用起来了。