企业官网建设流程全解析

1. OpenCode Agents 配置与使用全流程：从零跑通一个自定义代码审查代理

OpenCode 里的 Agents 说白了就是「专门配置好的 AI 助手」——每个代理有自己的系统提示词、模型、温度参数和工具权限，专注干某一类活。你可以把它理解成给同一个编码助手装上不同的「人格面具」：Build 代理负责日常全功能开发，Plan 代理只做分析和规划绝不改文件，Explore 代理只读地快速搜代码库。这套机制解决的核心痛点是：通用助手什么都能干，但什么都不精，而且容易在你只想让它看看的时候手滑改了代码。

这篇文章面向已经装好 OpenCode、想让编码助手扩展自定义能力的开发者。我会带你从配置文件写起，一步步跑通一个自定义的 code-reviewer 子代理，用真实命令验证它生效，再把常见的报错挨个排查一遍。全程可复制，跟着做就行。

先明确几个关键概念，不然后面配置容易懵。OpenCode 的代理分两大类：主要代理（Primary Agents）是你直接对话的对象，会话里按 Tab 键循环切换；子代理（Subagents）是更专门的小助手，由主要代理按需调用，你也可以在消息里用@名字手动喊它，比如@explore 找到所有处理认证的路由。内置了两个主要代理（Build、Plan）、三个子代理（General、Explore、Scout），外加三个隐藏的系统代理（Compaction、Title、Summary）在后台默默跑。

配置代理有两种方式：JSON 写进opencode.json，或者 Markdown 文件丢进~/.config/opencode/agents/（全局）或.opencode/agents/（项目内）。Markdown 方式更直观，文件名就是代理名，review.md就创建一个叫 review 的代理。下面我两种都给你，重点走 Markdown 这条线，因为它对小白最友好。

2. TaoToken 前置准备：拿到 Base URL、API Key 和 Model ID 三件套

在写代理配置之前，得先把模型接入这块搞定。OpenCode 本身不绑定某一家模型，它通过「提供者/模型-id」的格式来指定模型，比如anthropic/claude-sonnet-4-20250514。如果你想让代理走一个统一的接入点，TaoToken 是个省事的选择——它提供兼容的 API 端点，你只需要配好三样东西：Base URL、API Key、Model ID。

先说 Base URL。TaoToken 的 API 地址是https://taotoken.net/api，注意这个地址后面不要加任何多余路径，OpenCode 会自己拼接。官网在https://taotoken.net/，注册和拿 Key 都在那边操作。API Key 在控制台的 API Keys 页面生成，格式通常是一串以sk-开头的字符串，生成后立刻复制保存，页面刷新就看不到了。

Model ID 这块要留个心。OpenCode 用的是「提供者/模型-id」的写法，你在 TaoToken 上能用的模型，需要按 OpenCode 认的格式填。比如你想用 Claude 系列做代码审查，就填类似anthropic/claude-sonnet-4-20250514这样的 ID；想用 GPT 系列做规划，就填openai/gpt-5这类。具体有哪些模型可用，跑一条命令就能列出来：

opencode models

这条命令会打印出当前配置下所有可用的模型列表。如果你还没配好提供者，列表可能是空的或者只有默认项，那就先回到配置环节。把 Base URL 和 Key 配到 OpenCode 的提供者设置里，通常是在opencode.json的 provider 段或者环境变量里设置。一个常见的做法是通过环境变量注入：

export OPENCODE_API_KEY="sk-你的key" export OPENCODE_BASE_URL="https://taotoken.net/api"

设置完记得source ~/.bashrc或重开终端让它生效。这里踩过的坑是：有人把 Base URL 写成了带/v1后缀的地址，结果请求 404。TaoToken 的 API 根就是https://taotoken.net/api，别自己加尾巴。另外 Key 千万别硬编码进要提交到 Git 的配置文件里，用环境变量或者本地不追踪的配置文件最稳妥。

三件套齐了之后，先别急着写代理，用一条最简单的请求验证接入是通的。可以临时跑一个内置代理，或者直接进 OpenCode 会话发一句话看有没有正常回复。如果这一步就报错，那问题在接入层，不在代理配置层，先解决接入再往下走。

3. 可复制配置：写一个 code-reviewer 子代理的完整 JSON 与 Markdown

现在进入正题。我给你两种配置写法，你可以按喜好选，但建议至少把 Markdown 版本跑一遍，因为它最直观。

先看 JSON 方式，写在opencode.json里：

