> ## 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 setup with LaoZhang API

> Point Nous Research's Hermes Agent at LaoZhang API through a custom endpoint, run Claude over the Anthropic format with prompt caching, and reuse the same setup on Telegram and other chat apps.

Hermes Agent is Nous Research's open-source agent for the terminal, with a gateway that brings the same agent to chat apps. It calls tools on every step, so choose a model with tool calling and at least 64K of context.

| Item | Details |
| - | - |
| Where | `hermes model` → Custom endpoint |
| Config files | `~/.hermes/config.yaml` (model and endpoint), `~/.hermes/.env` (key) |
| Base URL | `https://api.laozhang.ai/v1`; `https://api.laozhang.ai` for the Anthropic format |
| Tokens | `default` group for the OpenAI format, `Claude Code` group for the Anthropic format, both with the Usage first billing mode |
| Recommended models | `claude-sonnet-5-5`, `gpt-6.1-sol`, `glm-5.2`, `deepseek-v4-pro` |
| Model requirements | Tool calling, context window of 64K or more |
| Last verified | November 4, 2026, Hermes Agent 0.22.7 |

## Install Hermes Agent

On macOS, install with the official script, reload your shell, and start Hermes:

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

* The script brings its own uv, Python 3.14, Node, ripgrep, and FFmpeg, so you don't need to install Python first.
* It puts the `hermes` command in `~/.local/bin/`, the code in `~/.hermes/hermes-agent/`, and your data and settings in `~/.hermes/`.
* Installing with pip, uv, or Homebrew isn't supported by the project. On Apple Silicon Macs you can also use the Hermes Desktop app.

## Connect LaoZhang API

**1. Create a token**

