Hermes / OpenClaw 接入 MonkeyAI：先按五步顺序实测，再改配置

为什么『安全顺序』值得照做？

直接结论：它把『接口失败』和『配置失败』分开。每一步只验证一层，验证通过再进下一步。如果带正确 Key 调 GET /v1/models 仍然失败，说明问题在 API 本身；这时改 provider 配置只会增加噪音。

第一步——先确认路由，再确认 Key

不带凭据的请求至少要到达网关的认证层。如果路由返回的是 HTML 或通用 404，说明客户端根本没有命中 OpenAI 兼容接口。

curl -sS https://monkeytheme.com/v1/models
# HTTP 401 —— {"code":"API_KEY_REQUIRED","message":"API key is required ..."}

curl -sS https://monkeytheme.com/models
# HTTP 404 —— nginx 默认 404 HTML（路径不对）

/v1/chat/completions、/v1/responses、/v1/messages、/v1/embeddings 四个端点在没有 Key 时都返回同样的 API_KEY_REQUIRED。这正好覆盖 Agent 客户端会主动调用的几类接口。

第二步——确认凭据被接受

伪造 Bearer Key 和伪造 Anthropic 风格的 x-api-key 都能到达认证层，但服务端返回的错误码不同，便于区分"无 Key / 错 Key / Key 来自另一套系统"。

这和 OpenAI 兼容客户端的预期一致：只要在 Authorization 里放 Bearer 头，就能到达认证层；服务端会明确告诉你 Key 不对，而不是悄悄拒绝。

第三步——Hermes Agent / OpenClaw 配置怎么写

Hermes Agent 官方文档描述了 custom_providers 配置：把一个 OpenAI 兼容的 Base URL 指向第三方网关。任何支持 OpenAI 兼容模式的 Agent 网关都可以使用相同的写法。

# ~/.hermes/config.yaml
model:
  default: gpt-5.4
  provider: monkeytheme
  base_url: https://monkeytheme.com/v1
  api_key: sk-***

custom_providers:
  - name: monkeytheme
    base_url: https://monkeytheme.com/v1
    api_key: sk-***
    models:
      - gpt-5.5
      - gpt-5.4

保存后重启 gateway 进程，让新的 custom_providers 生效。Hermes Agent 会缓存 OpenAI 客户端对象——换 Key 或新增 provider 会重建客户端，但长会话里模型列表变化往往需要重启或开新会话才能感知。

第四步——挑一个后台真实展示的模型名

在改 provider 配置前，先确认模型名对当前账号可见。直接用线上 models 接口：

curl -sS https://monkeytheme.com/v1/models \
  -H "Authorization: Bearer sk-***" \
| python3 -c 'import json,sys; [print(x.get("id")) for x in json.load(sys.stdin).get("data", [])]'

把返回的 id 原样写到 models: 列表或当前模型字段。显示名、其他服务商的教程、凭记忆猜测的别名，都会让 model not found 在凭据和 Base URL 都正确的情况下仍然出现。

第五步——重启 + 跑一条最小请求

改完配置后，重启 gateway 或开新会话，然后跑一条最短的 completion 验证全链路：

curl -sS https://monkeytheme.com/v1/chat/completions \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"hi"}]}'

如果返回正常 completion，说明 provider 配置已经接通；如果还是 401，问题在 Key 或 Base URL 上，不在 Agent 的 provider 列表里。

本文明确不覆盖什么

• Hermes Agent / OpenClaw 的 Anthropic Messages 协议支持。本文只覆盖 OpenAI 兼容模式。Anthropic 协议走 ANTHROPIC_BASE_URL、apiKeyHelper 等不同环境变量，参见协议边界页。
• OAuth 流程变更。本文假设凭据是后台签发的静态 sk-… Key。
• 账号分组相关的模型列表。不同分组可见模型不同，线上 /v1/models 是唯一权威来源。
• 订阅或计费变更。Provider 配置不接触计费路径。

相关教程与参考资料

• 区分 401、404 与模型错误
• 为什么 API Base URL 通常需要 /v1
• Claude Code 与 API Gateway（协议边界）
• Agent 客户端中心：Hermes、Codex、Cline、Roo Code
• 429 限流错误排查
• 504 超时与上游错误排查

常见问题