This guide ties together five hands-on Hermes / OpenClaw articles on this site into one complete path: which one to choose → how to install it → how to configure models → how to use skills. Every command was verified against real running instances on 2026-07-31—not padded out by copying official docs. Both projects move fast, so you should re-check the official documentation before you start.

0. What are these two for?

Hermes and OpenClaw are both open-source, self-hostable AI agent frameworks. Both use the MIT license, are free to use, and run on your own machine.

The difference between an “AI agent” and a regular chatbot is that an agent does more than reply: it can call tools, run scripts, remember state, and stay online across multiple chat apps at the same time. The core loop is the same:

You send it a message in some chat app (Telegram/WeChat/Feishu/Discord…) → the agent thinks and calls tools → it replies with the result.

They come from different backgrounds and have different personalities:

• Hermes (written in Python, from Nous Research): focused on a “self-improving agent.” It has a skills system that can automatically create and improve skills based on usage experience, getting stronger the more you use it. It has the most complete support for China-focused chat platforms (WeChat/Feishu/DingTalk/WeCom/QQ).
• OpenClaw (written in Node.js/TypeScript): focused on being a “multi-channel gateway.” It supports the widest range of chat platforms (24+, including niche channels like iMessage, Nostr, Teams, Line, and Twitch), and it also has a mature community skills marketplace.

How should beginners choose? In one sentence:

• If you want an agent that “gets smarter the more you use it,” or you need WeChat/Feishu integration → choose Hermes.
• If you want the broadest channel coverage, prefer the Node/TS stack, or want to browse a skills marketplace → choose OpenClaw.
• If you can’t decide → you can install both on the same machine. They coexist without interfering with each other (their config directories are ~/.hermes and ~/.openclaw). In practice, many people—including me—run both.

Terminology: MCP (Model Context Protocol) is a general protocol for connecting agents to external tools, and both frameworks support it; a skill is a “skill package” that teaches an agent how to do a category of tasks (a SKILL.md instruction file plus supporting scripts); a provider is the model vendor behind your agent (for example GPT, Claude, or Kimi).

Here is how the two fit into the chain:

