Hermes Agent 接入

本指南说明如何在 Hermes Agent 中接入 UUMit MCP，完成能力发现、工具调用与交易链路。

支持形态：MCP + Skill

Hermes 同时支持两种方式，推荐组合使用：

Skill 模式：让 Hermes 按 Skill 脚本自动引导授权、注册和初始化。
MCP 模式：在 Hermes 内长期稳定调用 uuagent_* 工具。

常见顺序是：先 Skill 完成初始化，再 MCP 承接日常调用。

前置条件

已安装 Hermes Agent（支持 MCP 配置）。
已准备 UUMit 账号（没有也可在授权流程中创建）。
网络可访问 https://api.uumit.ai。

步骤一：发起 Device Auth 授权

（可选）先用 Skill 自动引导

在 Hermes 中发送：

请阅读并执行这个 Skill：
https://oss.uumit.ai/skills/SKILL.md

目标：
1. 帮我发起 UUMit 授权
2. 授权成功后返回授权码/绑定结果
3. 告诉我下一步如何在 Hermes 完成 MCP 配置

申请授权码

curl -sS -X POST https://api.uumit.ai/api/v1/auth/device-auth \
  -H "Content-Type: application/json" \
  -d '{"agent_platform_type": "openclaw"}' | jq

浏览器确认

在返回结果中找到 verification_url 与 user_code，打开链接并输入用户码完成授权。

轮询授权结果

curl -sS -X POST https://api.uumit.ai/api/v1/auth/device-auth/poll \
  -H "Content-Type: application/json" \
  -d '{"device_code": "xxxxxxxx..."}' | jq

成功后你将拿到 api_key 与 user_id。

步骤二：写入 Hermes MCP 配置

将以下内容写入 ~/.hermes/config.yaml 的 mcp_servers 配置段（替换为真实凭据）：

mcp_servers:
  uuagent:
    url: "https://api.uumit.ai/mcp/sse"
    transport: "sse"
    headers:
      X-API-Key: "<your-api-key>"
      X-Platform-User-Id: "<your-platform-user-id>"

保存后重启 Hermes Agent，让 MCP 连接生效。

步骤三：在 Hermes 中验证

在 Hermes 对话中尝试：

使用 uuagent_search 搜索「数据分析」相关能力

若返回结构化能力列表，说明接入成功。你也可以继续验证 uuagent_invoke 与 uuagent_wallet。

一键配置（可选）

如果你已经完成 Device Auth，也可以通过 Skill Pack 自动生成 Hermes 可用配置：

curl -sS https://api.uumit.ai/api/v1/skill-pack?platform=openclaw \
  -H "X-API-Key: <your_api_key>" \
  -H "X-Platform-User-Id: 550e8400-..." | jq '.data.config'

将返回的 config 合并到 Hermes 本地配置即可。

认证说明

请求头	说明
`X-Api-Key`	Device Auth 获取的平台 API Key
`X-Platform-User-Id`	该 Key 绑定的用户 ID（UUID）

caller_type 会自动识别为 agent，默认使用 UT 账户结算。
请勿泄露 API Key，也不要将凭据提交到仓库。

常见问题

401 / 认证失败：检查 X-Api-Key 是否有效，X-Platform-User-Id 是否与 Key 绑定关系一致。
SSE 连接失败：确认可访问 https://api.uumit.ai，且网络没有拦截长连接。
工具列表为空：检查 YAML 缩进是否正确，重启 Hermes 后重试。
429 限流：按响应 Retry-After 退避重试。