企业官网建设流程全解析

1. 为什么 opencode 的配置文件值得单独写一篇

opencode 这个终端里的 AI 编码工具，第一次上手最容易卡住的地方不是安装，而是配置文件。它同时支持 JSON 和 JSONC（带注释的 JSON）两种格式，官方文档里两种写法混着出现，新手很容易把注释写进.json文件里然后被解析器直接报错。我实测下来，最省心的做法是：统一用opencode.jsonc，需要注释就写注释，不需要注释也不影响，省得在两种格式之间来回切换。

这篇要解决的问题很具体：你装好 opencode 之后，怎么用一份 JSONC 配置文件把 provider、model、agent 三件事一次配好，并且把请求统一走 TaoToken 的 API 通道，用一个 Key 管住所有模型调用。适合已经装过 opencode、但还没跑通自定义 provider 的人，也适合想把项目级配置和全局配置理清楚的人。

核心检索词先摆出来：opencode 配置文件怎么写、opencode JSONC 和 JSON 的区别、opencode agent 怎么定义、opencode 接入自定义 baseURL。这几个问题在下面都会落到可复制的片段上。

先说清楚 opencode 的配置合并逻辑，这是后面所有操作的地基。opencode 的配置不是「后者替换前者」，而是多层合并：全局配置~/.config/opencode/opencode.json放你的通用偏好，项目里的opencode.json放这个项目特有的设置，.opencode/目录放 agent、command、plugin 这类扩展。合并的时候同名字段会叠加而不是覆盖，所以你在全局里定义了一个 provider，在项目里只补一个 model，两边都能生效。

这个机制的好处是：TaoToken 的 Key 和 baseURL 只需要在全局配一次，之后每个项目里只写自己关心的模型和 agent，不用重复粘贴密钥。坏处是：如果你在两层都写了同一个字段，得清楚哪层优先，不然会出现「我明明改了配置怎么没生效」的情况。我的习惯是——provider 和鉴权只放全局，model 和 agent 放项目级，职责分清，排查起来快。

再补一个容易忽略的点：opencode 的授权信息会单独存到~/.local/share/opencode/auth.json。也就是说，即使你在配置文件里写了apiKey，opencode 在/connect流程里也可能把授权结果写进这个 auth.json。两者不冲突，但排查 401 的时候要同时看这两个地方，别只盯着配置文件。

2. 用 TaoToken 统一 Key 做前置准备

在写配置之前，先把 TaoToken 这边的三样东西拿到手：Base URL、API Key、Model ID。这三件套是后面所有配置片段的原料，缺一个都跑不通。

Base URL 用https://taotoken.net/api，注意这里不带任何查询参数，就是干净的 API 根地址。API Key 去控制台生成，路径是 API Keys 页面，生成后复制出来，不要直接写进会提交到 git 的配置文件，后面我会用环境变量引用的方式处理。Model ID 就是你要调用的模型标识，比如claude-sonnet-4-5、deepseek-chat这类，具体以你账号下可用的为准。

如果你还没生成 Key，可以走这个入口：API Keys 页面在https://taotoken.net/api-keys，登录后新建一个即可。想先看看有哪些模型可用，模型对话页面https://taotoken.net/models能直接试，确认模型 ID 拼写对不对，省得配置里写错了再回头查。

这里要强调一个原则：Key 走环境变量，不进配置文件明文。opencode 支持{env:VAR_NAME}这种引用语法，配置文件里只写变量名，真实值放在 shell 的环境变量里。这样你的opencode.jsonc可以放心提交到项目仓库，不会泄露密钥。设置环境变量的方式看你用的 shell，bash/zsh 一般是写进~/.zshrc或~/.bashrc：

export TAOTOKEN_API_KEY="sk-你的真实key"

改完记得source ~/.zshrc或者重开终端，让变量生效。验证一下：

echo $TAOTOKEN_API_KEY

能打印出你的 Key 就说明环境变量到位了。这一步没做的话，后面配置里引用{env:TAOTOKEN_API_KEY}会拿到空值，请求直接 401。

