Hermes Agent BYOK 中文指南

BYOK 能干什么

• 用自己的 OpenAI 订阅 / Anthropic 订阅 / Gemini 配额，不再付 OpenClaw Launch 的模型费
• 用自己企业账号的 OpenRouter 余额（OpenRouter 一般有团队定价）
• 用 Anthropic OAuth（不需要 API key，直接 OAuth 登录拿 token）
• 用本地 / 自建 endpoint（Ollama、vLLM、LM Studio）
• 用便宜或免费的 provider（Groq、Together、Fireworks）做高频低成本任务

支持的 Provider 列表

Hermes 原生支持的 provider（基于 v2026.4.16+）：

• openai：OpenAI 官方
• anthropic：Anthropic 官方（API key 或 OAuth）
• openrouter：OpenRouter 聚合
• google：Gemini API
• groq：Groq Cloud
• together：Together AI
• fireworks：Fireworks AI
• cohere：Cohere
• mistral：Mistral La Plateforme
• deepseek：DeepSeek 官方
• moonshot：Moonshot Kimi
• minimax：MiniMax 海外（不是国内）
• ollama：本地 Ollama 实例
• vllm / lmstudio：自建 OpenAI 兼容 endpoint
• 外加 Anthropic OAuth、OpenAI Codex 设备代码登录两种 OAuth-based provider

最简单的 BYOK：环境变量

最快的方式是启动 Hermes 时直接传 provider key 的环境变量：

docker run -d \
  -e OPENAI_API_KEY="sk-proj-..." \
  -e ANTHROPIC_API_KEY="sk-ant-api..." \
  -e OPENROUTER_API_KEY="sk-or-v1-..." \
  -e GEMINI_API_KEY="AIza..." \
  -e GROQ_API_KEY="gsk_..." \
  -p 8642:8642 \
  ghcr.io/nousresearch/hermes-agent:latest

Hermes 启动时检测到这些环境变量就自动把对应 provider 加进 models.providers。

用 hermes.json 精细控制（推荐）

{
  "models": {
    "primary": "openai/gpt-5",
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      },
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      },
      "openrouter": {
        "apiKey": "${OPENROUTER_API_KEY}"
      },
      "google": {
        "apiKey": "${GEMINI_API_KEY}"
      }
    }
  }
}

Anthropic OAuth（不用 API key）

如果你订阅了 Claude Pro 或 Claude Max，不需要单独申请 API key —— 直接用 OAuth 登录，Hermes 把你的浏览器登录态用来调 Anthropic：

# 启动 Hermes 后
hermes auth login anthropic

# 浏览器打开 claude.ai 让你登录
# 完成后 Hermes 把 token 写到 ~/.hermes/auth/anthropic.json

用法和 API key 一样，但走的是订阅额度（Claude Pro 是月费固定额度，Max 是调用计费）。这种方式 Hermes 配置：

"anthropic": {
  "authMode": "oauth"
}

OpenAI Codex 设备代码登录

OpenAI 给 ChatGPT Plus / Pro 订阅者提供了一种 device-code OAuth 流程（原本给 Codex CLI 用），Hermes 也支持。订阅了 Plus 的人不用单独买 API tier 也能调 GPT-5：

hermes auth login openai-codex
# 跟着提示在浏览器打开 chatgpt.com 输入 6 位 code

关键：BYOK 模式下默认模型必须也是 BYOK

重要规则：如果你开了任何一个 provider 的 BYOK，models.primary（默认模型）必须也是这个 provider 的模型，而且不能配 fallback 到非-BYOK 的 provider。

为什么：Hermes 的 routing 是“按模型 ID 选 provider”。如果 primary 是 openrouter/anthropic/claude-sonnet-4.6 但你只开了 anthropic BYOK 没开 openrouter BYOK，那 chat 会落到我们共享的 OpenRouter sub-key 上 —— 用户预期是“全走我自己的 key”，结果一半流量走了别人的池子。

Hermes v2026.4.16 引入了“BYOK 全流量”约束：检测到任何 BYOK 配置时，强制重写 models.primary 到 BYOK provider 的对应模型，且不允许 fallbacks 数组。

本地 Ollama / vLLM 接入

"providers": {
  "ollama": {
    "baseUrl": "http://host.docker.internal:11434"
  },
  "vllm": {
    "baseUrl": "http://my-vllm-server:8000/v1",
    "apiKey": "any-string"
  }
}

"primary": "ollama/llama3.1:70b"

详细参考 Hermes 接入 Ollama。

多 provider 用法：按任务分配模型

{
  "models": {
    "primary": "anthropic/claude-sonnet-4.6",
    "agents": {
      "code": "openai/gpt-5",
      "memory": "groq/llama-3.3-70b",
      "embed": "google/text-embedding-004"
    }
  }
}

Hermes 给每个 agent role 分配最适合的模型。code agent 用 GPT-5（推理强），memory agent 用便宜的 Groq Llama（高频但任务简单），embed 用 Gemini（最便宜的 embedding）。

常见问题

开了 BYOK 但 Hermes 还在烧 OpenClaw 的 key

你的 models.primary 没改成 BYOK provider 的模型。或者 fallback 数组里有非-BYOK 的 model 在兜底。检查 hermes.json 把 fallback 清空。

API key 在容器里能不能加密

Hermes 不直接加密 API key（运行时要明文调 provider）。但 OpenClaw Launch 托管版会把 key 存在加密的 ENV vault 里，容器启动时才注入。自己部署的话别把 key commit 到镜像或 Git，用 Docker secrets 或 Kubernetes secrets 管。

限速怎么办

不同 provider 限速差很大：OpenAI 是按 RPM/TPM，Anthropic 类似，Groq 较宽松，OpenRouter 按 sub-key。Hermes 自动 retry 短时 429，但不会跨 provider 自动 fallback（出于上文的 BYOK 全流量约束）。建议直接选额度宽松的 provider 做主力。

托管版：OpenClaw Launch

托管版给每个 Hermes 实例发一个独立的 OpenRouter sub-key（按订阅 tier 分配额度），不用 BYOK 也能开箱即用。如果想用自己的 key 替代，Dashboard → Models → 填 BYOK key，OpenClaw 会自动把所有 provider 切换到 BYOK 路径。首月 $3，之后 $6/月。

下一步

• Hermes Agent 中文介绍
• OpenAI 兼容 API
• OpenAI Codex 设备代码登录
• 本地 Ollama 接入
• 模型对比