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/PowerShellLinux/macOS/WSL 用终端执行openclaw --version能正常显示版本号就说明安装成功。OpenClaw 的默认技能目录分两种全局技能所有项目生效Windows 为C:\Users\用户名\.openclaw\workspace\skillsLinux/macOS/WSL 为~/.openclaw/workspace/skills。项目局部技能仅当前项目生效在项目根目录新建.openclaw/skills文件夹即可。再校验 Hermeshermes --version如果提示找不到命令说明没装或环境变量没刷新。Hermes 官方一键安装脚本适配 WSL、Linux、macOScurl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash source ~/.bashrcHermes 默认技能目录是~/.hermes/skillsWindows 在用户目录下找对应文件夹。它统一采用全局技能目录不区分项目局部加载逻辑更简单。接下来是 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建一个新 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.yamlskills: 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/apiKey 填你刚创建的Model ID 按技能需求选。不同技能可以共用同一个 Key只是 Model ID 按场景调整。比如搜索类技能用轻量模型就够文档总结类可以用能力更强的模型。注意Base URL 不要带末尾斜杠也不要加 UTM 参数。配置写完后保存重启会话让配置生效。如果你用的是 Claude Code 做技能开发也可以通过环境变量接入export ANTHROPIC_BASE_URLhttps://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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite测试一下 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/apiModel 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite选择合适的套餐开通后复制新的 Key替换掉openclaw.json或config.yaml里的apiKey字段。其他配置不用动。如果你是用 Claude Code 做技能开发接入方式也一样export ANTHROPIC_BASE_URLhttps://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 调用的技能接口格式可能会有变化。更新前先备份配置更新后跑一次验证请求确认技能仍然正常工作。这样你的智能体能力才能持续稳定地扩展下去。