企业官网建设流程全解析

OpenClaw 的 Agent Skills 最容易踩的坑，不是 SKILL.md 写得不规范，而是模型通道没接上——TaoToken 要解决的也正是这一段。先把结论放前面：去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 拿一把 Key，再把 openclaw.json 里的 Base URL 填成 https://taotoken.net/api，技能才有机会被模型「看见」。很多人以为把 SKILL.md 丢进 skills 目录就算装好了，其实文件只是躺在磁盘上，真正决定它能不能被挑中的，是模型那一侧的通道是否通、模型 ID 是否对得上。这篇文章按加载链路走一遍：先拆开 SKILL.md 的两段式结构，再看 openclaw.json 里那两个总要自己拼的空位，最后给出可以直接抄的配置、验证方法和出错时的排查顺序。

1. 把 SKILL.md 丢进目录，OpenClaw 到底读到了什么

1.1 frontmatter 先上场，正文按需再读

Agent Skills 的加载是两段式的，理解这一点比记住任何配置项都重要。第一段发生在会话刚开始：OpenClaw 扫描技能目录，把每个 SKILL.md 顶部 frontmatter 里的name和description抽出来，拼进系统上下文。第二段发生在模型决定要用某个技能之后：这时候才把 SKILL.md 的正文读进来，正文里写了什么命令、什么步骤、输出格式要求是什么，模型此时才看得见。

这个两段式设计省的是 token。二十个技能的元数据加起来可能只有几百字，但二十个技能的完整正文动辄上万字，全部预加载纯属浪费。代价同样明显——description 是第一段唯一的筛选依据，写得含糊，模型在第一步就把你排除了，正文写得再工整也没有出场机会。

一个能跑的 SKILL.md，frontmatter 大概长这样：

--- name: weather-brief description: 查询指定城市的实时天气并给出穿衣、带伞建议。用户提到天气、气温、下雨、要不要带伞时使用。 ---

正文部分建议分成三块写清楚。第一块说明触发场景，用自然语言重复一遍 description 里的关键词；第二块写具体怎么做，把命令原样贴出来；第三块写输出要求，比如「两句话讲完，不要罗列原始数据」。中间那块的命令块单独长这样：

curl -s "https://wttr.in/Shanghai?format=3"

注意这条命令是在你自己的机器上执行的，网络不通、域名解析失败、命令不存在，报错都会原样回到对话里。SKILL.md 本身不负责执行，它只是把「该执行什么」告诉模型。

1.2 技能目录的层级和文件名，比内容更容易出错

目录结构上，OpenClaw 通常按skills/<技能名>/SKILL.md这一层来找。技能名建议和 frontmatter 里的name保持一致，全小写、用连字符分隔，避免空格和大小写混写。常见错误有三种：把 SKILL.md 直接放在 skills 根目录，而不是放进子目录；文件名写成skill.md、SKILL.md.txt、README.md；子目录名带空格或者中文。

另外要注意技能目录的解析顺序。项目内的./skills和用户目录下的~/.openclaw/skills如果同时存在同名技能，到底哪一份生效，取决于你本地版本的实现顺序。稳妥做法是同一个技能名只保留一份，改完文件后用一条明确的问句去验证，不要指望「两个都放总会有一个生效」。

技能数量也不用一上来就堆。先跑通一个，确认链路通了，再按需增加。一口气塞十个技能进去，最先出问题的往往不是技能本身，而是你自己都分不清是哪个环节没生效。

1.3 决定加载成败的其实是模型通道

文件层面全部正确之后，真正的关卡才出现。OpenClaw 要把 frontmatter 元数据送进模型、接收模型返回的「要不要用这个技能」、再把技能正文送进去让模型编排步骤——这三个动作全部经过同一个模型通道。通道不通，前面所有准备都是白做：模型收不到元数据，自然不会调用任何技能。

这就是为什么很多人遇到的现象是「技能明明写对了，AI 就是不用」。它不报错，也不提示，就是不用。因为模型压根没看到那段 description，或者看到的是被截断的版本。所以排查技能加载问题，顺序应该倒过来：先确认模型通道是通的、模型 ID 是存在的，再回头检查 SKILL.md 的写法。倒着查能省掉大量时间。

2. openclaw.json 里那两个总要自己拼的空位

2.1 官方示例留下的两个坑

OpenClaw 的初始配置文件里，model段通常是留空的，或者给一个明显是占位符的值：apiKey写着your-api-key-here，baseURL要么注释掉要么指向一个示例域名。官方这么做是合理的，它不知道你想用哪条通道；但对第一次上手的人来说，这两个空位就是全部问题的来源。

