1. 为什么 Agent Skills 值得折腾：从“只会聊天”到“能干活”
OpenClaw 和 Hermes Agent 这两套智能体框架，最近在开发者圈子里讨论度很高。它们真正拉开差距的地方不是模型本身，而是 Agent Skills 这套扩展机制。简单说，Skills 就是一份符合规范的 Markdown 文件（核心是 SKILL.md），里面写清楚触发条件、执行步骤、参数配置和异常处理。智能体在对话中匹配到对应场景时，会自动加载并执行这个技能，从而实现“一句话完成复杂任务”。
我拿一个实际场景举例。你对着智能体说“帮我把当前目录下所有 .log 文件按日期归档并压缩”，如果没装文件处理类 Skill，它只能给你一段示例代码让你自己跑；装了对应 Skill 之后，它会直接列出文件、询问命名规则、执行重命名和压缩、最后反馈结果。这个差别就是“聊天机器人”和“能干活的助手”之间的分水岭。
OpenClaw 和 Hermes 采用的是统一的 Skills 规范，这意味着二者技能基本可以互通。OpenClaw 支持全局技能和项目局部技能，适合多项目切换；Hermes 统一用全局技能目录，加载更简洁，还支持智能体自主生成并保存新技能。对于想用 CLI 快速扩展智能体能力的开发者来说，掌握 SKILL.md 的目录结构和安装命令，是绕不开的一步。
这篇教程面向的是已经装好 OpenClaw 或 Hermes、想通过 CLI 和手动方式扩展技能的人。我会把 SKILL.md 的目录结构、CLI 安装命令、统一 Key/API 通道配置、安装后的加载验证，以及常见报错排查都串一遍。尤其是需要 API Key 的技能（搜索、绘图、文档解析），我会给出用 TaoToken 统一 Key 通道的配置示例，避免你在多个平台之间反复切换密钥。
先说清楚一个前提：Skills 本身不绑定任何特定模型服务。但很多实用技能（联网搜索、AI 绘图、文档总结）在运行时需要调用外部 API。如果你每个技能都单独配一套 Key，管理成本会很高。统一 Key 通道的价值就在这里——一个 Base URL、一个 Key、一个 Model ID，就能让多个技能共用同一套调用入口。下面进入环境校验和目录梳理。
2. 前置准备：OpenClaw 与 Hermes 环境校验及 SKILL.md 目录结构
在装任何技能之前，先把两套环境校验一遍，同时记住各自的技能默认目录。这一步做扎实，后面 90% 的“技能不生效”问题都能避免。以下步骤适配 Windows、WSL、Linux、macOS。
先校验 OpenClaw。打开终端（Windows 用 CMD/PowerShell，Linux/macOS/WSL 用终端），执行：
openclaw --version能正常显示版本号就说明安装成功。OpenClaw 的默认技能目录分两种：
全局技能（所有项目生效）：Windows 为C:\Users\用户名\.openclaw\workspace\skills；Linux/macOS/WSL 为~/.openclaw/workspace/skills。
项目局部技能（仅当前项目生效）：在项目根目录新建.openclaw/skills文件夹即可。
再校验 Hermes：
hermes --version如果提示找不到命令，说明没装或环境变量没刷新。Hermes 官方一键安装脚本适配 WSL、Linux、macOS：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash source ~/.bashrcHermes 默认技能目录是~/.hermes/skills，Windows 在用户目录下找对应文件夹。它统一采用全局技能目录，不区分项目局部，加载逻辑更简单。
接下来是 SKILL.md 的目录结构，这是整个 Skills 体系的核心。一个合法的技能文件夹，结构必须是这样：
my-skill/ ├── SKILL.md # 必须在一级目录，不能嵌套 ├── config.yaml # 可选，技能参数配置 ├── README.md # 可选，使用说明 └── scripts/ # 可选，技能依赖的脚本SKILL.md 的头部元信息用 YAML front matter 写，格式必须严格：
--- name: file-batch-rename description: 批量重命名当前目录指定后缀的文件，支持自定义命名规则 --- ## 使用场景 当用户需要批量修改当前目录下指定后缀（如 .txt、.jpg）的文件名时，自动调用该技能。 ## 执行流程 1. 列出当前目录下所有文件，筛选出符合用户指定后缀的文件； 2. 询问用户自定义命名规则（如前缀+序号）； 3. 按照规则拼接新文件名，执行重命名操作； 4. 反馈重命名结果，提示是否完成。 ## 注意事项 1. 禁止修改系统隐藏文件和重要配置文件； 2. 重命名前会自动备份原文件名，避免误操作； 3. 仅支持当前目录下的文件，不包含子目录。这里有个高频坑：SKILL.md 必须在技能文件夹的一级目录。如果你解压后得到的是skill-folder/sub-folder/SKILL.md，智能体是识别不到的。另外头部元信息的---不能缺行、不能写错符号，name和description两个字段是必填的。
提示：OpenClaw 和 Hermes 的技能格式完全通用。你在 OpenClaw 里写好的自定义技能，直接复制到
~/.hermes/skills就能用，不需要改任何内容。
环境校验和目录结构确认完之后，就可以进入实际的安装环节了。下面先讲 OpenClaw 的四种安装方式，再讲 Hermes 的三种，最后给出统一 Key 通道的配置。
3. 可复制配置：OpenClaw 与 Hermes 的 CLI 安装命令与统一 Key 通道
这一节是整篇教程的操作核心。我会把 OpenClaw 和 Hermes 的 CLI 安装命令、手动离线安装步骤，以及需要 API Key 的技能如何接入 TaoToken 统一通道，全部写成可直接复制的形式。
先看 OpenClaw 的 CLI 安装。适用于未上架 ClawHub、自定义 Fork 改版的技能，可直接从 GitHub 仓库拉取：
# 直接拉取 GitHub 仓库安装 openclaw skill install --github https://github.com/xxx/xxx-skill # 指定分支/版本安装 openclaw skill install --github 仓库地址 --ref v1.0.0 # 私有仓库安装（携带 Token 授权） openclaw skill install --github 私有仓库地址 --token ghp_xxxx追加--global参数可安装为全局技能，不加则仅当前项目可用。安装完成后用clawhub list查看已装技能列表。
国内网络访问 GitHub 或 ClawHub 时容易触发限流，手动离线安装是最稳的方式。下载技能压缩包后解压，确认 SKILL.md 在一级目录，然后把整个文件夹复制到~/.openclaw/workspace/skills（全局）或项目根目录的.openclaw/skills（局部）。不需要执行任何命令，新建对话后智能体会自动识别。
再看 Hermes 的 CLI 安装，它内置技能仓库，命令更简洁：
# 浏览官方技能仓库 hermes skills browse # 关键词搜索技能 hermes skills search web # 安装官方内置技能 hermes skills install official/web-search # 从 GitHub 仓库直接拉取 hermes skills install github:用户名/仓库名 # 查看技能详情 hermes skills show web-search # 列出本机已安装技能 hermes skills list # 更新指定技能 hermes skills update 技能名 # 卸载指定技能 hermes skills remove 技能名手动拖拽安装同样适用：下载或克隆技能仓库，解压后确保根目录有 SKILL.md，复制到~/.hermes/skills，重启 Hermes 会话即可。
现在到了关键部分——需要 API Key 的技能怎么配。像 web-search、AI 绘图、document-summary 这类技能，运行时需要调用外部模型服务。如果你每个技能单独配 Key，管理起来很麻烦。用 TaoToken 统一 Key 通道，一个 Base URL、一个 Key、一个 Model ID 就能覆盖多个技能。
先获取 Key。访问 TaoToken 的 API Keys 管理页面（https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite），创建一个新 Key 并复制保存。然后配置到 OpenClaw 的openclaw.json：
{ "skills": { "web-search": { "apiKey": "你的TaoToken Key", "baseUrl": "https://taotoken.net/api", "model": "gpt-4o-mini" }, "document-summary": { "apiKey": "你的TaoToken Key", "baseUrl": "https://taotoken.net/api", "model": "claude-3-5-sonnet" } } }Hermes 的配置写在~/.hermes/config.yaml：
skills: web-search: api_key: "你的TaoToken Key" base_url: "https://taotoken.net/api" model: "gpt-4o-mini" document-summary: api_key: "你的TaoToken Key" base_url: "https://taotoken.net/api" model: "claude-3-5-sonnet"这里三件套必须写全：Base URL 填https://taotoken.net/api，Key 填你刚创建的，Model ID 按技能需求选。不同技能可以共用同一个 Key，只是 Model ID 按场景调整。比如搜索类技能用轻量模型就够，文档总结类可以用能力更强的模型。
注意：Base URL 不要带末尾斜杠，也不要加 UTM 参数。配置写完后保存，重启会话让配置生效。
如果你用的是 Claude Code 做技能开发，也可以通过环境变量接入：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="你的TaoToken Key"配置完成后，需要 API Key 的技能就能正常调用了。下面进入验证环节，确认技能真的加载成功。
4. 验证请求与成功结果：确认技能加载与调用生效
配置写完不代表技能就能用，必须做加载验证。这一节给出具体的验证命令和成功结果判断标准，帮你确认技能真的生效了。
第一步，确认技能列表里能看到目标技能。OpenClaw 执行：
clawhub list正常输出会列出所有已安装技能的名称、版本和来源。如果你刚手动复制了文件夹但列表里没有，说明路径不对或 SKILL.md 格式有问题。
Hermes 执行：
hermes skills list输出会显示技能名、状态和安装来源。状态显示active或loaded才算正常。
第二步，做一次实际调用验证。以 web-search 技能为例，在 OpenClaw 对话窗口输入：
/skills run web-search 帮我搜索 OpenClaw Agent Skills 的最新文档如果技能加载正常，你会看到智能体先输出技能触发提示，然后返回搜索结果。Hermes 里直接对话即可：
帮我搜索一下 Hermes Agent 的技能安装方式成功结果的特征是：智能体明确调用了技能（会显示技能名），返回内容包含实时信息而非训练数据里的旧内容。
第三步，验证需要 API Key 的技能。以 document-summary 为例，准备一个测试文档，然后发起调用：
帮我总结一下当前目录下 test.md 的核心内容如果 Key 通道配置正确，会返回文档摘要。如果报 401 或认证失败，回到上一节检查 Base URL 和 Key 是否写对。
我试过在 WSL 环境下同时跑 OpenClaw 和 Hermes，两个框架共用同一个 TaoToken Key，切换技能时不需要重新配密钥，这点确实省事。验证通过后，建议把配置备份一份：
cp -r ~/.openclaw ~/.openclaw_backup_$(date +%Y%m%d) cp -r ~/.hermes ~/.hermes_backup_$(date +%Y%m%d)如果你想把 OpenClaw 里积累的技能迁移到 Hermes，直接执行hermes init，系统会自动扫描 OpenClaw 默认技能目录并交互式导入。自动迁移失败时，手动复制~/.openclaw/workspace/skills里的文件夹到~/.hermes/skills即可，格式完全通用。
验证环节做完，基本就能确认技能可用了。但实际安装过程中，报错是常态。下一节把最常见的几类报错和排查方法整理出来。
5. 本篇常见错排查：401、local proxy failed、reading choices 与 OAuth 报错
安装和调用 Skills 的过程中，报错集中在几类。这一节按真实报错信息给出排查路径，你遇到时可以直接对照。
报错一：401 Unauthorized / invalid api key
这是需要 API Key 的技能最常见的报错。原因通常是 Key 写错、Base URL 写错，或者 Key 已失效。排查步骤：先确认openclaw.json或config.yaml里的apiKey字段没有多余空格；再确认 Base URL 是https://taotoken.net/api，不带末尾斜杠；最后去 TaoToken 控制台确认 Key 状态正常。如果三件套里 Model ID 写了一个不存在的模型名，也可能返回 401 或 404，建议先用模型对话页面（https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite）测试一下 Key 和模型是否可用。
报错二：local proxy failed / connection refused
这个报错通常出现在智能体尝试调用外部 API 时。原因可能是本地网络环境导致请求发不出去，或者配置文件里的 Base URL 指向了一个本地代理地址但代理没启动。排查时先检查配置文件里有没有残留的localhost或127.0.0.1地址，统一改成https://taotoken.net/api。另外确认终端能正常访问外网，可以用curl https://taotoken.net/api测试连通性。
报错三：reading choices / cannot read property 'choices' of undefined
这个报错说明 API 返回的数据结构不符合预期，智能体在解析choices字段时拿到了 undefined。常见原因是 Base URL 指向了一个不兼容 OpenAI 接口格式的服务，或者 Model ID 填错导致返回了错误信息。排查时确认 Base URL 是https://taotoken.net/api，Model ID 用标准名称如gpt-4o-mini、claude-3-5-sonnet。如果技能本身对返回格式有特殊要求，查看技能文件夹里的 README.md 确认兼容性。
报错四：OAuth token expired / authentication failed
部分技能（如 GitHub 操作类）需要 OAuth 授权。报错说明 token 过期或授权范围不足。排查时重新执行授权流程，或者改用 Personal Access Token 方式。如果技能配置里同时有 OAuth 和 API Key 两套认证，确认当前用的是哪一套，避免混用。
报错五：技能不生效，智能体识别不到
这是最高频的问题，核心原因就三个：SKILL.md 嵌套在子文件夹里、头部元信息格式错误、没重启会话。排查时先确认技能文件夹/SKILL.md是一级结构，再检查---包裹的 YAML 头部有没有缺字段，最后关闭当前对话新建会话。如果还不行，执行openclaw skills verify @author/skill做格式校验。
报错六：Rate limit exceeded
国内网络访问 GitHub 或 ClawHub 频率过高触发限流。解决方案是放弃 CLI 安装，改用手动离线安装，下载压缩包后解压放入对应目录，彻底避开限流。
提示：遇到报错时，先看终端输出的完整错误信息，不要只看最后一行。很多报错的根因在更早的日志里。
排错做完，技能基本就能稳定运行了。最后说一下长期使用和批量管理的思路。
6. 长期编码与 Agent 扩展：用 Coding Plan 统一管理技能调用
当你装的技能越来越多，尤其是涉及代码审查、自动化部署、批量文件处理这类长期运行的任务时，按次调用模型的方式在成本和稳定性上都不太划算。这时候可以考虑用 Coding Plan 来统一管理技能背后的模型调用。
Coding Plan 的思路是：把技能需要的模型调用集中到一个套餐里，多个技能共用额度，不用每个技能单独充值。对于需要频繁调用模型的技能（比如代码审查、文档总结、联网搜索），这种方式能明显降低管理成本。配置方式也很简单，在 TaoToken 控制台开通 Coding Plan 后，把技能配置里的 Key 换成套餐对应的 Key 即可，Base URL 和 Model ID 保持不变。
具体操作路径：访问 Coding Plan 页面（https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite），选择合适的套餐，开通后复制新的 Key，替换掉openclaw.json或config.yaml里的apiKey字段。其他配置不用动。
如果你是用 Claude Code 做技能开发，接入方式也一样：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="你的Coding Plan Key"然后在 Claude Code 里正常开发技能，调用会自动走统一通道。这样你在 OpenClaw、Hermes、Claude Code 三个环境里可以用同一套 Key 体系，技能迁移时不需要重新配密钥。
对于团队协作场景，建议把技能配置和 Key 管理分开。技能文件夹可以提交到 Git 仓库共享，Key 通过环境变量注入，避免密钥泄露。OpenClaw 支持在openclaw.json里用${ENV_VAR}形式引用环境变量，Hermes 的config.yaml也支持类似写法。
最后给一个实用建议：定期执行hermes skills update --all和clawhub list检查技能更新，尤其是涉及 API 调用的技能，接口格式可能会有变化。更新前先备份配置，更新后跑一次验证请求，确认技能仍然正常工作。这样你的智能体能力才能持续稳定地扩展下去。