flowchart LR
    U["You message a chat app
(TG / WeChat / Feishu / Discord…)"] --> H["Hermes
(Python · self-improving skills)"]
    U --> O["OpenClaw
(Node.js · 24+ channel gateway)"]
    H --> P["Model Provider
(GPT / Claude / Kimi…)"]
    O --> P
    P --> R["agent thinks + calls tools"] --> U

1. Before You Install

System requirements:

• A Linux machine, or WSL2 on Windows (Windows Subsystem for Linux—the Linux subsystem inside Windows). The installation steps for both frameworks on WSL2 are exactly the same as on native Linux. macOS also works (OpenClaw uses launchd to manage services on macOS).
• Installing Hermes: you don’t need to prepare anything in advance. The official installer brings all dependencies with it (uv, Python 3.11, Node.js, ripgrep, ffmpeg).
• Installing OpenClaw: you need Node.js 20 or later installed first (check with node --version).
• A model API key (covered in detail in Chapter 4)—without a model, an agent is just an empty shell.

The whole process takes about 15–30 minutes, most of which is waiting for downloads.

2. Install Hermes (Python, the self-improving camp)

Step 1: One-command install

1

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

After installation, everything lives under ~/.hermes, completely isolated from your system Python (it won’t mess up your system environment).

Verify the installation:

1

hermes --version

If it says the hermes command cannot be found: the installer symlinked the command into ~/.local/bin. Check whether that directory is in your PATH (on WSL2 it usually is by default).

Step 2: Run the setup wizard

1

hermes setup

This interactive flow takes you through everything in one pass: choosing a model provider, configuring chat channels, and installing skills. If you prefer a web UI, use hermes setup --portal.

Step 3: Start the gateway and chat

1
2

hermes gateway setup    # Configure messaging channels (Telegram, etc.)
hermes gateway start    # Start the gateway

Then send a message to the bot in the chat app you configured. If it replies, you’re connected.

Step 4 (strongly recommended): Make it start on boot and keep running after you close the terminal

hermes gateway start runs inside your current terminal—once you close the terminal, it stops. To keep it running 24/7, use a systemd user service (Linux’s user-level background service manager).

Create the file ~/.config/systemd/user/hermes-gateway.service with the following contents (copy as-is; %h automatically expands to your home directory):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

[Unit]
Description=Hermes Agent Gateway - Messaging Platform Integration
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=%h/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main gateway run
WorkingDirectory=%h/.hermes
Environment="HERMES_HOME=%h/.hermes"
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

Then run:

1
2
3
4

systemctl --user daemon-reload
loginctl enable-linger $USER          # Key step: keep the service running even after logout / when you are not logged in
systemctl --user enable --now hermes-gateway.service
systemctl --user status hermes-gateway.service   # If you see active (running), you're good

Terminology: linger is a systemd switch. By default, your user services only run while you are logged in. With linger enabled, after the machine reboots, your service starts automatically without waiting for anyone to log in. This also applies in WSL2.

Hermes troubleshooting quick reference:

• Service won’t start → check logs with journalctl --user -u hermes-gateway.service -f. Nine times out of ten, Step 2 (hermes setup) wasn’t completed (missing model or channel config). Go back, finish it, then start again.
• Service logs show PATH mixed with Windows paths → this is normal in WSL2. It’s cosmetic; ignore it.

3. Install OpenClaw (Node.js, the multi-channel gateway camp)

Step 1: Install globally via npm

First confirm Node.js ≥ 20 (node --version), then:

1
2

npm install -g openclaw
openclaw --version

Step 2: Interactive configuration

1

openclaw configure

This walks you through everything in one pass: credentials, channels, gateway, and agent defaults. The config file is at ~/.openclaw/openclaw.json, while secrets are stored separately in ~/.openclaw/.env (secrets are never written into the config file; both projects follow this design).

Validate the config non-interactively:

1

openclaw config validate

Step 3: Install it as a system service and start it

This is where OpenClaw is easier than Hermes: it generates the systemd service for you, so you don’t need to hand-write a unit file:

1
2
3
4

openclaw gateway install    # Automatically create a systemd user service
openclaw gateway start      # Start it
openclaw gateway status     # Confirm it's running
loginctl enable-linger $USER   # Also recommended: enable linger (start on boot + keep running after logout)

For foreground debugging, run openclaw gateway run.

Step 4: Add chat channels

1

openclaw channels

Follow the prompts to add and log in to channels (Telegram/WhatsApp/Discord/Feishu… 24+ options), then send a test message in the corresponding app.

OpenClaw-specific pitfall: stale version warning (seen in real use)

If OpenClaw warns every time it runs: “your config was written by 2026.7.1-2, but the current command is 2026.6.8”—don’t panic; your config is not lost. The cause is that the globally installed npm binary is older than the version that originally wrote the config file (for example, you previously installed a newer dev version and then rolled back). Fix:

1. Make the openclaw command point to the version you actually want (adjust PATH or your Node version manager);
2. Run openclaw gateway uninstall && openclaw gateway install to reinstall the service using that same version;
3. Run openclaw gateway status --deep to confirm the service and version match.

4. Configure a Model Provider (same idea for both)

The agent framework itself does not include a model. You must connect it to an LLM provider before it has a “brain.”

Hermes: one interactive command to choose a model

1

hermes model

It lists available providers, automatically fetches each provider’s model list (/v1/models), and lets you choose the default model. The Nous-hosted provider supports OAuth login; on a browserless command-line machine, add --no-browser or --manual-paste. Refresh the provider list with hermes model --refresh.

The config is written to ~/.hermes/config.yaml and looks like this (structure only):

1
2
3
4
5
6
7
8

model:               # Default model
  provider: <name>
  api_mode: <mode>
providers:           # Named providers
  <name>:
    base_url: <https://...>
    api_mode: <mode>
    models: [...]

OpenClaw: configure wizard or field-level commands

The openclaw configure wizard includes model configuration. If you want to script precise changes to specific fields:

1
2
3
4
5

openclaw config file                    # Show config file path
openclaw config schema                  # Show the JSON schema for the config structure
openclaw config get providers.models    # Read a value by path
openclaw config set <path> <value>      # Set a value by path
openclaw config patch --file ./patch.json5   # Batch write with validation

Secrets go in ~/.openclaw/.env, and the config references the corresponding environment variable names (such as NEWAPI_KEY or CPAMC_KEY).

Advanced: connect a self-hosted proxy (CPA / NewAPI)

Both frameworks understand OpenAI-compatible APIs (the base_url + API key pattern). So if you run your own model proxy (for example CPA on :8317, or NewAPI), the integration is exactly the same:

1. Start the proxy;
2. Add a provider in the agent config, with base_url pointing to the proxy address;
3. Put the proxy API key into an environment variable;
4. Use hermes model or openclaw configure to set it as the default model.

Benefit: one local proxy can sit in front of multiple upstream models/keys, while the agent only talks to the proxy. Later, when you switch upstream models, you don’t need to change a single line of the agent config.

5. Skills: shared by both, install once and use in both places

Good news: Hermes and OpenClaw skill packages use the same format (the standard agent-skill format: a SKILL.md file + YAML front matter + supporting directories such as examples/ and scripts/), and they are downloaded from the same registries (skills.sh, ClawHub, GitHub, etc.). In testing, installing the same skill on both sides produced files that were byte-for-byte identical.

Their respective management commands:

1
2
3
4
5
6
7

# Hermes (more full-featured)
hermes skills browse / search / install / list / update / uninstall ...
hermes bundles        # Multi-skill bundles
hermes curator        # Unique feature: a background process that automatically improves skills from usage experience (self-improvement)

# OpenClaw (streamlined)
openclaw skills list / inspect / install

The only compatibility pitfall: the skill documentation is universal, but the scripts bundled inside a skill may be language-specific. If a skill’s scripts are written in Python, Hermes can run them out of the box; on the OpenClaw side, the machine needs Python installed. This is assessed skill by skill, not a framework-level issue.

6. Common Issues Quick Reference

7. Further Reading (full hands-on details for each topic)

• How to choose (detailed comparison): /posts/hermes-vs-openclaw/
• Install Hermes (full version): /posts/install-hermes-wsl2/
• Install OpenClaw (full version): /posts/install-openclaw-gateway/
• Configure models (full version): /posts/model-provider-setup/
• Skills interoperability (verification process): /posts/skills-portability-hermes-openclaw/
• Why self-host (essay): /posts/why-self-host-agents-and-agenthub/

Timeliness Note

All commands and configuration structures in this guide were verified against live instances on 2026-07-31 (Hermes v0.16.0, OpenClaw 2026.7.1-2). Both projects iterate quickly, so if you are reading this guide several months later, please treat the official documentation as the source of truth:

• Hermes: official quickstart
• OpenClaw: gateway CLI docs