> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent 接入老张API：自定义端点、Claude 与消息网关配置

> 用 hermes model 向导或 config.yaml 把 Hermes Agent 的模型换成老张API，按 Anthropic 格式接入 Claude 并启用提示词缓存，在 Telegram 等消息平台沿用同一套配置。

| 项目 | 内容 |
| - | - |
| 入口 | `hermes model` → Custom endpoint |
| 配置文件 | `~/.hermes/config.yaml`（模型与地址）、`~/.hermes/.env`（密钥） |
| 接口地址 | OpenAI 格式 `https://api.laozhang.ai/v1`；Anthropic 格式 `https://api.laozhang.ai` |
| 令牌 | OpenAI 格式用 `default` 分组，Anthropic 格式用 `Claude Code` 分组，计费模式都选按量优先，在[令牌管理](https://api2.laozhang.ai/token)创建 |
| 推荐模型 | `claude-sonnet-5-5`、`gpt-6.1-sol`、`deepseek-v4-pro` |
| 最后核对 | 2026 年 11 月 4 日，Hermes Agent v0.22.7 |

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

## 安装 Hermes Agent

在 macOS 终端运行官方安装脚本：

```bash theme={null}
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.zshrc
hermes
```

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

## 用向导接入老张API

**1. 打开模型向导**

在终端运行：

```bash theme={null}
hermes model
```

在服务商列表中选择 **Custom endpoint (self-hosted / VLLM / etc.)**。

**2. 填写地址、密钥和模型**

* **API base URL**：`https://api.laozhang.ai/v1`
* **API key**：粘贴老张API密钥
* **模型名**：填写完整的模型 ID，例如 `deepseek-v4-pro`
* **上下文长度**：留空，由 Hermes 自动检测

模型 ID 要与[模型与价格总表](https://docs.laozhang.ai/models.md)完全一致。

**3. 发一个小任务测试**

用 `-z` 单次运行一个需要调用工具的任务：

```bash theme={null}
hermes -z "当前目录有几个 .txt 文件？用工具查一下，只回答数字。"
```

返回一个数字，说明对话和工具调用都已接通。之后运行 `hermes` 进入交互对话。

在[调用日志](https://api2.laozhang.ai/log)中可以看到这次对话的请求和用量。

## 用 config.yaml 配置

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

### 最小配置

**1. 把密钥写进 .env**

打开或新建 `~/.hermes/.env`，加一行：

```bash theme={null}
LAOZHANG_API_KEY=你的老张API密钥
```

这个文件里是完整密钥，不要提交到代码仓库或截图外发。

**2. 在 config.yaml 中设置模型**

打开 `~/.hermes/config.yaml`，把 `model` 一节改成：

```yaml theme={null}
model:
  default: deepseek-v4-pro
  provider: custom
  base_url: https://api.laozhang.ai/v1
  key_env: LAOZHANG_API_KEY
```

* `base_url` 要带 `/v1`，Hermes 会请求 `/v1/chat/completions`。
* `key_env` 填 `.env` 里的变量名，不要在这里写密钥本身。

**3. 发一个小任务测试**

```bash theme={null}
hermes -z "当前目录有几个 .txt 文件？用工具查一下，只回答数字。"
```

返回一个数字即配置成功。

第 2 步也可以用 `hermes config set` 完成，这几条命令会写入 `~/.hermes/config.yaml`：

```bash theme={null}
hermes config set model.provider custom
hermes config set model.base_url https://api.laozhang.ai/v1
hermes config set model.default deepseek-v4-pro
hermes config set model.key_env LAOZHANG_API_KEY
```

之后换默认模型只需再执行一次 `hermes config set model.default <模型 ID>`。

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

给老张API起一个 provider 名称，之后在对话里可以随时换模型：

```yaml theme={null}
providers:
  laozhang:
    api: https://api.laozhang.ai/v1
    key_env: LAOZHANG_API_KEY
    transport: chat_completions

model:
  default: deepseek-v4-pro
  provider: custom:laozhang
```

在 Hermes 会话中输入以下命令即可切换模型，格式为 `/model custom:laozhang:<模型 ID>`：

```text theme={null}
/model custom:laozhang:gpt-6.1-sol
```

只想让某一次启动用别的模型时，用 `-m` 参数或 `HERMES_INFERENCE_MODEL` 环境变量临时覆盖，不用改配置文件。

## 用 Anthropic 格式接入 Claude

Claude 模型按 Anthropic Messages 格式接入时，Hermes 会自动启用提示词缓存，命中缓存的部分按缓存价计费，规则见[提示词缓存计费](https://docs.laozhang.ai/faq/prompt-cache-billing.md)。

Anthropic 格式要用 `Claude Code` 分组的令牌：在[令牌管理](https://api2.laozhang.ai/token)新建一个，再在 `~/.hermes/.env` 中加一行：

```bash theme={null}
LAOZHANG_CLAUDE_API_KEY=你的老张API密钥
```

然后把 `model` 一节改成：

```yaml theme={null}
model:
  default: claude-sonnet-5-5
  provider: custom
  base_url: https://api.laozhang.ai
  key_env: LAOZHANG_CLAUDE_API_KEY
  api_mode: anthropic_messages
```

* `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：

```yaml theme={null}
providers:
  laozhang-claude:
    api: https://api.laozhang.ai
    key_env: LAOZHANG_CLAUDE_API_KEY
    api_mode: anthropic_messages
```

不改默认模型，直接用这个 provider 跑一次验证：

```bash theme={null}
hermes -z "当前目录有几个 .txt 文件？用工具查一下，只回答数字。" --provider custom:laozhang-claude -m claude-sonnet-5-5
```

返回一个数字，说明 Claude 已经按 Anthropic Messages 格式完成了工具调用。会话中用 `/model custom:laozhang-claude:claude-sonnet-5-5` 切换到 Claude。Claude 模型也能通过 `laozhang`（Chat Completions 格式）调用，但只有走 Anthropic 格式时 Hermes 才会自动加提示词缓存。

## 选择模型

下表模型都能在 Chat Completions 中以流式方式调用工具：

| 模型 | 适合 |
| - | - |
| `claude-sonnet-5-5` | 通用 Agent 任务、写作；按 Anthropic 格式接入可用提示词缓存 |
| `gpt-6.1-sol` | 复杂多步任务、编程 |
| `glm-5.2` | Agent 编程 |
| `deepseek-v4-pro` | 日常任务，性价比高 |
| `gemini-3.8-flash` | 性价比高，适合消息平台里频繁的短对话 |

GPT-6 系列从 2026 年 11 月 4 日起可以在 Chat Completions 中边推理边调用工具，不用调低推理强度。各模型价格见[模型与价格总表](https://docs.laozhang.ai/models.md)。

### 设置图片理解模型

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

```yaml theme={null}
auxiliary:
  vision:
    model: <支持图片输入的模型 ID>
```

哪些模型支持图片输入，见[模型与价格总表](https://docs.laozhang.ai/models.md)。

## 在 Telegram 等消息平台使用

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

**1. 配置网关**

```bash theme={null}
hermes gateway setup
```

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

**2. 启动网关**

```bash theme={null}
hermes gateway start
```

**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` 里的值，并在[令牌管理](https://api2.laozhang.ai/token)确认令牌已启用。
* **404**：地址里的 `/v1` 重复或缺失。Chat Completions 格式的地址要写成 `https://api.laozhang.ai/v1`。

更多排查见 [API Key 无效与 Base URL](https://docs.laozhang.ai/faq/invalid-api-key.md)。

### 报 403 或 503 no available channels？

令牌分组不包含这个模型，或模型 ID 写错。确认令牌分组：Chat Completions 格式用 `default`，Anthropic 格式（`api_mode: anthropic_messages`）用 `Claude Code`。再确认计费模式为按量优先，模型 ID 与[模型与价格总表](https://docs.laozhang.ai/models.md)一致。排查方法见[如何确认模型是否可用](https://docs.laozhang.ai/faq/model-availability.md)。提示余额不足时见[余额不足怎么办](https://docs.laozhang.ai/faq/balance-insufficient.md)。

## 相关文档

* [工具接入总览](https://docs.laozhang.ai/scenarios.md)
* [Chat Completions 请求格式与字段](https://docs.laozhang.ai/api-reference/chat-completions.md)
* [Claude 协议：Anthropic Messages 请求格式](https://docs.laozhang.ai/api-reference/claude.md)
* [提示词缓存计费](https://docs.laozhang.ai/faq/prompt-cache-billing.md)
* [Hermes Agent 官方文档](https://hermes-agent.nousresearch.com/docs/)
* [Hermes Agent GitHub 仓库](https://github.com/NousResearch/hermes-agent)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.