企业官网建设流程全解析

1. Webhooks 已经能触发，模型调用却掉链子

1.1 Webhooks 网关做了什么

OpenClaw 的 Webhooks 已经能让外部事件触发 agent 跑隔离轮次，但 agent 的模型调用总卡在 Key 失效、额度见底。把模型请求改到 TaoToken（https://taotoken.net/?utm_source=taotoken_aicg_blog_end ）后，这条链路才完整：POST /hooks/wake 负责把系统事件推入主会话队列，POST /hooks/agent 用独立 sessionKey 跑隔离轮次，处理完再把摘要送回主会话。整个过程里，模型请求统一走 TaoToken 这一个 API 通道。

从 OpenClaw 的视角看，Webhooks 网关暴露的是两个本地 HTTP 端点。POST /hooks/wake 接收一个 text 字段，比如「收到新邮件」，mode 设为 now 就会立即触发一次心跳；POST /hooks/agent 则更灵活，请求体里可以带 message、agentId、sessionKey、model、thinking、timeoutSeconds 等字段，跑出来的摘要默认送回主会话。认证只认请求头，Authorization: Bearer 或 x-openclaw-token: 二选一，查询字符串里带 token 会被直接拒绝。

1.2 痛点：hooks.token 是网关钥匙，不是模型钥匙

实际操作里最常见的场景是：Webhooks 配置完全照文档写了，curl 打 /hooks/agent 也返回 200，但 agent 真正执行任务时，模型调用那一步开始报错。查日志会发现，问题出在模型 provider 的凭据上，而不是网关本身。这里必须分清两把钥匙：hooks.token 是 Webhooks 网关的共享密钥，只决定「这个 HTTP 请求能不能进 OpenClaw」；模型 Key 决定「agent 调模型时以谁的身份、走哪个通道」。两者一旦混用，要么 Webhooks 认证直接失败，要么模型调用始终不稳定。

我的解法是把模型 provider 整体指到 TaoToken：Base URL 填 https://taotoken.net/api ，Key 用从官网创建的那把，hooks.token 保持原样。这样外部触发和模型调用两条链路各走各的，互不干扰。

2. 拿模型 Key：先开官网再填 Base URL

2.1 注册并创建 API Key

第一步，打开 TaoToken 注册登录。登录后进入控制台，在 API Keys 页面创建一把新 Key，创建完复制保存，这就是要填进 OpenClaw 的模型 Key。注意别把它和 hooks.token 搞混：hooks.token 继续留在 OpenClaw 的 hooks 配置里当网关密钥；这把新 Key 只服务模型调用。

2.2 Base URL 填 https://taotoken.net/api，末尾不要带 /v1

接着打开 OpenClaw 的模型 provider 配置。默认配置路径通常在 ~/.openclaw 目录下的 openclaw.json（也可能是 openclaw.jsonc，以你的版本为准），在模型 provider 段落里找到 Base URL 和 API Key 两个字段。不同版本对这个段落的命名不太一样，有的叫 modelProviders，有的直接放在 agents.defaults.models 附近。不用纠结字段名，核心是改两个值：接口地址和密钥。Base URL 填：

https://taotoken.net/api

末尾不要加 /v1。很多工具在保存 Base URL 时会自动补 /v1，填完回看一下，如果变成了 https://taotoken.net/api/v1，删掉多余的 /v1。API Key 填 YOUR_API_KEY。模型 ID 以 TaoToken 模型广场当时列出的为准，别凭印象填一个不存在的 ID，否则 agent 轮次会直接报模型不存在。

2.3 官网入口和接口地址是两回事

注册、创建 Key、看模型广场、看用量，都去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end ；填进工具的 Base URL 是 https://taotoken.net/api 。这两个地址不能互相替代，也不能把官网落地页链接填进工具。如果你用的是环境变量方式注入模型配置，同样把 Base URL 指到 https://taotoken.net/api ，变量名以你的 OpenClaw 版本文档为准。记住这个分工之后，后面无论怎么改模型 ID 或者加 agent，都不会再迷路。

