企业官网建设流程全解析

1. 先搞懂 openclaw 智能体循环到底在转什么

openclaw 的智能体循环，说白了就是一条从「你发消息」到「AI 回消息」的完整流水线。它不是一个函数调用那么简单，而是包含了入口接收、排队、组装提示词、模型推理、工具执行、流式回传、持久化这一整套动作。很多刚接触 openclaw 的开发者会把它想成「调一次模型 API 就完事」，结果一上手就懵：为什么 CLI 敲下去没反应？为什么 Gateway RPC 返回了一个 runId 却拿不到最终结果？为什么同一个会话连发几条消息，顺序会乱？

这些问题的答案都藏在智能体循环的机制里。openclaw 把一次对话拆成了多个阶段，每个阶段都有明确的事件和钩子，你可以理解成一条装配线：原料（用户消息）从一头进去，经过多道工序，成品（AI 回复）从另一头出来。中间任何一道工序出问题，成品就出不来。

它适合谁？适合正在用 openclaw 做智能体应用、想搞清楚 CLI 和 Gateway RPC 两条调用链路差异、并且需要把模型请求统一走一个稳定入口的开发者。尤其是当你发现本地直连模型经常超时、或者多个智能体共用一套 Key 管理混乱的时候，把模型调用收敛到 TaoToken 这类统一网关，会省掉大量重复配置。

我试过在同一个项目里同时用 CLI 调试、用 Gateway RPC 做服务端集成，两条链路如果各自配一套模型地址和 Key，维护起来非常痛苦。后来统一走 TaoToken 的 API 入口，CLI 和 RPC 共用一份配置，问题少了一大半。

这一篇的核心目标有三个：第一，把智能体循环的触发与回传机制讲清楚；第二，给你一份可复制的 TaoToken 统一 Key 配置片段；第三，带你跑通 Gateway RPC 的连通性验证。读完你应该能自己判断：消息卡在哪一环、该看哪个事件、该改哪份配置。

在往下走之前，先记住一个关键区分：CLI 的openclaw agent是「启动并等结果」，Gateway RPC 的agent是「启动并立即返回 runId」，agent.wait才是「等结果」。这个区别决定了你写代码时是同步拿回复还是异步轮询事件。搞混这两个，后面所有调试都会绕弯路。

2. TaoToken 前置准备：统一 Key 与模型入口

在讲配置之前，先把 TaoToken 的定位说清楚。它是一个模型调用的统一入口，你不需要在 openclaw 里为每个模型单独填一堆地址和密钥，而是把 Base URL 指向 TaoToken 的 API 地址，用一把 Key 管理多个模型的调用。对 openclaw 这种会在智能体循环里频繁发起模型请求的场景来说，统一入口能明显减少配置漂移。

你需要准备的东西不多：一个 TaoToken 账号、一把 API Key、以及确认你要用的模型 ID。API Key 在控制台的 API Keys 页面创建，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。创建后复制出来，注意它只完整显示一次，丢了就得重建。

模型 ID 这块要留意：openclaw 的配置里模型名要和 TaoToken 支持的模型标识对齐，不要自己拍脑袋写一个。你可以先在模型对话页面确认可用模型，地址是 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。选一个你常用的，比如做代码类任务就选偏 coding 的模型，做通用对话就选通用模型。

Base URL 统一用 https://taotoken.net/api ，注意这个地址后面不加任何 UTM 参数，直接写进配置即可。很多人在这一步会多写一个斜杠或者拼错路径，导致后面 401 或者 404，排查半天。记住：Base URL 就是https://taotoken.net/api，模型请求路径由 openclaw 自己拼接。

关于 Key 的安全，有一点必须提醒：不要把 Key 硬编码在会提交到 Git 的文件里。openclaw 的配置通常放在用户目录下的配置文件中，你可以用环境变量引用，或者放在本地不纳入版本管理的配置文件里。后面给的配置片段我会用占位符表示，你替换成自己的真实值。

如果你还没决定用哪种方式接入，可以先想清楚使用场景：只是本地 CLI 调试，配置写在 openclaw 的全局配置里就够了；如果是服务端通过 Gateway RPC 调用，建议把模型配置抽成一份共享配置，CLI 和 RPC 都读它，避免两处不一致。这也是我推荐统一走 TaoToken 的原因——一份 Base URL、一把 Key、一个模型 ID，两条链路复用。

另外，TaoToken 的接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到路径或参数不确定的时候，先翻文档比瞎试快得多。前置准备做到位，后面的配置和验证就是顺水推舟。

3. 可复制配置：openclaw 接入 TaoToken 的完整片段

这一节是重点，直接给你能复制粘贴的配置。openclaw 的模型配置一般放在用户目录下的配置文件中，常见路径是~/.openclaw/config.json或项目级的openclaw.config.json。具体用哪个取决于你的安装方式，先确认你的 openclaw 读的是哪份配置，再往里写。

