把 KNA 接入 Hermes Agent

Hermes Agent 是 Nous Research 出的 self-improving AI agent —— 自带学习闭环，能从经验创建技能、跨会话记忆、跑在 25+ 消息平台。GitHub: nousresearch/hermes-agent · 官网

核心原理：Hermes 原生支持 provider: anthropic + 自定义 base_url。KNA 是完全兼容的 Anthropic API gateway，所以 Hermes 调用 KNA 时用的还是 Anthropic 官方 SDK，零行代码改动。

0TL;DR（60 秒版）

# 1. 安装 Hermes
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.zshrc

# 2. 主模型用 Sonnet 4.6
hermes config set model.provider anthropic
hermes config set model.base_url https://code.wearekna.com/anthropic
hermes config set model.default claude-sonnet-4-6

# 3. 把 KNA Key 写进 .env（这一步是关键 — anthropic provider 不读 config.yaml 里的 api_key）
cat >> ~/.hermes/.env <<'EOF'
ANTHROPIC_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_BASE_URL=https://code.wearekna.com/anthropic
ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
EOF

# 4. 开聊
hermes

如果你要看完整流程、auxiliary 任务全配置、消息平台 daemon 重启、故障排查，往下读。

1前提条件

1.1 在 KNA 注册账号、拿 API Key

1. 打开 https://wearekna.com，点 立即注册
2. 邮箱注册（无需海外信用卡、无需手机号实名）
3. 登录到 https://code.wearekna.com/dashboard
4. 左侧 API 密钥 → 创建 Key → 命名「hermes-agent」→ 复制以 sk- 开头、共 67 字符（sk- + 64 位 hex）的 token
5. 充值（最低 ¥10，全场赠送 20%；推荐先充 ¥30 测试）

💡 首次充值建议 ¥30：到账约 $5 USD 余额，够跑约 250 万 Haiku tokens 或 33 万 Sonnet input tokens —— 足以验证 hermes 完整工作流。

1.2 系统支持矩阵

1.3 运行时

Hermes 用 Python 3.11+，安装脚本会自动装 uv。

2安装 Hermes Agent

2.1 一键安装（推荐）

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

完成后 reload shell：

source ~/.bashrc      # 用 bash
source ~/.zshrc       # 用 zsh（macOS 默认）

2.2 验证安装

hermes --version
hermes doctor

hermes doctor 会检查 Python、uv、依赖、配置目录等；正常输出全是 ✅。

3配置 KNA Key 进 Hermes

Hermes 的配置存在两个文件里：

• ~/.hermes/config.yaml — 非密钥配置
• ~/.hermes/.env — API Key 和敏感信息（自动从 config 分离，避免误传 GitHub）

方式 A · 交互式向导

hermes model

按提示：

1. Choose provider → 用箭头选 anthropic
2. Enter base URL → 填 https://code.wearekna.com/anthropic（末尾 /anthropic 不能省）
3. Enter API key → 粘贴你的 sk-xxxxxxxxxx... (67 字符)
4. Choose default model → 选 claude-sonnet-4-6

向导走完后仍需手动加 4 个 ANTHROPIC_* env 变量到 ~/.hermes/.env（见上方踩坑提醒）。

方式 B · CLI + .env（实测有效，推荐）

# 1. 主模型 metadata（写到 config.yaml）
hermes config set model.provider anthropic
hermes config set model.base_url https://code.wearekna.com/anthropic
hermes config set model.default claude-sonnet-4-6

# 2. 凭证写到 .env（这一步必做，否则 anthropic provider 拿不到 key）
cat >> ~/.hermes/.env <<'EOF'
ANTHROPIC_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_BASE_URL=https://code.wearekna.com/anthropic
ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
EOF

验证：

hermes config show | grep -A4 'Model:'
hermes doctor

410 个 auxiliary 任务配置（容易漏）

主模型配好不代表完事。Hermes 内部有 10 个辅助任务（压缩、视觉、标题生成、记忆 curator 等），每个都有自己的 provider 配置。如果不配，跑起来会看到一堆类似的警告：

⚠ No auxiliary LLM provider configured —
  context compression will drop middle turns without a summary.
⚠ Auxiliary title generation failed: No LLM provider configured for
  task=title_generation provider=auto. Run: hermes setup

这 10 个任务全部都需要单独配。最简洁的做法 —— 全部指到 KNA + Haiku（便宜 5 倍）：

KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
URL=https://code.wearekna.com/anthropic

for task in vision web_extract compression session_search skills_hub \
            approval mcp title_generation curator flush_memories; do
  hermes config set auxiliary.$task.provider anthropic
  hermes config set auxiliary.$task.model claude-haiku-4-5
  hermes config set auxiliary.$task.base_url $URL
  hermes config set auxiliary.$task.api_key $KEY
