跳转到主要内容
Hermes Agent 对模型有两个要求：能返回工具调用，上下文不少于 64K。上下文小于 64K 时 Hermes 会拒绝启动。

​
安装 Hermes Agent

在 macOS 终端运行官方安装脚本：
  • 脚本会自带 uv、Python、Node、ripgrep 和 FFmpeg，不需要提前安装 Python。
  • hermes 命令装在 ~/.local/bin/hermes，配置和数据在 ~/.hermes/。
  • pip、uv、Homebrew 安装方式官方标注为不支持，请用上面的脚本。
  • Apple Silicon 的 Mac 也可以安装 Hermes Desktop（DMG 安装包）。

​
用向导接入老张API

1

打开模型向导

在终端运行：
在服务商列表中选择 Custom endpoint (self-hosted / VLLM / etc.)。
2

填写地址、密钥和模型

  • API base URL：https://api.laozhang.ai/v1
  • API key：粘贴老张API密钥
  • 模型名：填写完整的模型 ID，例如 deepseek-v4-pro
  • 上下文长度：留空，由 Hermes 自动检测
模型 ID 要与模型与价格总表完全一致。
3

发一个小任务测试

用 -z 单次运行一个需要调用工具的任务：
返回一个数字，说明对话和工具调用都已接通。之后运行 hermes 进入交互对话。在调用日志中可以看到这次对话的请求和用量。

​
用 config.yaml 配置

不想走向导，或者要在多台机器上复用配置时，直接编辑配置文件。密钥写在 ~/.hermes/.env，config.yaml 只引用变量名，这样分享或备份 YAML 时不会带出密钥。

​
最小配置

1

把密钥写进 .env

打开或新建 ~/.hermes/.env，加一行：
这个文件里是完整密钥，不要提交到代码仓库或截图外发。
2

在 config.yaml 中设置模型

打开 ~/.hermes/config.yaml，把 model 一节改成：
  • base_url 要带 /v1，Hermes 会请求 /v1/chat/completions。
  • key_env 填 .env 里的变量名，不要在这里写密钥本身。
3

发一个小任务测试

返回一个数字即配置成功。
第 2 步也可以用 hermes config set 完成，这几条命令会写入 ~/.hermes/config.yaml：
之后换默认模型只需再执行一次 hermes config set model.default <模型 ID>。

​
命名 provider 与会话中切换模型

给老张API起一个 provider 名称，之后在对话里可以随时换模型：
在 Hermes 会话中输入以下命令即可切换模型，格式为 /model custom:laozhang:<模型 ID>：
只想让某一次启动用别的模型时，用 -m 参数或 HERMES_INFERENCE_MODEL 环境变量临时覆盖，不用改配置文件。

​
用 Anthropic 格式接入 Claude

Claude 模型按 Anthropic Messages 格式接入时，Hermes 会自动启用提示词缓存，命中缓存的部分按缓存价计费，规则见提示词缓存计费。 Anthropic 格式要用 Claude Code 分组的令牌：在令牌管理新建一个，再在 ~/.hermes/.env 中加一行：
然后把 model 一节改成：
  • api_mode: anthropic_messages 让 Hermes 改用 Anthropic Messages 格式请求，密钥以 x-api-key 请求头发送。
  • key_env 指向 Claude Code 分组的令牌。LAOZHANG_API_KEY 里的 default 令牌继续给 Chat Completions 格式用。
  • base_url 写 https://api.laozhang.ai 即可，写成带 /v1 也能用，Hermes 会自动去掉结尾的 /v1。
  • 这个格式下还可以用 claude-opus-5-5、claude-haiku-5-5、glm-5.2、deepseek-v4-pro 等模型。
用命名 provider 时，在 provider 上设置 api_mode: anthropic_messages。想同时保留上一节的 laozhang，再加一个 provider：
不改默认模型，直接用这个 provider 跑一次验证：
返回一个数字，说明 Claude 已经按 Anthropic Messages 格式完成了工具调用。会话中用 /model custom:laozhang-claude:claude-sonnet-5-5 切换到 Claude。Claude 模型也能通过 laozhang（Chat Completions 格式）调用，但只有走 Anthropic 格式时 Hermes 才会自动加提示词缓存。

​
选择模型

下表模型都能在 Chat Completions 中以流式方式调用工具： GPT-6 系列从 2026 年 11 月 4 日起可以在 Chat Completions 中边推理边调用工具，不用调低推理强度。各模型价格见模型与价格总表。

​
设置图片理解模型

识别图片、生成会话标题、压缩上下文等副任务默认使用主模型。主模型不支持图片输入时，在 config.yaml 中单独指定一个支持图片的模型：
哪些模型支持图片输入，见模型与价格总表。

​
在 Telegram 等消息平台使用

Hermes 的消息网关让你在 Telegram、Discord、Slack、WhatsApp、飞书、企业微信等平台和同一个 Agent 对话。网关读取同一份 config.yaml，上面配好的老张API模型不用再填一遍。
1

配置网关

按向导选择要接入的平台，并填写该平台要求的信息。
2

启动网关

3

在平台里发消息测试

给机器人发一条消息，能收到回复说明网关已经通过老张API调用模型。

​
常见问题

​
提示上下文不足 64K，无法启动？

Hermes 要求模型上下文不少于 64K。确认模型 ID 填写正确，并选用上文推荐的模型。用向导配置时，可以在上下文长度一栏手动填写所选模型的上下文长度，而不是留空自动检测。

​
设置了 OPENAI_BASE_URL，为什么没生效？

OPENAI_BASE_URL 和 OPENAI_API_KEY 只对 Hermes 内置的 openai-api provider 生效，自定义端点不读取它们。
  • 地址和密钥：按上文在 config.yaml 中设置 base_url 和 key_env。
  • 临时换模型：LLM_MODEL 已被移除，改用 -m 参数或 HERMES_INFERENCE_MODEL。

​
报 401 或 404？

  • 401：密钥错误或没有复制完整。检查 .env 里的值，并在令牌管理确认令牌已启用。
  • 404：地址里的 /v1 重复或缺失。Chat Completions 格式的地址要写成 https://api.laozhang.ai/v1。
更多排查见 API Key 无效与 Base URL。

​
报 403 或 503 no available channels？

令牌分组不包含这个模型，或模型 ID 写错。确认令牌分组：Chat Completions 格式用 default，Anthropic 格式（api_mode: anthropic_messages）用 Claude Code。再确认计费模式为按量优先，模型 ID 与模型与价格总表一致。排查方法见如何确认模型是否可用。提示余额不足时见余额不足怎么办。

​
相关文档