先给一份 JSON 格式的配置片段，把模型入口指向 TaoToken：

{ "models": { "default": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "model": "your-model-id" } }, "agent": { "model": "default", "maxIterations": 10, "timeoutMs": 600000 } }

这里几个字段要解释清楚。provider用openai-compatible是因为 TaoToken 的 API 兼容 OpenAI 风格的请求格式，openclaw 走这个 provider 就能正常发请求。baseUrl就是前面说的https://taotoken.net/api，不要加多余路径。apiKey用${TAOTOKEN_API_KEY}引用环境变量，这样配置文件本身可以安全地放进版本库。model填你在 TaoToken 模型列表里确认过的模型 ID。

agent段里的maxIterations控制智能体循环最多转几轮，默认给 10 够用，复杂任务可以调大。timeoutMs是执行超时，对应前面说的智能体运行超时，默认 600000 毫秒也就是 10 分钟，和 openclaw 的默认执行超时一致。

如果你更习惯 TOML 格式，等价配置长这样：

[models.default] provider = "openai-compatible" baseUrl = "https://taotoken.net/api" apiKey = "${TAOTOKEN_API_KEY}" model = "your-model-id" [agent] model = "default" maxIterations = 10 timeoutMs = 600000

环境变量这样设置，Linux/macOS 下：

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

Windows PowerShell 下：

$env:TAOTOKEN_API_KEY="sk-你的真实key"

设置完记得新开一个终端或者 source 一下配置文件，让环境变量生效。很多人配完发现还是 401，就是因为当前 shell 没读到新变量。

如果你用的是 Claude Code 这类工具，配置思路一样，把 Base URL 指向 TaoToken，Key 用环境变量注入，模型 ID 填对应值。三件套永远是：Base URL + Key + Model ID，缺一不可，任何一个写错都会在智能体循环的模型推理阶段报错。

配置写完后，先别急着跑复杂任务，用一条最简单的消息验证链路通不通。下一节就带你做 Gateway RPC 的连通性验证。

4. 验证请求：Gateway RPC 连通性与成功结果

配置就绪后，第一步是确认 Gateway 服务在跑。openclaw 的 Gateway 通常监听一个本地端口，你先启动它：

openclaw gateway start

启动后确认端口在监听，比如默认端口是 18789，可以用：

curl -s http://127.0.0.1:18789/health

返回健康状态说明 Gateway 起来了。接下来验证 Gateway RPC 的agent调用。agent是启动并立即返回 runId，适合异步场景。用 curl 发一个 JSON-RPC 请求：

curl -s http://127.0.0.1:18789/rpc \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "agent", "params": { "sessionId": "test-session-001", "message": "你好，请回复一句话确认链路正常" } }'

如果链路正常，你会拿到类似这样的返回：

{ "jsonrpc": "2.0", "id": 1, "result": { "runId": "run_abc123", "acceptedAt": 1730000000000 } }

看到runId和acceptedAt就说明入口点接收成功了，消息已经进入智能体循环的排队阶段。注意这只是「收到了」，不是「做完了」。要拿最终结果，用agent.wait：

curl -s http://127.0.0.1:18789/rpc \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "agent.wait", "params": { "runId": "run_abc123", "timeoutMs": 30000 } }'

agent.wait的默认等待超时是 30 秒，注意这个 30 秒只是「等待」超时，不代表智能体停了。如果 30 秒内没等到结果，它会返回等待超时，但智能体还在后台跑。这时候你可以再调一次agent.wait继续等，或者通过事件流订阅进度。

成功拿到结果时，返回里会包含 AI 的回复内容，类似：

{ "jsonrpc": "2.0", "id": 2, "result": { "runId": "run_abc123", "status": "completed", "reply": "链路正常，我收到了你的消息。" } }

看到status: completed和reply字段，说明整条链路从 Gateway RPC 入口、排队、组装提示词、模型推理（走 TaoToken）、流式回传、持久化全部跑通了。这时候你去~/.openclaw/agents/<智能体ID>/sessions/<会话ID>.jsonl应该能看到这次对话的记录。

如果你想用 CLI 验证，更简单：

openclaw agent --session test-session-001 --message "你好，确认链路"

CLI 是启动并等结果，会直接把回复打印出来。CLI 通了但 RPC 不通，通常是 Gateway 没起或者端口不对；RPC 通了但模型报错，通常是 TaoToken 的 Key 或模型 ID 有问题。分清楚卡在哪一环，排查效率会高很多。

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

这一节把智能体循环里最容易撞上的几个报错拆开讲，每个都给你定位思路。

401 Unauthorized。这个几乎都是 Key 的问题。先确认环境变量TAOTOKEN_API_KEY在当前 shell 里能读到：

