Hermes Agent 如何接入 OpenAI、Claude、DeepSeek 和本地模型

在 VPS 上部署 Hermes Agent 时，模型接入往往是新手翻车最多的地方。OpenAI、Claude、DeepSeek 的 API 格式不同，本地模型又要单独跑 Ollama，配置文件写错一个字段就报 401 或 503。本文直接给出可复用的配置模板和排障方法，帮你把 Hermes Agent 接到四种常见模型上。

Hermes Agent 接入 OpenAI 与 Claude

配置 API Key 和基础环境

Hermes Agent 默认通过环境变量读取 API Key。建议在运行前用 `export` 设置，或写入 `.env` 文件。安全起见，不要硬编码在配置文件里，尤其是版本控制时容易泄露。

export OPENAI_API_KEY="sk-xxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxx"

修改配置文件连接 OpenAI

Hermes Agent 的模型配置通常在 `config.yaml` 或 `agent_config.json` 中。OpenAI 的 endpoint 默认是 `https://api.openai.com/v1`，只需要指定模型名即可。

yaml
llm:
provider: openai
model: gpt-4o
api_key: ${OPENAI_API_KEY}

如果使用自定义 OpenAI 兼容接口（比如 One API 中转），需要额外加 `base_url` 字段。

接入 Claude 的注意事项

Claude 的 API 格式与 OpenAI 不通用。Hermes Agent 支持 Anthropic 原生接口，但需要明确 `provider: anthropic`，并且模型名写 `claude-3-5-sonnet-20241022` 这种完整版本号。老版本 Agent 可能不支持 `claude-3-5-haiku`，建议以官方仓库支持的模型列表为准。

yaml
llm:
provider: anthropic
model: claude-3-5-sonnet-20241022
api_key: ${ANTHROPIC_API_KEY}

Hermes Agent 接入 DeepSeek

DeepSeek 的 API 兼容 OpenAI 格式，所以配置起来最简单。把 provider 设为 `openai`，然后修改 `base_url` 指向 DeepSeek 的端点即可。

yaml
llm:
provider: openai
base_url: https://api.deepseek.com/v1
model: deepseek-chat
api_key: ${DEEPSEEK_API_KEY}

验证接入是否成功

启动 Hermes Agent 后，用一句简单指令测试，比如“用中文回答，1+1等于几”。如果返回正常，说明接入成功。如果报 400 错误，先检查 API Key 权限和余额，再看模型名是否写对——DeepSeek 的模型名是 `deepseek-chat` 而不是 `deepseek-v2`。

Hermes Agent 接入本地模型（Ollama）

部署 Ollama 并拉取模型

Ollama 是当前最省心的本地模型运行方案。在 VPS 上用 Docker 部署最快：

docker run -d –name ollama -p 11434:11434 ollama/ollama
docker exec ollama ollama pull qwen2.5:7b

注意：VPS 内存如果低于 8GB，别跑 7B 以上模型，否则直接 OOM 被 kill。建议先跑 3B 或 1.5B 的小模型测试。

配置 Hermes Agent 使用本地端点

Ollama 暴露的接口是 OpenAI 兼容的，所以 provider 依然用 `openai`，base_url 改成你的 VPS IP 加端口：

yaml
llm:
provider: openai
base_url: http://你的VPS公网IP:11434/v1
model: qwen2.5:7b
api_key: "" # 本地模型不需要 Key

安全提醒：Ollama 默认监听 0.0.0.0，如果 VPS 有公网 IP，务必用防火墙放行指定 IP 或改用 Nginx 反代加 Basic Auth，否则任何人都能调用你的模型。

性能与内存注意事项

本地模型推理很吃 CPU/GPU 和内存。Hermes Agent 在调用本地模型时，如果并发请求多，容易超时。建议在 Agent 配置里调长 `timeout` 参数（比如 120 秒），并且不要同时跑多个 Agent 进程。

老鸟叮嘱：避坑指南

1.API Key 别写进公开仓库。哪怕私有仓库，也建议用环境变量或密钥管理工具，比如 `docker secret` 或 `1Password CLI`。
2.Claude 的 region 问题。如果使用 Claude 的欧洲/亚洲端点，base_url 要对应修改，否则延迟高且可能被限流。
3.DeepSeek 的上下文长度。默认 32K，但 Hermes Agent 某些插件会拆分长文本，注意不要超过模型限制。
4.本地模型端口别裸奔。用 iptables 或 ufw 只允许自己的 IP 访问 11434 端口，或者通过 Cloudflare Tunnel 暴露。
5.版本兼容性。Hermes Agent 更新频繁，部分旧版本不支持 `base_url` 自定义，先跑 `git pull` 或检查 release note。

FAQ

Q1：Hermes Agent 支持同时配置多个模型吗？
A：支持。可以通过配置文件中的 `llm.fallback` 或路由规则设置主模型和备用模型，但不同 provider 需要分别配好 Key。

Q2：接入本地模型后 Agent 响应很慢怎么办？
A：先检查 VPS 的 CPU 占用和内存使用。如果内存不足，换更小的模型（如 qwen2.5:1.5b）。如果 CPU 跑满，考虑加 swap 或升级配置。还可以调低 Agent 的 `max_tokens` 和 `temperature` 来减少推理时间。

Q3：OpenAI 的 API Key 在 Hermes Agent 里报 401 是什么原因？
A：最常见原因是 Key 没有正确加载。检查环境变量是否生效，或者配置文件中 `api_key` 字段是否引用了未定义的变量。另外，OpenAI 的 Key 开头是 `sk-`，别复制错。

Q4：DeepSeek 的免费额度够用吗？
A：DeepSeek 注册送 500 万 tokens（以官方最新政策为准），个人测试完全够用。但生产环境建议按量付费，或者搭配本地模型做降级。

Q5：能不能用 Hermes Agent 同时调用本地模型和云端 API？
A：可以。通过 Agent 的插件或路由机制，可以实现“先尝试本地模型，失败或超时回退到云端”。具体实现需要修改 Agent 的 `tool_use` 逻辑，有一定门槛。

Q6：Ollama 拉取模型太慢怎么办？
A：可以添加国内镜像源（如 `https://docker.mirrors.ustc.edu.cn`），或者手动下载模型文件后导入 Ollama。另外，选 `qwen2.5:3b` 这类小模型，下载速度快，部署也轻量。

接入模型是 Hermes Agent 上手的第一个硬门槛，但只要理清 provider、base_url、model 三个字段，不管是云端还是本地模型都能快速跑通。建议先用 OpenAI 或 DeepSeek 验证 Agent 功能，再切换到本地模型做离线部署和成本控制。

—

**相关阅读：**

– [Hermes Agent VPS 部署教程：Docker Compose 安装和初始化配置](https://www.zhujixuan.com/jishujiaocheng/9872.html)
– [VPS部署AI工具100讲：AI Agent、Codex、Claude Code、Hermes Agent、Ollama与自动化工作流实战教程](https://www.zhujixuan.com/jishujiaocheng/9606.html)
– [VPS 部署 AI 工具需要哪些基础？Linux、Docker、Nginx 和域名配置入门](https://www.zhujixuan.com/jishujiaocheng/9747.html)