企业官网建设流程全解析

1. 为什么你的 Agent 总是“从零开始”

如果你最近在折腾 QClaw 这类 Agent 工具，大概率遇到过这种场景：每次开新会话，都要把同一套背景、同一套输出格式、同一套操作流程重新讲一遍。上周调好的“周报生成逻辑”，这周换个窗口就失效了；昨天写好的“日志分析步骤”，今天让 Agent 做又跑偏了。问题不在于模型笨，而在于你把能力存在了对话里，而不是存在了技能库里。

QClaw Skills 技能库要解决的就是这件事。它把零散的能力沉淀成一个个带SKILL.md的目录，Agent 启动时扫描技能库，按需加载对应技能，再按技能里定义的流程执行。你可以把它理解成给 Agent 装了一套“可插拔的操作手册”：手册写清楚什么时候用、怎么用、输出什么格式，Agent 负责照着做。适合谁？适合已经在用 QClaw 做自动化、但每次都要重复交代上下文的人；也适合想把团队内部流程固化成 Agent 能力、让多人复用的开发者。

这篇不聊概念，直接落地。我会从SKILL.md的结构讲起，说清 Agent 怎么识别和调用技能，然后给你一套可复制的技能目录骨架、settings.json配置片段，最后用一次真实的加载验证动作，确认技能真的被 Agent 吃进去了。过程中涉及模型调用的部分，我会用 TaoToken 的 API 做演示，因为它的接入方式对 QClaw 这类工具比较友好，配置也简单。

2. TaoToken 前置准备：把模型通道先打通

QClaw 本身负责技能调度，但技能里如果涉及模型推理（比如内容生成、日志分析、摘要），就需要一个稳定的模型通道。我实测下来，TaoToken 的接入成本比较低，一个 API Key 就能覆盖多种模型，适合放在 QClaw 的settings.json里做统一出口。

先拿到 Key。打开官网https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=，注册后在控制台里创建 API Key。控制台地址是https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite，进去之后找到 API Keys 页面，新建一个 Key，复制出来。这个 Key 只显示一次，建议先存到本地环境变量里，别直接写死在代码里。

API 的基础地址是https://taotoken.net/api，注意这个地址不带 UTM 参数，是纯接口地址。QClaw 的技能配置里如果要填base_url，就填这个。模型名称按你实际用的填，比如claude-sonnet-4-20250514这类，具体以控制台里可选的为准。

提示：Key 不要提交到 Git。建议用.env文件或者系统环境变量管理，QClaw 的settings.json里用${TAOTOKEN_API_KEY}这种占位符引用。

如果你还没决定用哪个模型，可以先在模型对话页面试一下https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite，确认通道正常再写进技能配置。这一步花两分钟，能省掉后面排查“到底是技能没加载还是模型没通”的时间。

3. SKILL.md 结构：Agent 到底读什么

QClaw 的技能识别逻辑很直接：扫描技能库目录，找到每个子目录里的SKILL.md，解析 YAML front matter，拿到name、description、metadata三个关键字段，然后决定是否加载、何时加载。

一个标准的SKILL.md长这样：

--- name: log-analyzer description: 分析应用日志，提取错误堆栈、统计错误频次、给出修复建议 metadata: openclaw: emoji: "" always: false triggers: - "分析日志" - "log analysis" - "错误堆栈" --- # 日志分析技能 ## 使用场景 当用户提供日志文件路径或粘贴日志内容，需要定位错误、统计频次时使用。 ## 执行步骤 1. 读取日志文件，按行解析 2. 提取 ERROR、WARN 级别条目 3. 按错误类型聚合，统计出现次数 4. 对 Top 3 错误给出修复建议 ## 输出格式 - 错误类型表格（类型 / 次数 / 首次出现时间） - 修复建议列表

这里有几个点容易踩坑。name必须和目录名一致，QClaw 用目录名做索引，不一致会导致技能加载失败。description是 Agent 判断“要不要用这个技能”的主要依据，写得太泛（比如“处理文件”）会导致误触发，写得太窄又可能漏触发。我一般会把触发词直接写进description或者triggers里，让匹配更准。

always: true表示强制加载，适合qclaw-rules这种系统基础规则；普通技能设false，按需加载。emoji只是展示用，不影响功能，但加上之后在技能列表里更好认。

SKILL.md的正文部分不是给 Agent “读”的，而是给 Agent “执行”的参考。QClaw 会把正文作为上下文注入，所以步骤要写得可操作，别写“分析一下日志”这种模糊指令，要写“按行解析、提取 ERROR 级别、聚合统计”这种可执行动作。

4. 可复制的技能目录骨架与 settings.json 配置

先建目录。我习惯在项目根目录下建qclaw_skills/，每个技能一个子目录，目录名用英文小写加连字符。骨架如下：