直接拿一个真实厂商的地址填进去，又会遇到第二层麻烦：模型名对不上、额度不好估算、换一个模型要改一次配置、几把 Key 分散在不同控制台里。技能这边只要动一次，模型那边就得跟着动，来回几次之后配置文件就变成了一团谁也不敢改的东西。

2.2 TaoToken 在这条链路里只做一件事：当模型通道

把baseURL指向 https://taotoken.net/api 之后，模型这一段就固定下来了。它是兼容通道的形式，协议按 OpenAI 那一套走，OpenClaw 不需要为它单独写适配器。需要换模型的时候，只改model字段，baseURL和apiKey都不用动。

关键要说清楚的是它的边界：TaoToken 只出现在模型通道这一层。SKILL.md 里的curl、wttr.in、你自己写的脚本命令，一个都不用改。技能文件长什么样，和你用哪条通道没有关系。有些教程会让人把命令里的地址也一起改掉，那纯粹是多余的——命令是给本机执行的，通道是给模型走请求的，两者在不同的层上。

2.3 provider 字段别乱填

provider一般保持openai-compatible这一类兼容标识，OpenClaw 会据此选择协议适配方式。如果你把它填成某个具体厂商的名字，OpenClaw 可能去找一个不存在的适配器，然后在一堆技能加载日志里报一个和模型无关的错，你按技能去查会查半天。

同一份配置里只保留一个 model 段。有些版本的配置文件允许定义多个 provider 再引用来引用去，能用是能用，但出问题时链长了两倍。单技能调试阶段，一个 provider、一条 baseURL、一把 Key，足够了。

3. 手把手改 openclaw.json

3.1 先创建 Key，再动配置文件

打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 注册登录，进控制台创建一把 API Key，复制出来先放在临时记事本里。同时去模型广场看一眼当前可用的模型 ID 列表，把准备用的那个记下来——注意是列表里实际存在的 ID，不是凭印象拼出来的名字。

这里有个习惯值得养成：给 Key 起一个能认出来的名字，比如openclaw-dev，以后在控制台看用量时能一眼分清是哪个工具在调用。Key 只在创建时完整展示，后面再看就是脱敏的了，复制时别多带换行和空格。

准备齐三样东西就可以动手了：一把 Key（下文统一写成YOUR_API_KEY）、一个 Base URL（https://taotoken.net/api）、一个模型 ID（以模型广场当时列表为准）。

3.2 openclaw.json 的最小可用配置

配置文件里和技能加载直接相关的其实就两块，model决定技能能不能被模型看到，skills决定文件从哪些目录被扫到：

{ "model": { "provider": "openai-compatible", "baseURL": "https://taotoken.net/api", "apiKey": "YOUR_API_KEY", "model": "YOUR_MODEL_ID" }, "skills": { "directories": ["./skills", "~/.openclaw/skills"] } }

如果你的 openclaw.json 里已经有model段，只改baseURL、apiKey、model三行即可，其余字段别碰。改完保存，重启 OpenClaw，让配置重新加载。

有一个细节必须强调：baseURL只填到https://taotoken.net/api，末尾不要加/v1。OpenClaw 自己会拼接后续路径，你多写一层，请求就打到/v1/v1/...上去，报错信息里通常看不出是这里的问题。另外，落地页那种带查询参数的链接是给人点的，不要整串贴进配置文件，配置文件里只认干净的接口地址。

3.3 逐字段核对一遍再启动

核对完这一轮再启动，能省掉大部分来回。特别是最后一行：./skills是相对路径，它相对于谁，取决于 OpenClaw 启动时的工作目录。拿不准就用绝对路径，别在这种地方跟自己较劲。

4. 跑起来验证：技能有没有被模型挑中

4.1 一条测试问句比看配置文件有用

配置保存、服务重启之后，别急着看日志，先在 OpenClaw 里发一条明确能命中技能的问句，比如「上海今天要带伞吗」。这条问句里同时出现了地点和「带伞」，正好落在 weather-brief 的 description 关键词上，是命中率最高的一种问法。

然后看回显。理想情况是：模型先说它要用天气简报这个技能，接着出现一次命令执行，打印出一行天气数据，最后给出两句话结论。整个过程中命令是你本机跑的，模型只是决定「要跑这条命令」并解读结果。

反过来，如果模型直接凭记忆答了一句「上海最近可能下雨，建议带伞」，没有任何命令执行痕迹，那基本可以判定技能没被加载或没被选中。这种答法看起来像成功，其实是最容易骗过自己的失败。

4.2 三段链路分开判断