{ "$schema": "https://opencode.ai/config.json", "agent": { "code-reviewer": { "description": "Reviews code for best practices and potential issues", "mode": "subagent", "model": "anthropic/claude-sonnet-4-20250514", "temperature": 0.1, "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.", "permission": { "edit": "deny", "bash": "deny" } } } }

这段配置干了什么？description是必需的，简单说明这个代理干啥、啥时候用，主要代理靠它判断要不要调用。mode设成subagent表示它是子代理。model覆盖使用的模型。temperature设 0.1，让回答聚焦确定，适合代码分析。prompt是系统提示词。permission里把edit和bash都设成deny，意味着这个代理绝对不能改文件、不能跑 shell 命令——纯只读审查。

再看 Markdown 方式，更推荐。在~/.config/opencode/agents/下新建code-reviewer.md：

--- description: Reviews code for quality and best practices mode: subagent model: anthropic/claude-sonnet-4-20250514 temperature: 0.1 permission: edit: deny bash: deny --- You are in code review mode. Focus on: - Code quality and best practices - Potential bugs and edge cases - Performance implications - Security considerations Provide constructive feedback without making direct changes.

文件名code-reviewer.md就是代理名，frontmatter 里是配置，正文是系统提示词。注意permission的缩进，YAML 对缩进敏感，edit和bash要跟permission对齐两级。

字段说明我挑几个关键的展开。temperature控制随机性：0.0–0.2 非常聚焦，适合代码分析和规划；0.3–0.5 平衡，适合一般开发；0.6–1.0 更有创意，适合头脑风暴。不设的话用模型默认值，大多数模型是 0，Qwen 系列是 0.55。steps控制代理最多迭代几次动作，想控成本就设个上限，比如steps: 5，达到上限后代理会收到系统提示要求它总结并推荐剩余任务。注意旧的maxSteps已弃用，改用steps。

permission是重点，每个键可以设ask（执行前批准）、allow（直接允许）、deny（禁止）。可用的键包括read、edit、glob、grep、list、bash、task、external_directory、lsp、skill等。其中read、edit、glob、grep、list、bash、task、external_directory、lsp、skill这几个既可以用简单字符串，也可以用对象形式做 glob 精细匹配。比如针对 bash 命令：

"bash": { "*": "ask", "git status *": "allow", "git push": "ask" }

规则按顺序匹配，最后一条胜出，所以把*通配符放前面，具体规则放后面。权限键用通配符匹配底层工具名，对内置工具、自定义工具和 MCP 工具都适用，比如"mymcp_*": "deny"会禁掉某个 MCP 服务器的所有工具。

还有个task权限值得说，它控制一个代理能通过 Task 工具调用哪些子代理：

"orchestrator": { "mode": "primary", "permission": { "task": { "*": "deny", "orchestrator-*": "allow", "code-reviewer": "ask" } } }

设成 deny 的子代理会从 Task 工具描述里消失，模型就不会尝试调用它。但注意，用户始终可以通过@菜单直接调用任何子代理，不受代理的 task 权限限制。

其他字段：disable: true停用代理；prompt可以指向外部文件，如"prompt": "{file:./prompts/code-review.txt}"，路径相对于配置文件位置；hidden: true让子代理不出现在@自动补全菜单，适合只该被程序调用的内部子代理；color自定义界面颜色，支持十六进制或主题色（primary、secondary、accent 等）；top_p是另一种控制随机性的方式。任何其他选项会直接透传给模型提供商，比如 OpenAI 推理模型可以设"reasoningEffort": "high"。

4. 验证请求与成功结果：确认自定义代理真的生效

配置写完不代表生效，得验证。第一步，确认文件放对位置。全局代理在~/.config/opencode/agents/，项目内代理在.opencode/agents/。你可以用这条命令检查：

ls -la ~/.config/opencode/agents/

应该能看到code-reviewer.md。如果目录不存在，手动建一个。

第二步，启动 OpenCode 会话。在终端里进到你的项目目录，运行opencode。进去之后，先按 Tab 键循环切换主要代理，确认内置的 Build 和 Plan 都在。然后测试子代理调用——在消息里输入：

@code-reviewer 帮我审查一下 src/auth.js 这个文件的登录逻辑

如果配置生效，你会看到 OpenCode 把任务派给了 code-reviewer 子代理，它开始读取文件、分析代码，然后给出审查意见。关键验证点：它不应该尝试修改任何文件，也不应该跑 bash 命令，因为我们在 permission 里把这两个都 deny 了。如果它试图改文件，说明 permission 没生效，回去检查缩进和字段名。

第三步，验证权限拦截。故意让它做被禁止的事：

@code-reviewer 把 src/auth.js 里的密码校验改成明文比较