In [Tokens](https://api.laozhang.ai/token), create a token in the `default` group with the **Usage first** billing mode, then copy the key. The wizard uses the OpenAI format; if you later [use Claude over the Anthropic format](#use-claude-over-the-anthropic-format), you'll add a second token in the `Claude Code` group.

**2. Start the model wizard**

Run:

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

From the provider list, choose **Custom endpoint (self-hosted / VLLM / etc.)**.

**3. Enter the endpoint details**

* **API base URL**: `https://api.laozhang.ai/v1`
* **API key**: your LaoZhang API key
* **Model name**: the full model ID, such as `deepseek-v4-pro`
* **Context length**: leave it blank and Hermes detects it

**4. Run a task that uses a tool**

`hermes -z` runs a single prompt and exits. Ask for something that needs a tool:

```bash theme={null}
hermes -z "How many .txt files are in the current directory? Use a tool to check, then answer with just the number."
```

If Hermes runs a command and prints the number, chat and tool calls both work. Each request appears in your [call logs](https://api.laozhang.ai/log). Run `hermes` without arguments for an interactive session.

## Edit the config file

The wizard is the quickest way in. To set things up by hand, or to see what the wizard changed, open `~/.hermes/config.yaml`. The smallest working setup looks like this:

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

You can write the same four keys from the command line instead. Each `hermes config set` call saves one key to `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
```

`key_env` tells Hermes which environment variable holds the key. Put the key itself in `~/.hermes/.env`, not in the YAML file:

```bash ~/.hermes/.env theme={null}
LAOZHANG_API_KEY=your-laozhang-api-key
```

* Keep `/v1` at the end of `base_url`. Hermes sends requests to `/v1/chat/completions` under that address.
* Uppercase names passed to `hermes config set` go to `.env` instead of `config.yaml`.
* To try another model for one run without editing the file, use `hermes -m gpt-6.1-sol` or set `HERMES_INFERENCE_MODEL`.

## Switch models with a named provider

A named provider lets you keep the LaoZhang API endpoint in one place and switch models in the middle of a session:

```yaml ~/.hermes/config.yaml theme={null}
model:
  default: deepseek-v4-pro
  provider: custom:laozhang

providers:
  laozhang:
    api: https://api.laozhang.ai/v1
    key_env: LAOZHANG_API_KEY
    transport: chat_completions
```

Inside a session, switch to another model with:

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

Any model ID from the [model catalog](https://docs.laozhang.ai/en/models.md) works after `custom:laozhang:`, as long as it supports tool calling.

## Use Claude over the Anthropic format

When Hermes talks to Claude over the Anthropic Messages format, it adds prompt caching on its own. An agent resends the conversation and tool definitions on every step, so cached input can cut the cost of long sessions noticeably; see [prompt cache billing](https://docs.laozhang.ai/en/faq/prompt-cache-billing.md).

Add a second provider with `api_mode: anthropic_messages`:

```yaml ~/.hermes/config.yaml theme={null}
model:
  default: claude-sonnet-5-5
  provider: custom:laozhang-claude

providers:
  laozhang:
    api: https://api.laozhang.ai/v1
    key_env: LAOZHANG_API_KEY
    transport: chat_completions
  laozhang-claude:
    api: https://api.laozhang.ai
    key_env: LAOZHANG_CLAUDE_API_KEY
    api_mode: anthropic_messages
```

The Anthropic-format provider needs a key in the `Claude Code` token group. Create one in [Tokens](https://api.laozhang.ai/token) with the Usage first billing mode and add it to `~/.hermes/.env` next to the first key:

```bash ~/.hermes/.env theme={null}
LAOZHANG_API_KEY=your-default-group-key
LAOZHANG_CLAUDE_API_KEY=your-claude-code-group-key
```

* Use `https://api.laozhang.ai` as the address. Hermes also accepts it with `/v1` and removes the suffix itself.
* Hermes sends the key in the `x-api-key` header. Each provider reads its own key, named in `key_env`.
* Claude models on this format: `claude-sonnet-5-5`, `claude-opus-5-5`, and `claude-haiku-5-5`. Automatic prompt caching applies to these.
* Other models on this format: `glm-5.2`, `deepseek-v4-pro`, and `deepseek-v4-flash`.
* Switch between the two providers in a session with `/model custom:laozhang-claude:claude-opus-5-5` or `/model custom:laozhang:gpt-6.1-sol`.

To check the Claude setup without changing your default model, run a one-shot task on the new provider:

```bash theme={null}
hermes -z "How many .txt files are in the current directory? Use a tool to check, then answer with just the number." --provider custom:laozhang-claude -m claude-sonnet-5-5
```

If it prints a number, Claude is answering and calling tools over the Anthropic format.

If you only use one provider, you can instead switch the minimal config to the Anthropic format:

* Add `api_mode: anthropic_messages` under `model`.
* Change `base_url` to `https://api.laozhang.ai`.
* Set `key_env` to `LAOZHANG_CLAUDE_API_KEY`.

## Choose a model

Hermes needs a model that returns tool calls and has a context window of at least 64K; it won't start with a smaller one. These models return tool calls in streaming Chat Completions requests:

| Model | Use it for |
| - | - |
| `claude-sonnet-5-5` | General agent work and writing; use the Anthropic format for prompt caching |
| `gpt-6.1-sol` | Complex multi-step tasks; first choice for an OpenAI model |
| `glm-5.2` | Agent coding at a lower price |
| `deepseek-v4-pro` | Everyday tasks at a good price |
| `gemini-3.8-flash` | Fast, low-cost tasks |

Since November 4, 2026, GPT-6 and GPT-5.6 models such as `gpt-6-sol` and `gpt-5.6-sol` can also reason and call tools in the same Chat Completions request. Prices are in the [model catalog](https://docs.laozhang.ai/en/models.md).

### Read images with a text-only model

Side tasks such as session titles, context compression, and image reading use the main model unless you set them separately. If your main model can't read images, set a vision model under `auxiliary`. Replace the placeholder with the ID of a model that accepts image input, from the [model catalog](https://docs.laozhang.ai/en/models.md):

```yaml ~/.hermes/config.yaml theme={null}
auxiliary:
  vision:
    model: <image-capable-model-id>
```

## Use Hermes on Telegram and other chat apps

The messaging gateway runs the same agent on Telegram, Discord, Slack, WhatsApp, Feishu, WeCom, and other platforms. It reads the model from the same `~/.hermes/config.yaml`, so the LaoZhang API setup above carries over with no extra configuration.

**1. Set up a platform**

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

Choose a platform such as Telegram and follow the prompts to connect your bot.

**2. Start the gateway**

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

Send your bot a message. The reply comes from the model in `config.yaml`, and the request shows up in your [call logs](https://api.laozhang.ai/log).

## FAQ

### I get a 401

The key is wrong or was cut off when copied. Check the key lines in `~/.hermes/.env`, including `LAOZHANG_CLAUDE_API_KEY` if you use the Anthropic format. Make sure each `key_env` value in `config.yaml` uses the same name as its line. See [Invalid API key or 404](https://docs.laozhang.ai/en/faq/invalid-api-key.md).

### I get a 403 or 503 "no available channels"

The token's group doesn't include the model, or the model ID is misspelled. Use a `default` group token for the OpenAI format and a `Claude Code` group token for the Anthropic format, both with the Usage first billing mode, and copy the ID from the [model catalog](https://docs.laozhang.ai/en/models.md). For Claude, `claude-haiku-4-5-20251001` isn't offered; use `claude-haiku-5-5`. See [Check model availability and access](https://docs.laozhang.ai/en/faq/model-availability.md).

### I get a 404

For the OpenAI format, the base URL must end in exactly one `/v1`: `https://api.laozhang.ai/v1`. A missing or doubled `/v1` returns 404.

### Hermes won't start and reports the context length is too small

Hermes requires at least 64K of context. Switch to a model from the table above. If you typed a context length in the wizard, run `hermes model` again and leave the field blank, or enter the model's real context length.

### The agent replies but never runs a tool

Hermes calls the model through Chat Completions and expects tool calls back. Switch to a model from [Choose a model](#choose-a-model).

### OPENAI\_BASE\_URL, OPENAI\_API\_BASE, or LLM\_MODEL has no effect

Hermes reads the custom endpoint from `config.yaml`, not from these variables:

* `OPENAI_BASE_URL` and `OPENAI_API_KEY` apply only to the built-in `openai-api` provider.
* `OPENAI_API_BASE` isn't read.
* `LLM_MODEL` has been removed. Use `HERMES_INFERENCE_MODEL` or `-m` for a one-off model.

Guides that use `hermes config set llm.*` are out of date. The keys are `model.*`, such as `model.default`.

### I see "insufficient balance"

Top up your account, and check the token's quota in [Tokens](https://api.laozhang.ai/token). If your balance looks fine, see [Why a request can fail with remaining balance](https://docs.laozhang.ai/en/faq/balance-insufficient.md).

## Related pages

* [Integrations overview](https://docs.laozhang.ai/en/scenarios.md)
* [OpenAI protocol: Chat Completions](https://docs.laozhang.ai/en/api-reference/chat-completions.md)
* [Claude protocol: Anthropic Messages API](https://docs.laozhang.ai/en/api-reference/claude.md)
* [Prompt cache billing](https://docs.laozhang.ai/en/faq/prompt-cache-billing.md)
* [Hermes Agent docs](https://hermes-agent.nousresearch.com/docs/)
* [Hermes Agent on GitHub](https://github.com/NousResearch/hermes-agent)


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