关于 provider 的 npm 包，opencode 走的是 AI SDK 的兼容层，自定义 provider 用@ai-sdk/openai-compatible这个包就行，它负责把 OpenAI 格式的请求转发到你的 baseURL。TaoToken 的 API 是 OpenAI 兼容的，所以这个包能直接用，不需要额外装别的适配器。

3. 可复制的 opencode.jsonc 配置片段

现在进入正题，把配置写出来。先建全局配置文件，路径是~/.config/opencode/opencode.jsonc。注意扩展名用.jsonc，这样你可以写注释：

mkdir -p ~/.config/opencode vim ~/.config/opencode/opencode.jsonc

内容如下，这段可以直接复制，把模型列表按你实际可用的调整：

{ "$schema": "https://opencode.ai/config.json", "provider": { "taotoken": { // provider 的唯一 id，后面 /connect 和选模型会用到 "npm": "@ai-sdk/openai-compatible", "name": "TaoToken", "options": { "baseURL": "https://taotoken.net/api", // 用环境变量引用，避免明文写 Key "apiKey": "{env:TAOTOKEN_API_KEY}" }, "models": { "claude-sonnet-4-5": { "name": "Claude Sonnet 4.5" }, "claude-haiku-4-5": { "name": "Claude Haiku 4.5" }, "deepseek-chat": { "name": "DeepSeek V3" } } } }, // 默认模型，格式是 provider/model "model": "taotoken/claude-sonnet-4-5", // 轻量任务单独走小模型，省钱 "small_model": "taotoken/claude-haiku-4-5" }

几个关键点解释一下。provider下的taotoken是自定义 id，你可以改成别的英文名，但一旦定了，后面model字段里的前缀就得跟它一致。options.baseURL填 TaoToken 的 API 根地址，options.apiKey用{env:TAOTOKEN_API_KEY}引用环境变量。models里列出的模型才会出现在/models选择列表里，不列出来的模型即使 API 支持也选不到，这是新手最容易踩的坑。

然后是项目级配置。在项目根目录建opencode.json，只放这个项目特有的东西，比如 agent 定义：

{ "$schema": "https://opencode.ai/config.json", "agent": { "reviewer": { "model": "taotoken/claude-sonnet-4-5", "prompt": "你是一个严格的代码审查者，只关注逻辑错误和边界条件，不评论代码风格。", "tools": { "write": false, "edit": false } }, "docwriter": { "model": "taotoken/claude-haiku-4-5", "prompt": "你负责把代码变更整理成简洁的中文说明，面向非技术读者。" } } }

这里的agent是定义一个专用代理，不是切换代理。reviewer这个 agent 被限制了写和编辑工具，只能读和审查，适合做 code review 场景。docwriter用便宜的小模型跑文档生成，成本可控。每个 agent 可以单独指定 model，这就是前面说的「provider 全局配一次，agent 按需选模型」。

如果你更喜欢用 Markdown 文件定义 agent，也可以放到~/.config/opencode/agents/或项目里的.opencode/agents/目录，一个文件一个 agent，文件名就是 agent 名。两种方式效果一样，配置文件适合集中管理，Markdown 文件适合 agent 逻辑复杂、prompt 很长的情况。

4. 验证配置生效与请求返回

配置写完，先别急着进交互界面，用一条命令验证配置能不能被正确解析、请求能不能通。opencode 提供了非交互的执行方式，可以直接跑一个 prompt：

opencode run "用一句话说明什么是 JSONC" --model taotoken/claude-haiku-4-5

如果配置没问题，你会看到模型返回的一句话解释。这条命令同时验证了三件事：配置文件被正确加载、provider 的 baseURL 和 Key 有效、指定的 model 能调通。任何一环出问题都会在这里报错，比进 TUI 之后再排查快得多。

想确认配置的合并结果，可以用：

opencode config

它会打印出当前生效的完整配置，你能看到全局和项目级合并后的样子。如果taotokenprovider 没出现在输出里，说明配置文件路径写错了或者 JSONC 语法有误。

进入交互界面后，用/models命令查看可选模型列表，应该能看到taotoken/claude-sonnet-4-5这些。用/connect命令时，在 other 选项里应该能找到你自定义的taotokenprovider。如果/connect里找不到，八成是 provider 的 id 拼写和配置文件里不一致。

再验证一下 agent 是否生效。在项目目录下启动 opencode，用 Tab 键切换到计划模式，然后试试调用你定义的 agent。agent 生效的标志是它的 prompt 和工具限制被应用，比如reviewer不会去改文件。

授权信息会保存在~/.local/share/opencode/auth.json，如果你在/connect流程里重新授权过，可以打开这个文件确认 provider 和 Key 的记录。注意这个文件里存的是授权结果，和配置文件里的{env:...}引用是两套机制，排查鉴权问题时两个都要看。

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

配置跑不通的时候，报错信息往往很简短，下面按真实遇到的几类来拆。

401 Unauthorized：最常见。先确认环境变量有没有生效，echo $TAOTOKEN_API_KEY能不能打印出值。如果打印为空，说明 shell 没加载到，检查是不是写进了错误的 rc 文件，或者忘了 source。如果环境变量正常，检查配置文件里apiKey字段是不是写成了{env:TAOTOKEN_API_KEY}，花括号和冒号都不能少。还有一种情况是 Key 本身失效或额度用完，去控制台 API Keys 页面确认一下状态。

local proxy failed / connection refused：这类报错通常指向 baseURL 写错或者网络层问题。确认baseURL是https://taotoken.net/api，不要多加/v1也不要少写协议头。如果你在配置文件里手滑写成了别的地址，opencode 会尝试连一个不存在的本地代理，报错就是 local proxy failed。改完配置记得重启 opencode，配置是启动时加载的。

reading choices / unexpected response：这个报错说明请求发出去了，但返回的 JSON 结构不符合 OpenAI 兼容格式的预期。常见原因是 model ID 写错了，请求打到了一个不存在的模型上，返回了错误结构。检查models里列出的 ID 和model字段引用的 ID 是否完全一致，大小写和连字符都要对上。另一个可能是 baseURL 指向了非 OpenAI 兼容的端点，确认你用的是 TaoToken 的 API 根地址。

OAuth / 授权相关报错：如果你在/connect里选了 OAuth 流程但 provider 是自定义的，可能会卡住。自定义 provider 走的是 API Key 鉴权，不需要 OAuth。遇到这类报错，回到配置文件确认apiKey字段存在且引用正确，然后在/connect的 other 里重新选一次你的 provider。

排查的通用顺序是：先echo环境变量，再opencode config看合并结果，然后opencode run跑一条最小请求，最后才进 TUI。这个顺序能把问题范围一步步缩小，比一上来就翻日志高效。

6. 把 Key 和配置管起来，长期用得更顺

配置跑通之后，有几件事值得顺手做掉，能省掉后面很多重复劳动。

第一，把全局配置和项目配置的职责固定下来。provider、baseURL、apiKey 引用只放全局~/.config/opencode/opencode.jsonc，model 默认值和 agent 定义放项目级。这样换项目不用重新配鉴权，换机器也只需要重新设一次环境变量。

第二，agent 按任务类型拆分。审查类 agent 限制写权限、用强模型；文档类 agent 用便宜模型；重构类 agent 可以放开编辑权限但指定更强的模型。每个 agent 单独指定 model，成本和质量都能控住。

第三，如果你要长期跑编码任务或者搭 Agent 工作流，可以了解一下 Coding Plan，它适合高频调用场景，比按次计费更划算。入口在https://taotoken.net/coding-plan。日常临时验证模型用模型对话页面就够了，接入和排障的文档在https://taotoken.net/doc，API Keys 管理在https://taotoken.net/api-keys。

第四，配置文件建议纳入版本管理，但只提交引用环境变量的版本，真实 Key 永远留在本地环境变量里。团队协作时，每个人用自己的 Key，配置文件共享，互不干扰。

最后一个小技巧：opencode 的配置是合并的，你可以在项目里放一个.opencode/agents/目录，把项目专属的 agent 用 Markdown 文件写进去，和opencode.json里的 agent 定义并存。这样配置文件和 Markdown 各管各的，prompt 长的用 Markdown，简单的用 JSON，维护起来不打架。