3. hooks.token 与模型 Key 各管一摊，OpenClaw 配置别混用

3.1 Webhooks 配置一行都不用改

Webhooks 部分的配置保持原样。原文推荐的 hooks 配置是：

{ "hooks": { "enabled": true, "token": "shared-secret", "path": "/hooks", "allowedAgentIds": ["hooks", "main"] } }

token 就是 Webhooks 网关的共享密钥，外部请求带 Authorization: Bearer shared-secret 或 x-openclaw-token: shared-secret 即可。这里千万别换成 YOUR_API_KEY，否则网关会拒绝一切请求。不想把 token 明文写在配置里的话，可以用环境变量：

{ "hooks": { "enabled": true, "token": "${OPENCLAW_HOOKS_TOKEN}", "defaultSessionKey": "hook:ingress", "allowRequestSessionKey": false, "allowedSessionKeyPrefixes": ["hook:"] } }

3.2 defaultSessionKey 和 allowedAgentIds 的作用

/hooks/agent 的核心能力是用独立 sessionKey 跑一次隔离轮次。这个 sessionKey 的请求体覆盖策略在较新版本里默认关闭：请求体带 sessionKey 会被拒绝，除非配置里显式打开。推荐做法是固定一个 defaultSessionKey（比如 hook:ingress），让所有外部事件落到同一个会话上下文；日常保持 allowRequestSessionKey=false，避免调用方随意选择会话。

allowedAgentIds 的作用是限制 /hooks/agent 请求体里显式指定的 agentId。配置了 ["hooks", "main"]，就只有这两个 agent 能被显式路由；省略或包含 * 表示允许任意 agent；设为 [] 则拒绝所有显式 agentId 路由。未知 agentId 会回退到默认 agent，排查路由问题时容易忽略这一点。多 agent 场景建议设置这个字段，否则外部调用方可以随意指定 agent，这属于网关自己的访问控制，和模型 Key 是不是 TaoToken 无关。

3.3 安全基线别放松

Webhooks 端点如果暴露在局域网或公网，建议保持在回环地址 127.0.0.1 或可信的反向代理之后。使用专用的 hook token，不要复用网关认证令牌。如果确实允许请求体设置 sessionKey，务必用 allowedSessionKeyPrefixes 限制前缀。重复认证失败会被按客户端地址限速，返回 429 并带 Retry-After，不需要自己额外写防爆破逻辑。

4. curl 验证外部事件：wake 推主线，agent 跑隔离轮次

4.1 POST /hooks/wake：把系统事件推入主会话队列

配置保存后先重启 OpenClaw，让模型 provider 和 hooks 配置都生效。第一条用 wake 验证：

curl -X POST http://127.0.0.1:18789/hooks/wake \ -H 'Authorization: Bearer shared-secret' \ -H 'Content-Type: application/json' \ -d '{"text":"收到新邮件","mode":"now"}'

text 是必填字段，描述事件本身；mode 默认 now，表示立即触发一次心跳。这条调用不跑隔离 agent，而是把系统事件排进主会话队列，由主 agent 在下一轮心跳里决定怎么处理，适合「先把 agent 叫醒」的场景。

4.2 POST /hooks/agent：用独立 sessionKey 跑隔离轮次

第二条验证隔离轮次：

curl -X POST http://127.0.0.1:18789/hooks/agent \ -H 'x-openclaw-token: shared-secret' \ -H 'Content-Type: application/json' \ -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

message 必填，name 会作为会话摘要的前缀，wakeMode 选 next-heartbeat 表示等下一次周期心跳再跑，避免每次都立刻打扰；需要马上执行就改成 now。响应 200 只代表 OpenClaw 已接受这次运行，agent 的真实执行是异步的，摘要最终会回到主会话。此时 agent 的模型请求已经全部走 https://taotoken.net/api 这个通道，和 Webhooks 认证完全分离。另外，deliver 默认是 true，agent 的响应会自动发送到消息通道；不想让它直接发出去，就把 deliver 设为 false，只把摘要留在主会话里。