qclaw_skills/ ├── README.md ├── qclaw-rules/ │ └── SKILL.md ├── log-analyzer/ │ └── SKILL.md ├── content-factory/ │ └── SKILL.md └── schedule-skill/ └── SKILL.md

qclaw-rules放系统基础规则，always: true；其余技能按需加载。每个SKILL.md按上一节的结构写，name和目录名保持一致。

然后是settings.json。QClaw 的技能库路径和模型通道都在这里配：

{ "skills": { "paths": [ "./qclaw_skills" ], "autoLoad": true, "maxSkills": 20 }, "model": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "model": "claude-sonnet-4-20250514" }, "agent": { "skillMatchMode": "description", "fallbackToAll": false } }

skills.paths支持多个路径，你可以把团队公共技能库和本地技能库分开配。autoLoad: true表示启动时自动扫描，maxSkills限制单次加载数量，避免上下文过长。skillMatchMode设成description，Agent 会根据description做语义匹配；如果设成all，就是全量加载，适合技能少但调用频繁的场景。

注意：baseUrl填https://taotoken.net/api，不要带末尾斜杠，也不要带 UTM 参数。apiKey用环境变量引用，别写明文。

配好之后，目录结构和配置文件就齐了。接下来做一次加载验证，确认 Agent 真的识别到了技能。

5. 加载验证：确认技能被 Agent 吃进去了

验证分两步：先确认技能库被扫描到，再确认技能被正确调用。

第一步，启动 QClaw 后，在对话里输入“列出当前可用技能”。如果配置正确，Agent 会返回技能列表，包含log-analyzer、content-factory这些名字。如果返回空，先检查skills.paths路径对不对，再检查每个SKILL.md的name是否和目录名一致。

第二步，触发一个具体技能。比如输入“帮我分析一下 ./logs/app.log 里的错误”。如果log-analyzer的description写得准，Agent 会自动匹配到这个技能，并按SKILL.md里的步骤执行：读取文件、提取 ERROR、聚合统计、输出表格。

我试过用一段模拟日志做验证，日志内容如下：

2026-03-22 10:01:23 ERROR [order-service] Timeout connecting to payment gateway 2026-03-22 10:02:11 WARN [order-service] Retry attempt 1 for order 8821 2026-03-22 10:03:45 ERROR [order-service] Timeout connecting to payment gateway 2026-03-22 10:05:02 ERROR [user-service] NullPointerException at UserController.java:88

Agent 返回的结果应该包含一个错误统计表，Timeout connecting to payment gateway出现 2 次，NullPointerException出现 1 次，并给出对应的修复建议。如果 Agent 没按技能走，而是自由发挥，说明技能没被加载，或者description匹配失败。

验证通过后，你可以把这次调用的日志留下来，作为技能库的“基线用例”。以后改了SKILL.md，用同样的输入跑一遍，对比输出是否一致，就能判断技能有没有被改坏。

6. 本篇常见错排查

技能不加载：最常见的原因是name和目录名不一致。QClaw 用目录名做索引，SKILL.md里的name只是展示用，但很多教程会写错。另一个原因是SKILL.md的 YAML front matter 格式错误，比如---没闭合、缩进用了 Tab。YAML 对缩进敏感，统一用两个空格。

技能误触发：description写得太泛，比如“处理数据”会匹配到大量无关请求。解决办法是把触发词写具体，或者在triggers里列明确的关键词。如果还是误触发，可以把skillMatchMode改成manual，手动指定技能。

模型调用失败：先确认baseUrl是https://taotoken.net/api，不带斜杠。再确认apiKey环境变量有没有生效，可以在终端里echo $TAOTOKEN_API_KEY看一下。如果返回 401，说明 Key 无效或没传对；如果返回 404，检查模型名称是否在控制台可选列表里。

上下文过长：技能加载太多会导致上下文超限。maxSkills设小一点，或者把不常用的技能从paths里移出去。always: true的技能只保留qclaw-rules一个，别什么都强制加载。

技能执行结果不稳定：SKILL.md正文里的步骤写得太模糊，Agent 每次理解不一样。把步骤拆成可执行动作，比如“读取文件”改成“用 read_file 工具读取指定路径”，“统计频次”改成“按错误类型分组计数”。步骤越具体，输出越稳定。

如果你在接入过程中遇到模型通道的问题，可以直接去 API Keys 页面重新生成一个 Key 试试：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite。接入文档在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite，里面有完整的参数说明和示例。长期做编码类 Agent 的话，可以看看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite，适合需要频繁调用模型的场景。

技能库这东西，一开始建的时候麻烦，但建好之后每加一个技能，Agent 的能力就沉淀一层。下次开新会话，不用再从头交代，Agent 自己会去技能库里找。