Hermes Agent setup with LaoZhang API

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:

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

Create a token

In Tokens, 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, you’ll add a second token in the Claude Code group.

Start the model wizard

Run:

hermes model

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

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

Run a task that uses a tool

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

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. 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:

~/.hermes/config.yaml

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:

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:

~/.hermes/.env

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:

~/.hermes/config.yaml

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:

/model custom:laozhang:gpt-6.1-sol

Any model ID from the model catalog 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. Add a second provider with api_mode: anthropic_messages:

~/.hermes/config.yaml

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 with the Usage first billing mode and add it to ~/.hermes/.env next to the first key:

~/.hermes/.env

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:

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.

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:

~/.hermes/config.yaml

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.

Set up a platform

hermes gateway setup

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

Start the gateway

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.

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.

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. For Claude, claude-haiku-4-5-20251001 isn’t offered; use claude-haiku-5-5. See Check model availability and access.

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.

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. If your balance looks fine, see Why a request can fail with remaining balance.

Overview

Coding tools

Chat clients

Agents

Frameworks

Hermes Agent setup with LaoZhang API

Install Hermes Agent

Connect LaoZhang API

Edit the config file

Switch models with a named provider

Use Claude over the Anthropic format

Choose a model

Read images with a text-only model

Use Hermes on Telegram and other chat apps

FAQ

I get a 401

I get a 403 or 503 “no available channels”

I get a 404

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

The agent replies but never runs a tool

OPENAI_BASE_URL, OPENAI_API_BASE, or LLM_MODEL has no effect

I see “insufficient balance”

​Install Hermes Agent

​Connect LaoZhang API

​Edit the config file

​Switch models with a named provider

​Use Claude over the Anthropic format

​Choose a model

​Read images with a text-only model

​Use Hermes on Telegram and other chat apps

​FAQ

​I get a 401

​I get a 403 or 503 “no available channels”

​I get a 404

​Hermes won’t start and reports the context length is too small

​The agent replies but never runs a tool

​OPENAI_BASE_URL, OPENAI_API_BASE, or LLM_MODEL has no effect

​I see “insufficient balance”

​Related pages

Install Hermes Agent

Connect LaoZhang API

Edit the config file

Switch models with a named provider

Use Claude over the Anthropic format

Choose a model

Read images with a text-only model

Use Hermes on Telegram and other chat apps

FAQ

I get a 401

I get a 403 or 503 “no available channels”

I get a 404

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

The agent replies but never runs a tool

OPENAI_BASE_URL, OPENAI_API_BASE, or LLM_MODEL has no effect

I see “insufficient balance”

Related pages