1. Hermes Agent 自定义 Skill 开发从零到工程落地Hermes Agent 自定义 Skill 开发全流程与工程实践核心是把「一个能跑的函数」变成「一个能被 Agent 稳定调度、可测试、可发布的能力单元」。如果你正在用 Hermes Agent 做自动化任务很快会遇到一个绕不开的问题Skill 越写越多每个 Skill 都要调用外部大模型 APIKey 散落在各个脚本里换一个模型就要改一遍代码测试环境和生产环境还容易串。这篇就聚焦这条完整链路重点解决多 Skill 调用外部 API 时的 Key 管理与通道配置问题。适合谁看已经能写 Python 脚本、想让 Hermes Agent 帮你调度多个自定义能力的开发者或者团队里多人协作维护 Skill被 Key 管理搞烦的人。我会给出可复制的settings.json/config.toml骨架演示通过 TaoToken 统一 Key/API 通道接入 Skill 的配置步骤最后附一个验证动作启动 Agent 后触发 Skill 调用检查请求是否经统一通道成功返回。全程按「能跟着做」的标准写代码可以直接抄。2. 为什么 Skill 的 Key 管理会变成工程问题先说清楚问题本身。单个 Skill 调用外部 API 时最省事的写法是把 Key 写在脚本里# 反面教材不要这样写 API_KEY sk-xxxxxxxxxxxxxxxx BASE_URL https://some-endpoint/v1一个 Skill 这样写没问题但 Hermes Agent 的典型用法是挂载多个 Skill。假设你有code_review、doc_summary、log_analyze三个 Skill每个都调外部模型就会出现三种混乱第一Key 重复且分散。三个脚本三份 Key轮换一次要改三处漏一处就报 401。第二通道不统一。有的 Skill 走 A 通道有的走 B 通道出问题时你根本不知道请求打到哪去了。第三环境隔离缺失。本地调试用的 Key 不小心提交到仓库或者测试环境的 Skill 打到了生产通道。工程上的解法是「统一入口 分层配置」所有 Skill 的外部调用都指向同一个 API 通道Key 从环境变量或统一配置文件读取Skill 本身不关心底层是哪家模型。TaoToken 在这里扮演的就是这个统一通道的角色——它提供兼容 OpenAI 风格的 API 接口你只需要维护一份 Key 和一个 base_url所有 Skill 复用。注意Skill 脚本里永远不要出现明文 Key。哪怕只是本地调试也养成从环境变量读取的习惯否则迟早会出事。3. TaoToken 前置准备拿到统一 Key 和通道地址在写 Skill 之前先把统一通道准备好。这一步只做一次后面所有 Skill 都复用。打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在里面可以创建 API Key。创建完成后你会得到一串以sk-开头的密钥这就是所有 Skill 共用的统一 Key。API 的基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为base_url使用。它兼容 OpenAI 的/v1/chat/completions接口格式所以任何用 OpenAI SDK 或 requests 手写请求的 Skill 都能无缝接入。如果你还没想好具体用哪个模型可以先去模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试一下确认通道能正常返回再写进 Skill。Key 的详细管理入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。拿到 Key 之后先做一件事把它写进环境变量不要写进代码。# Linux / macOS写入 ~/.bashrc 或 ~/.zshrc export TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/api # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的密钥 $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api验证环境变量是否生效echo $TAOTOKEN_API_KEY # 应该输出你的密钥而不是空行4. Skill 工程结构settings.json 与 config.toml 骨架Hermes Agent 的 Skill 通常放在一个约定目录下每个 Skill 一个子目录。推荐的结构是这样hermes_skills/ ├── settings.json # 全局配置通道地址、默认模型 ├── config.toml # 项目级配置超时、重试、日志 ├── code_review/ │ ├── SKILL.md # Skill 定义触发条件、执行步骤 │ ├── main.py # 核心逻辑 │ └── requirements.txt ├── doc_summary/ │ ├── SKILL.md │ └── main.py └── shared/ └── llm_client.py # 统一客户端所有 Skill 复用关键设计是shared/llm_client.py所有 Skill 都通过它发请求Key 和 base_url 只在这里读一次。这样换通道、换 Key 只改一处。先看全局settings.json骨架{ llm: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, default_model: gpt-4o-mini, timeout_seconds: 60, max_retries: 3 }, skills: { code_review: { model: gpt-4o-mini, temperature: 0.2 }, doc_summary: { model: gpt-4o-mini, temperature: 0.5 } }, logging: { level: INFO, log_request: true } }注意api_key_env字段它存的是环境变量的名字不是 Key 本身。这样配置文件可以安全提交到仓库。再看config.toml用于放一些不适合放 JSON 的注释和分组# config.toml - Hermes Agent Skill 项目配置 [llm] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model gpt-4o-mini timeout_seconds 60 max_retries 3 [llm.retry] backoff exponential base_delay 1.0 max_delay 30.0 [logging] level INFO log_request true log_response false [security] mask_sensitive truelog_response false是有意为之响应里可能包含用户数据默认不落盘。mask_sensitive true保证日志里出现 Key 时被替换成***。5. 统一 LLM 客户端所有 Skill 复用的核心这是整篇文章最关键的代码。shared/llm_client.py负责读取配置、拼装请求、处理重试Skill 只需要调用一个方法。# shared/llm_client.py import os import json import time import logging from pathlib import Path from typing import Optional import requests logger logging.getLogger(hermes.llm) class LLMClient: 统一 LLM 客户端所有 Skill 复用同一通道 def __init__(self, config_path: Optional[str] None): self.config self._load_config(config_path) llm_cfg self.config[llm] self.base_url llm_cfg[base_url].rstrip(/) self.api_key os.environ.get(llm_cfg[api_key_env], ) if not self.api_key: raise RuntimeError( f环境变量 {llm_cfg[api_key_env]} 未设置请先配置统一 Key ) self.default_model llm_cfg[default_model] self.timeout llm_cfg.get(timeout_seconds, 60) self.max_retries llm_cfg.get(max_retries, 3) def _load_config(self, config_path: Optional[str]) - dict: if config_path is None: config_path Path(__file__).parent.parent / settings.json with open(config_path, r, encodingutf-8) as f: return json.load(f) def chat(self, messages: list, model: Optional[str] None, temperature: float 0.3) - str: 发送对话请求返回模型文本回复 url f{self.base_url}/v1/chat/completions headers { Authorization: fBearer {self.api_key}, Content-Type: application/json, } payload { model: model or self.default_model, messages: messages, temperature: temperature, } last_error None for attempt in range(1, self.max_retries 1): try: logger.info(请求通道 %s模型 %s第 %d 次, self.base_url, payload[model], attempt) resp requests.post( url, headersheaders, jsonpayload, timeoutself.timeout ) resp.raise_for_status() data resp.json() return data[choices][0][message][content] except requests.exceptions.HTTPError as e: status e.response.status_code if e.response else None if status and 400 status 500: # 4xx 不重试直接抛出 raise RuntimeError(f请求被拒绝 ({status}): {e}) from e last_error e except requests.exceptions.RequestException as e: last_error e if attempt self.max_retries: delay min(2 ** (attempt - 1), 30) logger.warning(第 %d 次失败%d 秒后重试, attempt, delay) time.sleep(delay) raise RuntimeError(f重试 {self.max_retries} 次仍失败: {last_error})这段代码有几个工程细节值得说。第一base_url从配置读不硬编码换通道只改settings.json。第二4xx 错误不重试因为参数错了重试也没用5xx 和网络错误才重试。第三指数退避避免打爆通道。第四日志里只打通道地址和模型名不打 Key。6. 写一个 Skill以代码审查为例有了统一客户端写 Skill 就简单了。每个 Skill 的main.py只关心自己的业务逻辑。# code_review/main.py import sys import json from pathlib import Path # 把 shared 目录加入路径 sys.path.insert(0, str(Path(__file__).parent.parent)) from shared.llm_client import LLMClient SYSTEM_PROMPT 你是一个代码审查助手。请审查用户提供的代码 指出潜在 bug、安全问题、可读性问题按严重程度排序 每条给出具体行号和修改建议。用中文回答。 def review_code(code: str, language: str python) - str: client LLMClient() messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: f语言{language}\n\n代码\n{code}}, ] return client.chat(messages, temperature0.2) def main(): if len(sys.argv) 2: print(json.dumps({error: 用法: python main.py code_file}, ensure_asciiFalse)) sys.exit(1) code_file sys.argv[1] with open(code_file, r, encodingutf-8) as f: code f.read() result review_code(code) print(json.dumps({success: True, review: result}, ensure_asciiFalse, indent2)) if __name__ __main__: main()对应的SKILL.md定义触发条件和执行步骤# 代码审查 Skill ## 概述 对 Python/JavaScript 代码执行静态审查识别 bug、安全问题和可读性问题。 ## 触发条件 当用户请求审查代码、检查代码质量、找代码问题时使用。 ## 执行步骤 ### 步骤一读取代码 1. 使用 read_file 读取用户指定的代码文件 2. 若文件超过 500 行分页读取 ### 步骤二调用审查 1. 执行 python code_review/main.py code_file 2. 脚本通过统一通道调用模型 ### 步骤三返回结果 1. 解析 JSON 输出 2. 向用户展示审查结果 ## 约束条件 - 不修改源代码文件 - 不将代码上传到统一通道以外的服务7. 验证请求确认走的是统一通道写完 Skill 后必须验证请求确实经过统一通道。最直接的方法是打开log_request看日志里的通道地址。先单独跑一次 Skillcd hermes_skills export TAOTOKEN_API_KEYsk-你的密钥 python code_review/main.py /tmp/test_code.py如果配置正确你会看到类似日志INFO hermes.llm: 请求通道 https://taotoken.net/api模型 gpt-4o-mini第 1 次然后返回 JSON 结果{ success: true, review: 第 3 行变量命名不符合 snake_case... }接着在 Hermes Agent 里触发。启动 Agent 后输入「帮我审查一下 /tmp/test_code.py」Agent 应该匹配到代码审查 Skill 并调用。观察 Agent 日志确认请求的 base_url 是https://taotoken.net/api而不是其他地址。如果你想更严格地验证可以在llm_client.py里临时加一行打印logger.info(实际请求 URL: %s, url)确认输出是https://taotoken.net/api/v1/chat/completions。这一步能排除「配置读错文件」这类隐蔽问题。提示验证阶段建议把log_request设为 true上线后可以关掉减少日志量。8. 本篇常见错误排查错误一401 Unauthorized。最常见的原因是环境变量没生效。检查echo $TAOTOKEN_API_KEY是否有输出。如果是在 IDE 里跑注意 IDE 可能没继承 shell 的环境变量需要在运行配置里单独设置。另一个原因是 Key 前后有空格复制时容易带上。错误二404 Not Found。通常是base_url拼错了。正确写法是https://taotoken.net/api然后代码里拼/v1/chat/completions。如果你在base_url里已经带了/v1就会变成/v1/v1/chat/completions。检查settings.json里的base_url字段。错误三Skill 之间 Key 不一致。如果某个 Skill 没走shared/llm_client.py而是自己写了请求就会出现「有的 Skill 能跑有的报 401」。排查方法是全局搜索Authorization和sk-确保只有llm_client.py里出现。错误四超时。长代码审查容易超时。把timeout_seconds调到 120同时在 Skill 里对超长输入做分块。分块逻辑放在 Skill 层不要放在客户端层因为不同 Skill 的分块策略不一样。错误五配置读错文件。LLMClient默认读settings.json但如果你从别的目录启动相对路径会失效。建议在LLMClient初始化时打印实际读取的配置路径确认无误。错误六重试把 4xx 也重试了。看llm_client.py里的判断4xx 必须直接抛出不重试。如果你改过这段代码确认400 status 500的分支还在。9. 长期编码与 Agent 场景的通道规划如果你打算长期用 Hermes Agent 跑编码类任务或者做多 Skill 协作的 Agent建议提前规划通道。单个 Skill 调试用按量计费就够了但 Agent 场景下请求量大、并发高用 Coding Plan 会更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。规划时注意三点。第一把settings.json里的default_model设成一个够用且便宜的模型特殊 Skill 在skills字段里单独覆盖。第二max_retries不要设太大Agent 场景下重试会放大延迟3 次足够。第三日志级别在开发期用 INFO生产期用 WARNING避免日志把磁盘写满。回到工程本质Skill 开发全流程里最容易被忽视的不是业务逻辑而是配置和通道管理。把 Key 收拢到一个客户端、把通道地址收拢到一个配置文件后面加多少 Skill 都不会乱。这套结构我试过在十几个 Skill 的项目里用换通道时只改了一行base_url其他代码一行没动。如果你在接入过程中遇到报错先去接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照接口格式再去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 确认 Key 状态。大部分问题都出在这两处。