done

10 个 auxiliary 任务一览：

5KNA 支持的 Claude 模型

价格与 Anthropic 官方价 1:1，KNA 不加价、不预扣、不取整（见 wearekna.com 价格说明）。Anthropic 发新模型当天 KNA 同步支持。

6验证连接

6.1 用 Hermes 跑第一句话

hermes

进入 TUI 后输入：

你是哪个模型？请返回完整 model id。

正确响应应该自报为 Claude Sonnet 4.6 / Opus / Haiku。如果它说 GPT-X 或 Llama，说明配置走错 provider 了 —— 回头检查 model.provider。

6.2 用 curl 验证 KNA 端点本身工作

curl -s https://code.wearekna.com/anthropic/v1/messages \
  -H "x-api-key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 50,
    "messages": [{"role":"user","content":"返回三个字: 已验证"}]
  }' | jq '.model, .usage, .content[0].text'

6.3 验证 Hermes 真的打到了 KNA

KNA 在每个响应里加了 x-upstream: api.anthropic.com 和 x-passthrough: true 头：

curl -s -D - -o /dev/null -X POST https://code.wearekna.com/anthropic/v1/messages \
  -H "x-api-key: sk-xxxxxxxxxx... (67 字符)" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":5,"messages":[{"role":"user","content":"hi"}]}' \
  | grep -iE "x-upstream|x-passthrough"
# x-upstream: api.anthropic.com
# x-passthrough: true

7Gateway 守护进程（用 Telegram / Discord 必读）

如果你只用本地 TUI（hermes 命令），跳过本节。如果你要让 Hermes 在 Telegram / Discord / iMessage 上持续在线，得跑 gateway 守护进程：

hermes gateway setup    # 一次性配置 token / channel
hermes gateway start    # 启动 + 注册成系统服务（macOS launchd / Linux systemd）

7.1 macOS（launchd）

# 重启 gateway，新配置立即生效
launchctl kickstart -k gui/$(id -u)/ai.hermes.gateway

# 看启动日志
tail -f ~/.hermes/logs/gateway.log

正常输出会包含：

INFO gateway.run: Connecting to telegram...
INFO gateway.platforms.telegram: [Telegram] Connected to Telegram (polling mode)
INFO gateway.run: ✓ telegram connected
INFO gateway.run: Gateway running with 1 platform(s)

7.2 Linux（systemd user service）

systemctl --user restart hermes-gateway
systemctl --user status hermes-gateway
journalctl --user -u hermes-gateway -f

7.3 排错小技巧

• "Telegram bot token already in use" 错误：上一个 gateway 还活着，pkill -9 -f hermes_cli 后再 kickstart
• 改完 .env 不生效：gateway 必须重启，TUI 模式直接 /quit 再开就行
• 看不到 Telegram 消息：必须 DM 机器人或加群后被 @

8进阶 · 多模型策略

8.1 主模型 Sonnet + auxiliary Haiku（默认推荐）

主模型 + 10 个 auxiliary 已经在第 4 节配好。这是最佳性价比组合：贵的 Sonnet 用在真正对话，便宜的 Haiku 用在压缩 / 总结 / 标题等机械任务，整体省约 30%-50% 成本。

8.2 切到 Opus 跑复杂任务

Hermes TUI 里随时切：

/model claude-opus-4-7

这个 session 立刻用 Opus。下次启动还是 default。

8.3 同时用 KNA 和其他 provider

Hermes 支持多 provider 并存：

hermes model openrouter:x-ai/grok-4    # 临时切到 OpenRouter
hermes model anthropic:claude-sonnet-4-6   # 切回 KNA

8.4 Cron 调度任务

Hermes 内置 cron。每天早上 9 点跑一次：

hermes cron add "0 9 * * *" \
  --message "看 GitHub trending，挑 3 个 AI 项目总结发我 Telegram"

Cron 任务用 model.default。长跑任务持续消耗余额，建议 KNA dashboard 设余额低提醒邮件。

9常见问题

curl -fsSL https://code.wearekna.com/kna-doctor.sh | bash

# 清环境变量
unset ANTHROPIC_TOKEN CLAUDE_CODE_OAUTH_TOKEN

# 备份并移除本地凭据文件
[ -f ~/.claude/.credentials.json ] && mv ~/.claude/.credentials.json ~/.claude/.credentials.json.kna-bak
[ -f ~/.claude.json ] && mv ~/.claude.json ~/.claude.json.kna-bak