把上面的流程拆成三段来看，定位会快很多。第一段是元数据有没有进上下文：把技能数量临时减到只剩一个，如果这时能命中，说明是技能之间互相干扰，不是通道问题。第二段是通道通不通：如果所有技能都不命中，而且普通提问也回答得很奇怪或者干脆报错，先怀疑通道。第三段是执行环节：模型说要跑命令、但输出是报错，那问题在命令本身，跟配置无关。

这三段各自独立，别混在一起改。一次只动一个变量，改完立刻用同一条问句复测。

4.3 去控制台对一下这次调用记上账没有

链路通了之后，回到 TaoToken 控制台 看一下调用记录。控制台里能看到刚才那条问句产生的请求，对着时间戳能确认走的就是 openclaw-dev 这把 Key。这一步的意义不在「看用量」，而在于确认你改的配置真的生效了——如果记录是空的，说明请求压根没发到你填的这条通道上，配置文件里大概率还留着别的地方没改。

顺手也能看到每次技能加载大概消耗多少 token。技能数量上来之后，这部分开销会变明显，元数据不是免费的，值得定期看一眼。

5. skills 没动静的时候，按这个顺序查

5.1 文件层面：目录、文件名、frontmatter

先确认三件事：SKILL.md 在不在skills/<技能名>/这个层级里；文件名是不是全大写的SKILL.md；frontmatter 有没有用三条短横线正确包起来。frontmatter 里如果name和description有一项缺失，元数据就是空的，模型看到的是半截信息，行为会变得很随机——有时用有时不用，最难查。

5.2 触发层面：description 写得太宽或者太窄

太宽的写法长这样：「帮助用户处理各种日常问题」。这句话放进上下文里几乎是噪音，模型无法判断什么时候该用它。太窄的写法是只写了一个生僻关键词，用户的自然问法根本碰不到。

一个实用的写法是把 description 写成「做什么 + 什么时候用」两段：前半句说能力，后半句列出用户可能说的几个词。上面那个天气技能就是这么写的，命中率明显比只写「查天气」高。

5.3 通道层面：Key 和 Base URL 先各看一眼

所有技能同时失效，而且普通对话也开始报鉴权相关的错，那就是通道层。先确认apiKey不是官方示例里的占位值，再确认baseURL是https://taotoken.net/api而不是别的地址、也没多写/v1。最后核对模型 ID：模型名不存在时报错通常很模糊，容易误判成技能问题，去模型广场对一遍就能排除。

5.4 执行层面：命令报错就贴回对话，不要在配置里找原因

如果模型确实调用了技能，但命令输出是command not found、超时、或者返回一段 HTML 错误页，这跟 openclaw.json 没有任何关系。把你本机的报错原样贴回对话，让模型下一步去换命令或者换参数。SKILL.md 里的命令写的是你本机环境的事实，环境不对，改配置文件是解决不了的。

6. 多技能共存时，别让 SKILL.md 互相打架

6.1 description 之间要有清晰边界

两个技能的 description 都提到「文件」这个词，模型在选择时就会摇摆：有时选 A、有时选 B、有时两个都调用一遍。这种问题不会报错，只会让输出变得不稳定。解决办法是在描述里写清楚处理对象的类型，比如一个专门写「批量重命名本地文件」，另一个写「整理 Markdown 文档结构」，边界一清二楚。

技能数量增长到十几个以后，建议隔一段时间回头读一遍所有 description，把重叠的合并，把已经废弃的删掉。元数据是每轮对话都要进上下文的，留着不用的技能就是在持续消耗预算。

6.2 技能变多之后，先把「常用」和「备用」分开

如果发现技能变多之后响应明显变慢，先检查是不是所有技能都挂在默认扫描目录里。可以把低频技能挪到另一个目录，只在需要时临时加进directories，用完再移出去。这比调任何参数都直接。

另外，技能的正文别写成操作手册，写清楚最小执行路径就够了。正文越长，被模型读进来之后占的上下文越多，留给实际任务的余量就越少。

7. 配通之后，下一步去哪

技能加载跑通只是第一步，接下来通常是三件小事。想先用同一把 Key 在不改配置的情况下试试别的模型，可以打开 模型对话 发一条消息，确认模型 ID 和通道都没问题；日常写代码的量稳定下来之后，Coding Plan 里能看清配额够不够；要给别的工具或者新项目再开一把 Key，直接去 控制台 API Keys 创建，记得按用途命名。

如果你同时在用 Claude Code，环境变量那一套的对照表在 接入文档 里，字段名和这里的baseURL不一样，但填的地址是同一个。

最后留一句提醒：Agent Skills 真正的价值不在于技能数量，而在于每个技能的触发条件写得够不够准。通道配好之后，把精力放回 description 和正文上，收益比继续加技能大得多。