4.3 用 model 覆盖当次模型

/hooks/agent 请求体里可以带 model 和 thinking 做单次覆盖。原文示例是「provider/模型名」格式，放在我们的配置里：

curl -X POST http://127.0.0.1:18789/hooks/agent \ -H 'x-openclaw-token: shared-secret' \ -H 'Content-Type: application/json' \ -d '{"message":"Summarize inbox","name":"Email","model":"MODEL_ID_FROM_TAOTOKEN","thinking":"low"}'

MODEL_ID_FROM_TAOTOKEN 换成 TaoToken 模型广场上实际存在的完整模型 ID。如果你在 agents.defaults.models 里强制了模型列表，覆盖的模型必须也在列表中，否则这次 /hooks/agent 会因为模型不在允许列表里而失败。

如果你在配置里用了 hooks.mappings 做自定义映射，比如把某个外部系统的请求体转换成 wake 或 agent 动作，映射后的处理流程本质上还是会落到 /hooks/agent 这类逻辑上，模型请求同样走 https://taotoken.net/api 通道，不需要针对映射单独再做一遍模型配置。映射里如果要指定模型，model 字段同样以 TaoToken 模型广场的 ID 为准。

5. 排障：401 认证失败、400 会话键被拒、模型 ID 不存在

5.1 401：token 没配对或触发限速

返回 401 时，先检查请求头。认证支持 Authorization: Bearer 或 x-openclaw-token: 两种方式，确认请求头里的 token 和 openclaw.json 里 hooks.token 一致。查询字符串 ?token=... 会被拒绝并返回 400，而不是 401，这点容易看错。连续多次认证失败后，OpenClaw 会按客户端地址限速，返回 429，此时看 Retry-After 头，等一会儿再试。

5.2 400：sessionKey 被策略拒绝

/hooks/agent 请求体里如果带了 sessionKey，而配置里 allowRequestSessionKey 为 false（默认就是 false），会返回 400。解决办法是去掉请求体里的 sessionKey，让网关使用 defaultSessionKey；如果确实需要按事件区分会话，再打开 allowRequestSessionKey，同时用 allowedSessionKeyPrefixes 限制前缀，比如 ["hook:"]。

5.3 404 或模型不存在：Base URL 与模型 ID 一起查

如果把 Base URL 填成了 https://taotoken.net/api/v1 ，部分版本会把请求打到不存在的路径上，出现 404 或路径错误。把 Base URL 改回 https://taotoken.net/api 再试。模型 ID 报错则去 TaoToken 模型广场核对当前可用的 ID，模型广场入口在官网首页。排障时记住一个原则：hooks.token 是网关密钥，只出现在 Webhooks 认证头里；模型 Key 是另一串，只出现在模型 provider 配置里。两者一旦互换，排障方向会跑偏。

6. 跑通后去控制台对一下账

6.1 先到模型对话发一条测试消息

到这里，你可以先到 TaoToken 模型对话 里用同一把 Key 发一条测试消息，确认模型 ID 和 Base URL 没填错；如果打算长期跑这类外部事件自动触发的 agent 任务，可以打开 Coding Plan 看套餐是否够用。刚才那几次 /hooks/wake 和 /hooks/agent 调用，也可以回到 控制台 API Keys 或用量页面核对是否都记上了账；以后要把 Claude Code 这类命令行工具也接到同一个通道上，配置对照看 Claude Code 接入文档。

6.2 想先验证 Key 就用 CLI 跑一条

如果你想在终端里先不碰 OpenClaw，直接验证这把 Key 能不能走通模型调用，也可以用 TaoToken 官方 CLI：

npm install -g @taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m YOUR_MODEL_ID

-k 后面是你在 TaoToken 控制台创建的那把 Key，-u 是接口地址，-m 是模型广场上的模型 ID。CLI 能跑通，说明 Key 和通道都没问题，再回到 OpenClaw 排查 Webhooks 就纯粹是网关侧的事了。