1. 为什么要把 Skills、Plugins、Gateway 放在一起配很多人第一次搭 Hermes Agent会把它当成一个「能调工具的聊天脚本」装好依赖、填个 API Key、跑起来能对话就算完事。但真正用起来你会发现决定它好不好用的不是主循环而是三个外围系统——Skills、Plugins、Gateway。Skills 决定 Agent「知不知道怎么做一件事」Plugins 决定「系统本身能不能被扩展」Gateway 决定「用户从哪个入口连进来」。这三者如果配置链路是断的你会遇到很典型的现象技能索引扫不到、插件加载报错、Gateway 起来了但消息进不来。这篇就聚焦这三块的配置落地。核心思路是用 TaoToken 的统一 Key 和 API 通道把 Skills 的模型调用、Plugins 的 hook 触发、Gateway 的会话路由全部收敛到一套凭证上避免每个模块各配一份 Key、各写一份 base_url。最终交付的是可以直接复制的settings.json与config.toml骨架以及每一步的验证动作。适合已经在本地跑通 Hermes 基础对话、想进一步做二开或平台接入的人。下面所有配置都以本地单机为场景不涉及任何网络层特殊处理纯配置和代码层面。2. TaoToken 前置统一 Key 与 API 通道准备在动 Skills 和 Gateway 之前先把凭证层统一掉。Hermes 的多个模块都会发起模型请求如果每个模块单独配 Key后面排查问题会非常痛苦。TaoToken 在这里扮演的角色就是「一个 Key 覆盖所有模型调用入口」你只需要在控制台生成一次然后让各模块引用同一个环境变量。第一步去控制台创建 API Key。打开 https://taotoken.net/api-keys 登录后新建一个 Key复制出来。建议命名带上用途比如hermes-local方便后面区分。第二步把 Key 写进环境变量而不是硬编码进配置文件。Linux/macOS 下export TAOTOKEN_API_KEYsk-你的key echo export TAOTOKEN_API_KEYsk-你的key ~/.bashrcWindows PowerShell$env:TAOTOKEN_API_KEYsk-你的key [Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY,sk-你的key,User)第三步确认 API 基地址。Hermes 各模块统一走https://taotoken.net/api作为 base_url不要在每个模块里写不同的地址。你可以先用一条 curl 验证 Key 是否可用curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY返回模型列表就说明 Key 和通道都通了。这一步别跳过后面 Skills 加载失败、Gateway 会话超时很多都是因为 Key 没生效或者环境变量没被进程读到。如果你更习惯在网页里先试模型可以打开 https://taotoken.net/models 直接对话验证确认账号状态正常再往下走。3. 可复制配置settings.json 与 config.toml 骨架Hermes 的配置分两层settings.json管 Agent 运行时行为模型、技能目录、插件路径config.toml管 Gateway 和平台适配监听端口、会话路由、平台凭证。下面给的是最小可用骨架你可以直接复制后改路径。先看settings.json{ model: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, name: claude-sonnet-4-5, max_tokens: 8192, temperature: 0.3 }, skills: { enabled: true, directories: [ ~/.hermes/skills, ./.hermes/skills ], index_cache: ~/.hermes/cache/skill_index.json, progressive_disclosure: true }, plugins: { enabled: true, directories: [ ~/.hermes/plugins, ./.hermes/plugins ], entrypoint_group: hermes_agent.plugins, hooks: { pre_tool_call: true, post_tool_call: true, pre_llm_call: true, post_llm_call: true } }, memory: { backend: sqlite, path: ~/.hermes/memory.db } }几个关键点说明。api_key_env指向环境变量名而不是 Key 本身这样配置文件可以进版本库。skills.directories同时列了用户级和项目级Hermes 会按顺序扫描并合并索引。progressive_disclosure打开后技能只在需要时加载完整内容默认只给模型一个索引这对 token 消耗影响很大。plugins.hooks里列的是你要启用的生命周期插点先全开方便调试稳定后再按需关掉。再看config.toml这是 Gateway 的配置[gateway] enabled true host 127.0.0.1 port 8787 session_store ~/.hermes/gateway/sessions.db delivery_retry 3 delivery_backoff_ms 500 [gateway.api_server] enabled true path_prefix /v1 compat [chat_completions, responses] [gateway.platforms.webhook] enabled true secret_env HERMES_WEBHOOK_SECRET [gateway.routing] default_agent main session_key_strategy platform_channel_usersession_key_strategy决定会话怎么切分platform_channel_user表示同一平台同一频道同一用户算一个会话这是最常用的策略。api_server打开后Hermes 会对外暴露兼容 OpenAI 的接口Open WebUI、LobeChat 这类前端可以直接接进来。secret_env同样走环境变量别写明文。两个文件放好后目录结构大致是~/.hermes/ ├── settings.json ├── config.toml ├── skills/ │ └── github-pr-workflow/ │ └── SKILL.md ├── plugins/ │ └── my-plugin/ │ ├── plugin.yaml │ └── __init__.py ├── cache/ └── gateway/4. 验证请求从 Skills 索引到 Gateway 会话配置写完不算完要逐项验证。顺序建议是先验 Skills 索引再验 Plugins 加载最后验 Gateway 会话。先验 Skills。启动 Hermes 后在对话里让它列出技能/skills list如果返回的是空列表说明扫描路径不对或者SKILL.md的 frontmatter 格式有问题。一个合法的SKILL.md开头长这样--- name: github-pr-workflow description: 处理 GitHub PR 的创建、审查、合并流程 requires_toolsets: - git - github --- ## 使用条件 当用户提到 PR、pull request、代码审查时加载。 ## 操作步骤 1. 确认当前分支与目标分支 2. 生成 PR 描述 3. 调用 github 工具创建 PRrequires_toolsets是条件装配字段只有对应 toolset 可用时这个技能才会出现在索引里。验证单个技能能否加载/skills view github-pr-workflow能打印出完整内容就说明按需加载链路通了。再验 Plugins。写一个最小插件目录~/.hermes/plugins/hello-plugin/里面两个文件# plugin.yaml name: hello-plugin version: 0.1.0 entry: __init__# __init__.py def register(ctx): ctx.register_tool(hello_echo) def hello_echo(text: str) - str: return fecho: {text} ctx.register_hook(post_tool_call) def log_tool_call(payload): print(f[hello-plugin] tool called: {payload.get(tool)})启动后如果控制台打印了插件加载日志并且对话里能调用hello_echo说明插件注册和 hook 都生效了。最后验 Gateway。启动 gateway 进程hermes gateway --config ~/.hermes/config.toml然后用 curl 模拟一次 API Server 请求curl http://127.0.0.1:8787/v1/chat/completions \ -H Content-Type: application/json \ -d { model: hermes-agent, messages: [{role: user, content: 列出当前可用技能}] }返回里能看到模型回复并且回复内容里包含技能列表就说明 Gateway 的入站解析、会话构建、Agent 运行、出站格式化整条链路是通的。这一步成功之后你再接 Telegram、Discord 之类的平台适配器就只是换[gateway.platforms.*]段的事。5. 本篇常见错排查配置链路跑不通八成是下面几个问题。我按出现频率排一下。技能索引为空。先确认skills.directories里的路径存在且可读再检查SKILL.md的 frontmatter 是否用---正确包裹。YAML 对缩进敏感requires_toolsets下面用两个空格别用 Tab。如果路径里有~确认进程是以当前用户身份跑的否则~展开会指向别处。插件加载报 entrypoint 找不到。目录型插件必须有plugin.yaml且entry字段指向模块名__init__.py里必须有register(ctx)函数。如果是 pip 安装的插件确认hermes_agent.plugins这个 entrypoint group 在setup.py或pyproject.toml里注册了。Gateway 起来了但请求 401。检查TAOTOKEN_API_KEY是否被 gateway 进程继承。用systemd或supervisor托管时环境变量不会自动带过去需要在 service 文件里显式Environment或者用EnvironmentFile。验证方法是在 gateway 启动日志里看它读到的 base_url 和 key 前缀。会话串了或者每次都是新会话。这是session_key_strategy配错。如果你希望同一用户跨频道连续对话用platform_user如果希望按频道隔离用platform_channel。改完要清掉sessions.db里的旧记录否则旧 session_key 还在。hook 触发了但拿不到数据。不同 hook 的 payload 结构不一样pre_tool_call里有tool和argspost_llm_call里有response。先在 hook 里print(payload.keys())看一眼实际字段别照着文档猜。API Server 返回格式不对。compat字段决定暴露哪种兼容格式chat_completions和responses的响应结构不同。前端接进来如果解析失败先确认它期望的是哪种再对应调整。6. 后续怎么扩展这套配置配置跑通之后扩展方向其实很清晰。想增强业务知识就往~/.hermes/skills/里加技能目录每个技能一个文件夹SKILL.md写清楚使用条件和步骤附属的模板、脚本放templates/和scripts/子目录。技能数量多了之后建议用 Skills Hub 的 lock file 机制管理来源和版本避免不同来源的技能互相覆盖。想深度改系统能力就写插件。插件能注册工具、CLI 子命令、slash command还能替换 context engine。写的时候注意 hook 的执行顺序多个插件监听同一个 hook 时行为可能互相影响调试阶段建议一次只加一个插件。想做平台接入就在config.toml里加[gateway.platforms.*]段。每个平台的适配器实现不同但入站解析、会话构建、出站格式化这三段流程是一致的。接新平台时先用 webhook 平台验证消息能进来再换成真实平台凭证。如果你在配 Gateway 或者插件 hook 的时候卡住了可以直接去 https://taotoken.net/doc 翻接入文档里面有各模块的字段说明和示例。需要长期跑编码类 Agent 的话Coding Plan 那条线也值得看一下它和这套配置是兼容的。