echo $TAOTOKEN_API_KEY

如果输出为空，说明变量没生效，重新 export 或者检查配置文件路径。如果变量有值但还是 401，检查 Key 有没有复制完整、有没有多余空格、有没有在 TaoToken 控制台被禁用。还有一种情况是 Base URL 写错了，比如写成了https://taotoken.net/api/带尾斜杠，某些客户端会拼出双斜杠导致鉴权失败。统一用https://taotoken.net/api。

local proxy failed。这个报错通常出现在 openclaw 尝试连接模型入口但网络层没通的时候。先确认你的机器能正常访问https://taotoken.net/api，用 curl 测一下：

curl -s -o /dev/null -w "%{http_code}" https://taotoken.net/api

如果返回的不是 2xx 或 4xx 而是连接失败，说明网络出口有问题。注意这里不要用任何非正规的网络工具，正常的企业网络或家庭网络直连即可。如果公司网络有出口限制，找网络管理员确认放行。

reading choices 相关报错。这个一般出现在解析模型返回的时候，典型信息是cannot read property 'choices' of undefined或者reading 'choices'。原因是模型返回的结构和 openclaw 预期的不一致。排查两步：第一，确认provider设成了openai-compatible，因为 TaoToken 返回的是 OpenAI 风格结构，provider 不对就会解析失败；第二，确认模型 ID 是 TaoToken 支持的，写错模型 ID 时有些网关会返回错误结构而不是标准 choices。去模型对话页面核对一下模型标识。

OAuth 相关报错。如果你用的是 Claude Code 这类带 OAuth 流程的工具，报 OAuth 错误通常是因为认证方式没配对。走 TaoToken 统一入口时，认证靠 API Key，不需要额外的 OAuth 流程。检查配置里是不是残留了旧的 OAuth 配置项，把它清掉，改成 Base URL + Key + Model ID 三件套。

runId 拿到了但 wait 一直超时。这说明入口接收成功，但智能体循环卡在中间某一环。按顺序查：模型推理有没有报错（看 Gateway 日志）、工具执行有没有卡住（看 tool 事件）、是不是触发了压缩重试。把timeoutMs适当调大，同时看事件流里最后一个事件是什么类型，就能定位卡点。

同一会话消息顺序乱。正常情况下同一会话是串行处理的，不会乱。如果乱了，检查是不是用了不同的 sessionId 发到了同一个会话，或者队列模式配置有问题。openclaw 支持 collect、steer、followup 三种队列模式，默认行为是串行，改过配置的话确认一下当前模式。

排查的核心思路就一句话：先分清是入口问题、模型问题还是执行问题。入口看 runId 有没有返回，模型看 401 和 choices 报错，执行看事件流和超时。分清楚这三层，大部分报错十分钟内能定位。

6. 把智能体循环用起来：从验证到长期编码

链路验证通过之后，你就可以把 openclaw 的智能体循环真正用起来了。CLI 适合本地快速调试，敲一条命令看回复，改提示词、试工具调用都很方便。Gateway RPC 适合服务端集成，你的应用通过 RPC 发起任务、订阅事件、拿回结果，把智能体能力嵌进自己的系统里。

如果你打算长期跑编码类或 Agent 类任务，建议了解一下 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它针对长时间、多轮次的编码场景做了优化，配合 openclaw 的智能体循环，能减少频繁请求带来的管理成本。日常调试模型回复是否正常，可以用模型对话页面快速验证，地址是 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。

回到智能体循环本身，有几个实用技巧值得记住。第一，善用事件流。lifecycle、assistant、tool 三类事件能让你实时看到智能体在干什么，调试时把事件打出来，比盯着最终回复有用得多。第二，钩子是定制入口。before_tool_call 和 after_tool_call 能改工具参数和结果，before_agent_start 能做开工前检查，需要深度定制时从钩子下手。第三，注意两层超时的区别。agent.wait 的 30 秒是等待超时，智能体执行超时是 600 秒，别把等待超时当成任务失败。

最后给一个我踩过的坑：一开始我把 CLI 和 RPC 各配了一套模型地址，结果 CLI 能跑、RPC 报 401，查了半天发现是 RPC 那份配置里的 Key 是旧的。统一走 TaoToken 一份配置之后，这类问题再没出现过。配置收敛这件事，越早做越省心。

现在你可以按这个顺序动手：先配好 TaoToken 的 Base URL、Key、Model ID 三件套，启动 Gateway，用 curl 跑一遍 agent 和 agent.wait，看到 completed 和 reply 就算通了。然后换成你自己的业务消息，观察事件流，逐步加上钩子定制。智能体循环这条链路一旦跑顺，后面做多轮对话、工具编排、长任务都会顺很多。