openclaw 下的 skills 为什么是 markdown 文件？从配置骨架到验证动作一次讲清

1. 为什么 openclaw 的 skills 是 markdown 文件openclaw 里的 skills 目录下你看到的不是.json、不是.yaml而是一堆.md文件。这个设计第一次见会觉得奇怪技能配置不应该是结构化数据吗怎么用起文档格式了但如果你自己写过 Agent 的 prompt 编排就会明白这不是偷懒而是一个相当务实的工程取舍。skill 的本质是「一段给模型看的指令 一组可调用的工具声明 若干示例」这三样东西 90% 以上都是自然语言用 JSON 硬包反而处处别扭。这篇面向的是在本地 AI 工具链里管理技能配置的开发者你可能已经在用 openclaw 跑本地 Agent想把重复的 prompt 逻辑抽成 skill或者团队里有人要维护这些技能文件。我会先讲清楚 markdown 作为技能载体的真实原因然后给出一份可以直接复制的config.toml/settings.json骨架再通过 TaoToken 的统一 Key 和 API 通道把模型请求接进来最后用具体命令验证 skills 到底有没有被加载生效。整套流程可以复现踩坑点我也会标出来。需要先明确一点markdown 不是「高级格式」它只是恰好同时满足了可读性、模型理解稳定性和版本协作三个需求。理解这一点后面配置才不会拧着来。2. TaoToken 前置统一 Key 与 API 通道在验证 skills 加载之前得先让 openclaw 能真正发出模型请求。openclaw 本身是编排层它不提供模型你需要给它一个兼容 OpenAI 协议的 API 入口。TaoToken 在这里的角色就是统一通道一个 Key、一个 base_url就能把对话模型和编码类模型都接进来不用在多个供应商之间来回切换配置。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址后面不加任何查询参数直接作为 base_url 使用即可。操作顺序建议这样先注册账号然后进控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建完把 Key 复制出来形如sk-开头的一串字符先存到环境变量里不要直接写进会提交到 git 的配置文件。export TAOTOKEN_API_KEYsk-你的key如果你只是想先确认模型通不通可以打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 手动发一条消息确认账号和额度正常。这一步能省掉后面很多「到底是 skill 没加载还是 Key 没配好」的扯皮。注意Key 属于凭证写进settings.json时建议用环境变量引用而不是明文粘贴。openclaw 读取配置时支持${TAOTOKEN_API_KEY}这种占位写法。3. 可复制配置config.toml 与 settings.json 骨架openclaw 的配置分两层一层是运行时的config.toml管模型通道和全局参数一层是settings.json管 skills 目录、加载策略这些。下面这份骨架可以直接抄改掉路径和 Key 引用就能跑。先看config.toml# ~/.openclaw/config.toml [model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} default_model gpt-4o-mini timeout_seconds 60 [agent] max_tool_rounds 8 system_prompt_file ./prompts/system.md [skills] enabled true root ./skills loader markdown watch true几个参数说明一下。base_url固定指向 TaoToken 的 API 入口不要带尾斜杠之外的路径。default_model可以先填一个便宜的模型做加载验证确认链路通了再换成你实际要用的。skills.loader markdown是显式声明用 markdown 解析器虽然默认也是它但写出来方便排查。watch true让 openclaw 监听 skills 目录变化改完.md不用重启进程。再看settings.json{ skills: { root: ./skills, include: [**/*.md], exclude: [**/_draft_*.md, **/README.md], max_skills_loaded: 30, routing: { mode: metadata-first, metadata_file: ./skills/_index.json } }, logging: { level: debug, skill_trace: true } }这里有两个关键点。max_skills_loaded设成 30 不是随便写的skill 数量一多模型选错工具的概率会明显上升这个后面排障章节会展开。routing.mode metadata-first表示先读轻量元数据做路由命中后再加载完整 markdown避免一次性把所有 skill 塞进 context。一个 skill 文件长这样放在./skills/sql_query.md# Skill: SQL Query ## Description 根据用户自然语言问题生成并执行 SQL 查询。 ## When to use 用户提出涉及数据库检索、统计、筛选的请求时使用。 ## Steps 1. 解析用户意图确认目标表与字段 2. 生成 SQL 语句 3. 调用 sql_tool 执行 4. 将结果整理为自然语言返回 ## Tools - sql_tool - db_schema结构就是标题、描述、触发条件、步骤、工具列表。模型读这种层级化文本比读嵌套 JSON 稳定得多因为它在训练数据里见过海量类似的 markdown 文档。4. 验证请求确认 skills 加载生效配置写完最怕的是「以为加载了其实没有」。openclaw 提供了几个验证入口按顺序走一遍。第一步检查配置解析是否通过openclaw config validate --config ~/.openclaw/config.toml正常输出会列出解析到的 model provider 和 skills root。如果这里报api_key not resolved说明环境变量没导出回到上一步export一次。第二步列出已加载的 skillsopenclaw skills list --verbose期望看到类似输出[skills] root./skills loadermarkdown [skills] loaded 3 skill(s): - sql_query (./skills/sql_query.md) tokens≈420 - web_search (./skills/web_search.md) tokens≈310 - summarize (./skills/summarize.md) tokens≈260 [skills] routingmetadata-first max30如果列表是空的八成是include的 glob 没匹配上或者文件不在root目录下。--verbose会把每个 skill 的 token 估算打出来方便你判断 context 占用。第三步发一条真实请求看 skill 有没有被路由命中openclaw run --input 帮我查一下上个月的订单总数 --trace--trace会打印路由决策过程。你会看到类似[trace] user input received [trace] routing: candidate skills [sql_query, summarize] [trace] selected skill sql_query (score0.87) [trace] loading ./skills/sql_query.md [trace] model call - https://taotoken.net/api [trace] tool call: sql_tool [trace] final answer generated看到selected skill sql_query和loading ./skills/sql_query.md这两行就说明 markdown skill 被正确加载并拼进了 prompt。如果model call那行报 401是 Key 的问题如果根本没出现routing行是 skills 没启用。第四步直接验证模型通道本身curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回里有choices字段就说明通道正常。这一步能把「模型问题」和「skill 问题」彻底分开。5. 本篇常见错排查skill 文件不生效list 里看不到。先确认文件扩展名是.md而不是.markdownopenclaw 默认只认.md。再检查settings.json里的includeglob**/*.md能匹配子目录*.md只匹配根目录。还有一点容易忽略文件名以下划线开头的会被exclude规则挡掉别用_test.md这种命名做正式 skill。skill 加载了但模型不调用。大概率是When to use写得含糊。模型靠这段判断该不该用这个 skill写「用于查询」不如写「用户提出涉及数据库检索、统计、筛选的请求时使用」。触发条件越具体路由越准。skill 数量一多就开始乱选工具。这是真实存在的现象不是玄学。当 skills 超过 30 个每个都往 prompt 里塞模型要在几十个候选里做决策选错的概率会陡增。解决办法就是配置里的metadata-first路由先用轻量元数据筛出 3 到 5 个候选再加载完整 markdown。如果你的 openclaw 版本还不支持就手动把max_skills_loaded调小把不常用的 skill 移出root目录。改了 markdown 但行为没变。检查watch true是否生效有些环境文件监听不工作需要手动重启。另外 openclaw 可能有 skill 缓存openclaw skills reload可以强制刷新。token 超限报错。用openclaw skills list --verbose看每个 skill 的 token 估算把超过 800 token 的 skill 拆成多个小文件或者把示例部分精简。markdown 可读性好但也容易写着写着就膨胀。401 / 403 报错。先跑上面那条 curl确认 Key 本身有效。如果 curl 通但 openclaw 不通检查config.toml里api_key的占位符有没有被正确解析以及base_url是不是写成了带/v1的完整路径——openclaw 会自己拼/v1/chat/completions你只填到https://taotoken.net/api就行。6. 接入与后续把 skills 跑通之后日常维护其实很轻改.md、看 trace、确认路由命中。如果你还在搭本地编码 Agent或者想让 skill 在长任务里持续生效可以走 Coding Plan 这条线配置方式在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的参数说明和示例。如果你用的是 Claude Code 那套工具链Anthropic 兼容入口在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite Key 和通道是同一套不用重复配置。最后留一个我自己的习惯每次新增 skill先只放一个跑--trace确认路由命中再批量加。一次性丢十个进去出问题你根本不知道是哪个的触发条件写歪了。