玄枢API

Hermes 接入教程

把 Hermes 接到玄枢API，可选 Anthropic（Claude）或 OpenAI（Codex）通道，含一键脚本、手动安装、配置、最小测试、回滚与排错。

1. 准备 API Key

还没有账户的先到 /register 注册。
在 /keys 创建一个供 Hermes 单独使用的 Key，按需要设置额度、有效期和访问限制。
立即安全保存完整 Key；页面再次打开时可能只显示脱敏值。不要写入仓库、截图或聊天记录。

2. 一键安装（推荐）

运行后按提示选择通道并粘贴 API Key，脚本会写入 ~/.hermes/config.yaml。脚本需要 sudo。源码见 /install/hermes.sh，可先下载审阅再执行。

curl -fsSL https://www.xuanshuapi.com/install/hermes.sh | sudo bash

备用方式：手动安装 Hermes需要审查每条命令或一键脚本不可用时展开

3. 手动安装

用 pipx 安装：

pipx install hermes-agent
hermes --version

看到版本号即安装成功。

4. 选择通道并写入配置

模型会更新，当前可用列表以 /available-channels 为准。已有配置会被覆盖，建议先备份。

mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml << 'EOF'
model:
  default: claude-opus-4-7
  provider: xuanshu-claude
providers:
  xuanshu-claude:
    api_mode: anthropic_messages
    base_url: https://www.xuanshuapi.com
    api_key: <YOUR_API_KEY>
    default_model: claude-opus-4-7
    models:
      - claude-opus-4-7
EOF

mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml << 'EOF'
model:
  default: gpt-5.6-sol
  provider: xuanshu-codex
providers:
  xuanshu-codex:
    api_mode: codex_responses
    base_url: https://www.xuanshuapi.com/v1
    api_key: <YOUR_API_KEY>
    default_model: gpt-5.6-sol
    models:
      - gpt-5.6-sol
EOF

5. 运行最小测试

在项目目录执行下面的命令启动 Hermes，随便问一句话，确认能拿到回复。

hermes

6. 成功标准

Hermes 正常启动并返回模型回复；在 /usage 能看到对应模型的成功调用记录，且没有 404、401/403 或 429。三点都满足再进入真实项目。

7. 回滚配置

备份配置文件并清除当前终端里的相关环境变量，然后开启新的登录 Shell。

mv ~/.hermes/config.yaml ~/.hermes/config.yaml.xuanshu-backup
unset ANTHROPIC_API_KEY ANTHROPIC_BASE_URL \
  OPENAI_API_KEY OPENAI_BASE_URL
exec "$SHELL" -l

8. 常见问题排查

先记录状态码、请求时间、模型 ID 和 /usage 里的调用记录；分享日志时隐藏完整 Key。

现象	检查	处理
404	Anthropic 通道的 base_url 必须是 https://www.xuanshuapi.com（不带 /v1）；Codex 通道必须带 /v1。	按通道改正 base_url，重启 Hermes 后重试。
401 / 403	确认 api_key 是完整未截断的 Key，且该 Key 未过期、未被吊销。	在 /keys 重新复制或新建 Key。
模型不可用	用同一个 Key 在 /available-channels 核对精确模型 ID 与当前可见性。	改 default 与 default_model；模型暂不可用时改用同协议的可用模型。
429	在 /usage 检查余额、Key 限额和并发请求数。	降低并发并等待限流窗口恢复，只对 429 使用有上限的退避重试。
配置未生效	确认写入的是 ~/.hermes/config.yaml，且 Hermes 已重启。	重启 Hermes；一键脚本写入后已打开的会话不会自动重载。
pipx 未找到	pipx 未安装或不在 PATH 中。	先安装 pipx（python3 -m pip install --user pipx），再重开终端。