在 OpenClaw 里对 Agent 说“上海天气怎么样”，它不会直接跳到天气 API。它先要完成一次模型规划：读 SKILL.md、判断触发条件、决定调用 weather-assistant，再生成参数。模型通道没配好，Agent 要么回一段泛泛的天气建议，要么在日志里留下 401。把模型 Key 切到 TaoToken 时，先去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建 Key，再把 OpenClaw 的模型 Base URL 写为 https://taotoken.net/api，模型 ID 以模型广场当时列表为准。这样第 17.7 节的状态持久化、API 降级、Cron 推送才有验证价值。
1. 上海天气这句话背后，OpenClaw 先要过模型规划这一关
很多人第一次调天气 Skill，会把注意力全放在 WEATHER_API_KEY 上，觉得天气 API 通了，Skill 就通了。实际链路更长：用户说“上海天气怎么样”，Agent 先要理解这句话该不该触发 weather-assistant，然后读取 SKILL.md 里的触发条件和执行步骤，再决定传什么参数给 Skill。这个规划动作由模型完成，模型通道一断，Skill 代码再漂亮也没机会执行。
1.1 天气 Skill 的调用链不是“用户说一句→天气 API”
完整链路可以拆成六步。第一步，用户在 OpenClaw 对话里发消息。第二步，Agent 调用模型完成规划，判断是否命中 SKILL.md 中的触发条件。第三步，Agent 从 MEMORY.md 读取默认城市和温度单位偏好，如果用户没在本次消息里指定城市。第四步，Agent 调用 weather-assistant 的 execute，传入 location 和 unit。第五步，Skill 内部读 ~/.openclaw/.env 里的 WEATHER_API_KEY，请求天气服务商接口，期间可能走缓存或重试。第六步，Skill 返回结构化天气数据，Agent 组织成自然语言回复。
这条链里，第二步最容易被忽略。如果模型通道用的是默认官方地址，额度不够、Key 过期、并发限制都会让第二步直接失败。表现不是天气 API 报错，而是 Agent 根本没调用 Skill。你去翻日志，会看到 turn 级别的 401 或超时，而不是 weather-assistant 内部的错误。所以调天气 Skill 之前，先把模型通道确认下来，比反复改 SKILL.md 更省时间。
1.2 为什么先验证模型通道，再验证 Skill 逻辑
模型通道没通时，状态持久化、API 降级、Cron 推送这些特性都测不了。比如你按第 17.7 节设计了一个缓存天气结果的逻辑，想让 Agent 在天气 API 失败时返回上一次缓存。但模型通道不通，Agent 不会进入 Skill，缓存逻辑永远不执行。再比如你写了 AGENTS.md 的 Memory Rules，想让 Agent 把“我住在上海”写入 MEMORY.md。模型通道不通，Agent 连读取规则这一步都完不成。
先把模型通道切到 TaoToken，相当于把“规划层”和“执行层”拆开验证。规划层通了，你才可以用“上海天气怎么样”去触发完整调用，然后看日志里有没有 weather-assistant 的 execute 记录。有 execute 记录，说明模型规划正确命中 SKILL.md；没有 execute 记录，说明问题还在模型通道或 SKILL.md 触发条件上。这个判断顺序能避免你在天气 API 和 OpenClaw 配置之间来回猜。
2. 把 OpenClaw 的模型 provider 指到 TaoToken：动 .env 和 openclaw.json
模型通道配置不要和天气 Skill 配置混在一起。天气服务商的 WEATHER_API_KEY 属于 Skill 级别，放进 ~/.openclaw/.env，由 SKILL.md 里的 requires.env 声明。TaoToken 的 Key 属于模型通道级别，同样可以放在 ~/.openclaw/.env，但在 openclaw.json 的模型 provider 段里用 ${} 引用。两把 Key 分开命名，排障时一眼就能看出是谁报错。
2.1 在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建 Key，顺手看模型广场
打开 TaoToken，注册并进入控制台。创建 API Key 时，先复制出来，后面填进 ~/.openclaw/.env 的 TAOTOKEN_API_KEY。不要直接把 Key 写进 openclaw.json，也不要把 Key 写进 SKILL.md 或 TypeScript 代码注释。控制台里还有一个模型广场，里面会列出当前可用的模型 ID。OpenClaw 的模型 ID 不要凭记忆写，直接以模型广场当时列表为准。不同时期可用模型会变，拿列表里的 ID 填，能少踩一次 404。
创建 Key 之后，顺手看一眼用量入口在哪。后面重启 gateway、对 Agent 说“上海天气怎么样”之后，你要回到这个控制台确认这次模型调用有没有记上账。记上账说明 OpenClaw 确实通过 TaoToken 走了一次模型规划；没记上账，说明模型请求根本没发出来，或者被本地配置拦住了。
2.2 ~/.openclaw/.env 里只放引用，不放天气 Key 和模型 Key 的明文副本
在 ~/.openclaw/.env 里加两行，一行给模型通道，一行给天气服务商。变量名不要混用，后面 openclaw.json 和 SKILL.md 都按名字引用。
TAOTOKEN_API_KEY=YOUR_API_KEY WEATHER_API_KEY=your_weather_api_key_here这里 YOUR_API_KEY 是你在 TaoToken 控制台创建的 Key，不是天气服务商的 Key。weather_api_key_here 才是天气服务商给你的 Key。两个变量都放在 ~/.openclaw/.env，但用途完全不同。模型通道的 Key 只进 openclaw.json 的模型段；天气 Key 只进 SKILL.md 声明的环境变量。不要把 TAOTOKEN_API_KEY 写进天气 Skill 的 metadata，也不要把 WEATHER_API_KEY 写进 openclaw.json 的模型 provider。
2.3 openclaw.json 的模型段：base_url 填 https://taotoken.net/api，不要带 /v1
打开 ~/.openclaw/openclaw.json，找到模型 provider 相关配置。如果你现在的配置还是官方默认地址，把 base_url 改成 TaoToken 的接口地址。注意，填进工具的 Base URL 是 https://taotoken.net/api，末尾不要带 /v1。官网落地页和接口地址不是一回事，落地页只用来注册、创建 Key、看模型广场和看用量，不要把它填进 base_url。
{ "env": { "WEATHER_API_KEY": "${WEATHER_API_KEY}", "TAOTOKEN_API_KEY": "${TAOTOKEN_API_KEY}" }, "model": { "provider": "openai-compatible", "base_url": "https://taotoken.net/api", "api_key": "${TAOTOKEN_API_KEY}", "model": "YOUR_MODEL_ID" } }这段配置里，model.model 填模型广场里的模型 ID，不要自己加日期后缀，也不要写不存在的型号。provider 类型按你当前 OpenClaw 版本支持的方式填，如果原来是官方通道，保留原有 provider 类型，只改 base_url、api_key 引用和 model。改完保存，先不要急着重启，检查一遍 base_url 有没有多出 /v1，api_key 有没有写成天气 Key。
2.4 模型 ID 以模型广场当时列表为准
模型 ID 是排障里最容易出问题的一项。有人习惯把某个模型名记成“通用名”，但通道列表里可能已经换了别名。最稳妥的做法：打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 的模型广场，复制当前可用 ID，粘贴到 openclaw.json 的 model 字段。如果日志里出现 404 或 model not found，先回到模型广场对一遍 ID，而不是去改 SKILL.md。
模型 ID 对了，模型通道才算完整。接下来天气 Skill 的 SKILL.md、TypeScript 和 .cache.json 才有执行机会。
3. 天气查询 Skill 的 SKILL.md、缓存和降级怎么写
第 17.7 节的天气查询加推送技能，结构不复杂，但每个文件职责要分清。SKILL.md 负责触发条件和执行步骤，TypeScript 负责缓存、重试、降级和日志，.cache.json 负责 Skill 内部临时状态，MEMORY.md 负责跨会话偏好。模型通道切到 TaoToken 之后，Agent 能正确读到 SKILL.md，这些文件才会按预期联动。
3.1 SKILL.md 里把触发条件、默认城市、单位偏好写清楚
SKILL.md 不要只写“查天气”。触发条件写得太宽，Agent 会把“今天适合穿什么”也塞进来；写得太窄，用户说“上海天气怎么样”又触发不了。建议把常见说法列进去，同时把默认城市和温度单位的读取逻辑写进执行步骤。
--- name: weather-assistant description: 当用户询问天气、温度、是否需要带伞时使用。 metadata: openclaw: requires: env: ["WEATHER_API_KEY"] --- # 天气预报助手 ## 触发条件 - 用户说“查天气”“今天天气怎么样”“需要带伞吗”“上海天气怎么样” - 用户明确提到城市名并询问温度、降雨、湿度 ## 执行步骤 1. 识别消息中的城市；如果没有，从 MEMORY.md 读取默认城市 2. 识别温度单位偏好；如果没有，从 MEMORY.md 读取，默认摄氏度 3. 调用实时天气接口获取数据，优先使用 .cache.json 中 5 分钟内的缓存 4. 如果接口失败，尝试返回上一次成功缓存，并标记 fromCache 5. 如果用户说“记住我住在上海”，按 AGENTS.md 的 Memory Rules 写入 MEMORY.md ## API 配置 - 认证方式：从环境变量 WEATHER_API_KEY 读取 - 超时：10 秒 - 429 处理：读取 retry-after，等待后重试这个文件不需要写模型 Key。模型 Key 是 OpenClaw 全局模型通道的事，和天气 Skill 无关。SKILL.md 里出现 TaoToken 反而会让职责混乱。
3.2 TypeScript 里 fetchWithRetry、缓存、优雅降级
TypeScript 实现可以围绕四个函数展开：读缓存、写缓存、带重试的 fetch、Skill execute。重试只针对临时故障，401 和 403 不重试，直接提示检查 WEATHER_API_KEY。429 读取 retry-after，等待后重试。超时用 AbortController，给天气 API 设 10 秒上限，避免 Skill execute 长时间挂起导致对话卡住。
import { SkillDefinition } from '@openclaw/skills-core'; import fs from 'node:fs/promises'; const CACHE_TTL = 5 * 60 * 1000; async function readCache(location: string) { try { const raw = await fs.readFile('.cache.json', 'utf8'); const cache = JSON.parse(raw); const item = cache[location]; if (item && Date.now() - item.timestamp < CACHE_TTL) return item; return null; } catch { return null; } } async function writeCache(location: string, data: any) { let cache: Record<string, any> = {}; try { cache = JSON.parse(await fs.readFile('.cache.json', 'utf8')); } catch {} cache[location] = { data, timestamp: Date.now() }; await fs.writeFile('.cache.json', JSON.stringify(cache, null, 2)); } async function fetchWithRetry(url: string, maxRetries = 3): Promise<any> { let lastError: Error | null = null; for (let attempt = 1; attempt <= maxRetries; attempt++) { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 10000); try { const response = await fetch(url, { signal: controller.signal }); clearTimeout(timeoutId); if (response.status === 401 || response.status === 403) { throw new Error('WEATHER_API_KEY 可能无效，请检查 ~/.openclaw/.env'); } if (response.status === 429) { const retryAfter = Number(response.headers.get('retry-after') || 2); await new Promise((r) => setTimeout(r, retryAfter * 1000)); continue; } if (!response.ok) { throw new Error(`天气 API 返回 ${response.status}`); } return await response.json(); } catch (error: any) { lastError = error; if (attempt < maxRetries) { await new Promise((r) => setTimeout(r, 1000 * 2 ** (attempt - 1))); } } } throw lastError; }execute 里先读缓存，缓存命中就返回 fromCache。缓存没有或过期，再调 fetchWithRetry。接口失败时，再尝试读一次旧缓存，返回旧数据并标记 fromCache，而不是让整个对话直接报错。这个降级逻辑和第 17.3 节的优雅降级对应，也是天气 Skill 从 Demo 走向可用的关键一步。
3.3 跨会话状态：MEMORY.md、Daily Logs 和 .cache.json 各放什么
状态不要都塞进一个文件。默认城市、温度单位偏好属于跨会话长期状态，放 MEMORY.md，由 Agent 根据 AGENTS.md 的 Memory Rules 写入。本次会话里“刚才查了上海”属于短期上下文，放 Daily Logs，不需要 Skill 主动维护。天气响应缓存和速率限制计数属于 Skill 内部状态，放 Skill 目录下的 .cache.json，读写快，也方便清理。
AGENTS.md 里可以加一段 Memory Rules，明确告诉 Agent 什么时候写 MEMORY.md：
## Memory Rules - 用户明确说“记住我住在{城市}”时，把默认城市写入 MEMORY.md。 - 用户明确说“我习惯摄氏度/华氏度”时，把温度单位偏好写入 MEMORY.md。 - 不要将任何 API Key、Token 写入 MEMORY.md、Daily Logs 或 .cache.json。这段规则很重要。模型通道切到 TaoToken 后，Agent 的规划能力正常，它才有可能按规则判断“用户这句话是不是在要求记住偏好”。如果模型通道不稳定，Agent 可能漏掉写入动作，你就会误以为是 MEMORY.md 或 Skill SDK 的问题。
3.4 速率感知与超时：429 可以等，401/403 不要重试
天气服务商的限流和模型通道的限流要分开看。天气 API 返回 429，Skill 内部按 retry-after 等待，最多重试几次。模型通道如果返回 429，属于 OpenClaw 模型层，不需要天气 Skill 处理。不要把所有 429 都写成无限重试，也不要把 401、403 当临时故障。401 和 403 是凭证或权限问题，重试一百次也不会变成成功，只会拖长对话时间。
超时也一样。天气 API 超时由 Skill 内部 AbortController 处理，超过 10 秒就中断并走缓存降级。模型通道超时由 OpenClaw Gateway 处理，可能触发故障转移或上下文压缩。排障时先看错误出现在 turn 级别还是 execute 级别，再决定查 openclaw.json 还是查天气 API。
4. 重启 gateway 后，用“上海天气怎么样”做一次完整验证
配置改完，重启 gateway，让 OpenClaw 重新加载 openclaw.json 和 ~/.openclaw/.env。然后先跑一次命令行测试，绕开 Agent 规划，直接验证 Skill 本体能不能执行。命令行通过后，再回到对话里说“上海天气怎么样”，验证 Agent 规划能不能命中 SKILL.md。两个测试都通过，才说明模型通道和 Skill 逻辑都通了。
4.1 openclaw gateway restart 之后先跑一次 skills run
在终端执行：
openclaw gateway restart openclaw skills run weather-assistant --params '{"location":"上海"}'第一条命令让 Gateway 重新加载模型配置和 Skill。第二条命令直接调用 weather-assistant，不经过 Agent 规划。如果这里返回天气数据或缓存数据，说明 WEATHER_API_KEY、天气接口地址、缓存逻辑基本正常。如果这里报错，先修 Skill 本体，不要急着去对话里测模型通道。
这一步能帮你区分两类 401。skills run里的 401 来自天气服务商，提示你检查 WEATHER_API_KEY。对话里 turn 级别的 401 来自模型通道，提示你检查 TAOTOKEN_API_KEY、base_url 和模型 ID。两类错误长得像，但排查方向完全不同。
4.2 在对话里触发 Agent 规划，观察日志里的 401/超时
命令行测试通过后，回到 OpenClaw 对话，对 Agent 说“上海天气怎么样”。这句话会触发一次完整调用：Agent 读 SKILL.md，判断触发条件，生成 location=上海 的参数，调用 weather-assistant，拿到结果后组织回复。你要看的不只是回复内容，还有日志里有没有 weather-assistant 的 execute 记录。
如果 Agent 回复了天气，日志里也有 execute 记录，说明模型通道和 Skill 逻辑都通了。如果 Agent 回复“我无法查询天气”或类似内容，但日志里没有 execute 记录，说明模型规划阶段就失败了，优先查模型通道。如果日志里有 execute 记录但返回错误，说明模型规划成功，问题在天气 API 或 Skill 代码。这个分界点非常重要，能避免你反复改 SKILL.md 却忽略模型通道。
4.3 去控制台对一下这次调用有没有记上账
对话返回正常后，打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 的用量或调用记录页面，看刚才这次“上海天气怎么样”对应的模型调用有没有记上账。记上账，说明 OpenClaw 确实通过 TaoToken 发出了模型请求，模型通道配置正确。如果对话有回复但控制台没有记录，可能是你本地还有缓存，或者请求走了别的 provider，需要回 openclaw.json 再对一遍 base_url 和 api_key 引用。
这一步也顺便验证模型 ID 有没有填错。模型 ID 填错时，有些客户端会报 404，有些会回退到默认模型。回退到默认模型后，对话可能也有回复，但用量记录里的模型名和你配置的不一致。所以不要只看“有没有回复”，还要看“记的是不是你要的模型”。
4.4 跑通后再验第 17.7 节的 Cron 推送
模型通道和单次查询都跑通后，再验 Cron 推送。在 HEARTBEAT.md 里加一段每日任务：
## 每日 07:30 天气检查 - 从 MEMORY.md 读取默认城市和温度单位 - 调用 weather-assistant 查询当天天气 - 如果有雨，通过配置的 Channel 推送“今日有雨，记得带伞”Cron 推送依赖 Gateway 常驻和模型通道可用。如果 Gateway 没常驻，或者模型 Key 失效，推送任务会在模型规划阶段失败。先手动触发一次 Heartbeat，确认 Agent 能读取 HEARTBEAT.md、调用 Skill、生成通知，再等定时器自动执行。这样排障范围小，不用在定时任务和配置之间来回猜。
5. 401、超时、缓存不生效、Cron 不推送：按层排查
排障时不要一上来就改代码。先看错误发生在哪一层：模型规划层、Skill 执行层、天气 API 层还是 Cron 调度层。每一层的日志位置和修复动作不同。下面按天气 Skill 常见问题列一遍。
5.1 401/403：Key、Base URL、模型 ID 三查
模型通道 401 先查 TAOTOKEN_API_KEY 是否填对，再查 openclaw.json 里 api_key 是不是引用了 ${TAOTOKEN_API_KEY}。然后查 base_url，确认填的是 https://taotoken.net/api，末尾没有 /v1。多了 /v1 可能导致路径不匹配，出现 404 或 401。最后查模型 ID，确认是从模型广场复制的当前可用 ID。
天气 API 401 查 WEATHER_API_KEY。确认它只出现在 ~/.openclaw/.env，并且 SKILL.md 的 requires.env 里声明了 WEATHER_API_KEY。不要把天气 Key 和模型 Key 写成同一个变量，也不要把两个 Key 混着填进同一处配置。
5.2 超时：先分模型通道还是天气 API
对话整体超时，通常是模型通道或 Gateway 的问题。看日志里有没有开始 turn、有没有模型请求、有没有重试。如果模型请求发出后很久没返回，检查网络、模型 ID、并发限制。如果日志显示模型规划已完成，卡在 weather-assistant 执行，那超时来自天气 API，检查 Skill 里的 AbortController 是否生效、天气服务商是否可达。
还有一种情况：模型通道超时触发了 Gateway 的故障转移，换了一个认证配置继续跑。这种故障转移对 Skill 开发者透明，但会在日志里留下记录。如果你发现同一次对话里模型 ID 变了，或者用量记录出现两个模型，就要回 openclaw.json 检查模型通道是否还有旧配置残留。
5.3 缓存不生效：看 .cache.json 路径和 TTL
缓存不生效时，先确认 .cache.json 的读写路径是 Skill 目录，不是当前工作目录。Node.js 里 fs.readFile('.cache.json') 默认相对当前工作目录，如果 OpenClaw 启动 Gateway 时工作目录不是 Skill 目录，就会读不到缓存。可以用 path.join(__dirname, '.cache.json') 或配置 Skill 目录绝对路径。然后确认 TTL 没写错，5 分钟缓存对应 5 * 60 * 1000，不要写成 5 秒或 5 小时。
另外，缓存命中时返回的数据最好带 fromCache 标记。Agent 看到 fromCache=true，可以在回复里说明“这是最近一次缓存结果”。这样你一眼就能判断缓存有没有生效。
5.4 Cron 不推送：HEARTBEAT.md 与 gateway 常驻
Cron 不推送先看 HEARTBEAT.md 有没有被加载。格式不对、任务时间写错、频道配置缺失都会导致任务不执行。然后看 Gateway 是否常驻，如果进程退出，定时器自然不跑。再看模型通道是否可用，因为 Cron 任务也需要 Agent 完成规划才能调用天气 Skill。模型通道 401 时，Cron 任务会在规划阶段失败，天气 API 根本不会被调用。
排查时可以手动触发一次 Heartbeat，看日志里有没有读取 HEARTBEAT.md、有没有调用 weather-assistant、有没有发送通知。手动触发成功后再等自动执行，能快速定位是调度问题还是模型通道问题。
6. 跑通之后，把天气 Skill 的用量和推送节奏管起来
天气 Skill 跑通不是终点。模型通道和天气 API 都会产生用量，前者按模型调用计，后者按天气服务商的额度计。两套用量要分开看。模型通道的调用记录在 TaoToken 控制台，天气 API 的用量在天气服务商后台。把“上海天气怎么样”跑通之后，回控制台看一次模型调用记录，确认模型 ID、调用时间、消耗都能对上。后面加 Cron 推送时，每天会多一次模型调用，用量会变成一条稳定曲线。
6.1 用量视角：模型调用和天气 API 分开看
模型通道的用量由 Agent 规划次数决定。用户每问一次天气，Agent 至少完成一次模型规划；如果启用了多轮工具调用，可能一次对话产生多次模型请求。Cron 推送每天触发一次规划，也会计入模型用量。天气 API 的用量由 Skill 实际请求次数决定，缓存命中时不会请求天气服务商。你可以通过调大缓存 TTL 降低天气 API 用量，但模型规划次数不会因此减少。
排障时也要分开看。控制台没有模型调用记录，说明请求没走 TaoToken，查 openclaw.json。天气服务商后台没有请求记录，说明 Skill 用了缓存或没执行，查 .cache.json 和执行日志。混在一起看，容易把缓存命中误判成“模型通道没记账”。
6.2 下一步：模型对话、创建 Key、Coding Plan
模型通道和天气 Skill 都跑通后，建议做三件事。第一，在 TaoToken 模型对话 里用同一把 Key 发一条测试消息，确认模型 ID 和 Base URL 没填错。第二，如果后面要长期跑 OpenClaw 的定时推送和开发调试，在 Coding Plan 看一眼套餐是否够用。第三，Key 统一在 控制台 API Keys 创建和管理，方便按用途拆分。
如果天气 API 有免费额度限制，别把 WEATHER_API_KEY 写进 SKILL.md 或代码注释里，继续留在 ~/.openclaw/.env，用 ${WEATHER_API_KEY} 引用。模型通道的 Key 也一样，只放在 ~/.openclaw/.env，由 openclaw.json 引用。跑通一次“上海天气怎么样”只是开始，把 Key、Base URL、模型 ID 和用量记录固定成可复用的配置，后面加城市、加单位偏好、加每日推送才不会乱。