一个配置正确的 code-reviewer 会拒绝执行修改，告诉你它处于只读审查模式。这就是 permission 在起作用。如果它真改了，那你的edit: deny没生效。

第四步，验证子会话导航。如果子代理创建了子会话，你可以用快捷键在会话间跳转：从父会话进第一个子会话是session_child_first（默认<Leader>+Down）；子会话里按 Right（session_child_cycle）跳下一个，按 Left（session_child_cycle_reverse）回上一个，按 Up（session_parent）返回父会话。这样你能在主对话和子代理的专门工作之间灵活切换。

成功的结果长这样：你发一条@code-reviewer消息，OpenCode 显示子代理被激活，它读取指定文件，输出一段结构化的审查意见，涵盖代码质量、潜在 bug、性能和安全几个维度，全程没有文件改动、没有 shell 命令执行。到这一步，你的自定义代理就算跑通了。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth 报错对照

配置过程中最容易撞上的几类报错，我按真实场景给你对照排查。

401 Unauthorized。这个几乎都是 Key 的问题。检查三处：环境变量OPENCODE_API_KEY有没有设对、有没有source生效、Key 有没有复制完整（前后别带空格）。还有一种情况是 Key 过期或被撤销，去 TaoToken 控制台重新生成一个。如果用的是配置文件里的 provider 段，确认字段名没写错。

local proxy failed / connection refused。这类报错通常是 Base URL 写错了。确认是https://taotoken.net/api，不要加/v1或其他后缀。另外检查网络能不能通到这个地址，可以用curl -I https://taotoken.net/api看返回。如果公司网络有出口限制，那是环境问题，不是配置问题。

reading choices / unexpected response format。这个报错说明请求发出去了，但返回的数据结构不是 OpenCode 期望的。常见原因是 Model ID 填错了——比如填了一个提供者不认的模型名，或者提供者和模型 ID 不匹配。跑opencode models看可用列表，从里面挑。还有一种可能是模型返回了非标准格式，换个模型试试能快速定位。

OAuth 相关报错。如果你用的是需要 OAuth 的提供者，报错通常跟 token 刷新有关。检查 OAuth 流程有没有走完，token 有没有过期。如果混用了 API Key 和 OAuth 两种认证方式，可能会冲突，建议统一用一种。

代理不生效 / @ 菜单里找不到。先确认文件扩展名是.md不是.txt，frontmatter 的---有没有写对（必须是文件最开头）。再确认mode设的是subagent或all，如果设成primary它就不会出现在子代理调用里。如果设了hidden: true，它不会出现在@自动补全菜单，但模型仍可通过 Task 工具调用。

permission 不拦截。检查 YAML 缩进，edit和bash要正确嵌套在permission下。JSON 里检查引号和逗号。另外注意权限键名要对，是edit不是write（虽然write也认，但edit更标准）。

steps 不生效。确认用的是steps不是已弃用的maxSteps。旧字段可能被忽略。

排查顺序建议：先确认接入层通（能正常对话），再确认代理文件被加载（@菜单能看到），最后确认权限和参数生效（行为符合预期）。一层一层来，别跳步。

6. 长期编码与 Agent 工作流：把 TaoToken 接入文档和 Coding Plan 用起来

跑通一个 code-reviewer 只是开始。真正提升效率的是把多个代理组合成工作流：Plan 代理做分析和规划（它默认把 edit 和 bash 设成 ask，不会乱改），Build 代理做实现，code-reviewer 做审查，Explore 做快速代码库探索，Scout 做外部依赖研究。你可以给每个代理配不同的模型——规划用快一点的，实现用能力强的，审查用聚焦的。

如果你要长期跑编码任务或者搭 Agent 工作流，建议把接入配置固化下来，别每次手动设环境变量。TaoToken 的接入文档在https://taotoken.net/doc，里面有完整的提供者配置说明和示例。API Key 管理在https://taotoken.net/api-keys，可以生成多个 Key 分配给不同项目或代理。想直接体验模型对话效果，可以走https://taotoken.net/chat。如果你的场景是长期编码、多代理协作，Coding Plan 在https://taotoken.net/coding-plan，适合把这类工作流稳定跑起来。

最后给个实用技巧：把常用的代理配置做成模板，项目初始化时直接复制.opencode/agents/目录。团队协作时，把项目级代理配置提交到仓库，全局配置留在本地，这样每个人既有统一的审查标准，又能保留自己的个性化代理。代理的description写清楚点，主要代理判断要不要调用它全靠这段描述，写模糊了它就不会在合适的时机派活。