curl -sS https://code.wearekna.com/anthropic/v1/messages \
  -H "x-api-key: $(grep ANTHROPIC_API_KEY ~/.hermes/.env | cut -d= -f2)" \
  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":5,"messages":[{"role":"user","content":"hi"}]}'

hermes claw migrate

hermes config set model.base_url https://code.wearekna.com/anthropic
# 然后按方式 B 把 4 个 ANTHROPIC_* env 写到 .env

10数据流向

你的 Hermes Agent (本地 / VPS / Modal)
        │
        │ HTTPS, TLS 1.3
        ▼
   Cloudflare 边缘 (中国可达 CDN)
        │
        │ retention: 0 / logs: none
        ▼
   KNA 转发节点 (Tokyo, AS-Vultr)
        │
        │ retention: 0 / logs: metadata only (model, tokens, latency)
        │ 不缓存、不读取 prompt、不路由其他模型
        ▼
   api.anthropic.com (Anthropic 官方端点)
        │
        ▼
       Claude (Opus / Sonnet / Haiku)

KNA 全程零留存，仅记录账单 metadata（哪个 model、多少 token、多久）。prompt 与 completion 内容不落盘。详见 wearekna.com#notdo。

11故障排查 Checklist

按顺序检查：

• ☐ hermes doctor 全 ✅
• ☐ ~/.hermes/.env 同时有 4 个 ANTHROPIC_* 变量
• ☐ hermes config show 显示 provider: anthropic + base_url: https://code.wearekna.com/anthropic
• ☐ 第 4 节的 10 个 auxiliary 任务都已配（grep auxiliary ~/.hermes/config.yaml 应能看到全 10 个）
• ☐ curl 测试 KNA 端点能拿 200 响应（见 6.2 节）
• ☐ KNA dashboard 余额 ≥ $0.01、Key 状态 = 启用
• ☐ 改完配置后已重启 gateway（如果用 daemon 模式）
• ☐ 当前 IP 没被加入 KNA 黑名单（dashboard → IP 管理可见）

全过还是不通，邮件 info@wearekna.com，附上：

1. hermes doctor 输出
2. hermes config show（脱敏 API key）
3. 错误 stack trace 或 response body
4. Gateway 日志最后 50 行：tail -50 ~/.hermes/logs/gateway.log

附录 · 完整配置参考

~/.hermes/config.yaml（关键片段）

# 主模型
model:
  provider: anthropic
  base_url: https://code.wearekna.com/anthropic
  default: claude-sonnet-4-6

# 10 个 auxiliary 任务全部指到 KNA + Haiku
auxiliary:
  vision:           { provider: anthropic, model: claude-haiku-4-5, base_url: https://code.wearekna.com/anthropic, api_key: ${ANTHROPIC_API_KEY} }
  web_extract:      { provider: anthropic, model: claude-haiku-4-5, base_url: https://code.wearekna.com/anthropic, api_key: ${ANTHROPIC_API_KEY} }
  compression:      { provider: anthropic, model: claude-haiku-4-5, base_url: https://code.wearekna.com/anthropic, api_key: ${ANTHROPIC_API_KEY} }
  session_search:   { provider: anthropic, model: claude-haiku-4-5, base_url: https://code.wearekna.com/anthropic, api_key: ${ANTHROPIC_API_KEY} }
  skills_hub:       { provider: anthropic, model: claude-haiku-4-5, base_url: https://code.wearekna.com/anthropic, api_key: ${ANTHROPIC_API_KEY} }
  approval:         { provider: anthropic, model: claude-haiku-4-5, base_url: https://code.wearekna.com/anthropic, api_key: ${ANTHROPIC_API_KEY} }
  mcp:              { provider: anthropic, model: claude-haiku-4-5, base_url: https://code.wearekna.com/anthropic, api_key: ${ANTHROPIC_API_KEY} }
  title_generation: { provider: anthropic, model: claude-haiku-4-5, base_url: https://code.wearekna.com/anthropic, api_key: ${ANTHROPIC_API_KEY} }
  curator:          { provider: anthropic, model: claude-haiku-4-5, base_url: https://code.wearekna.com/anthropic, api_key: ${ANTHROPIC_API_KEY} }
  flush_memories:   { provider: anthropic, model: claude-haiku-4-5, base_url: https://code.wearekna.com/anthropic, api_key: ${ANTHROPIC_API_KEY} }

~/.hermes/.env（关键）

# anthropic provider 必须读 env 变量，4 个都写
ANTHROPIC_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_BASE_URL=https://code.wearekna.com/anthropic
ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

改完之后必做

# macOS 重启 daemon
launchctl kickstart -k gui/$(id -u)/ai.hermes.gateway

# 或 Linux
systemctl --user restart hermes-gateway