How to Turn Your Linux Server into a WeChat-Controlled AI Assistant with Hermes

A long‑running Linux machine that can take your commands from WeChat, run tasks on its own, and push results back to your phone – that’s exactly what Hermes delivers. This isn’t a remote control for Codex; it’s a persistent agent that lives on your server, understands natural language requests, and acts on files, terminals, and scheduled jobs without you sitting at a terminal.

In practice, getting this up and running takes four main steps: install Hermes, log in with your Codex subscription, scan a QR code to connect WeChat, and approve the first pairing request from a stranger. The real friction points are three: the Gateway stops after SSH logout, the default WeChat privacy policy isn’t pairing mode, and picking the wrong login option during Codex authentication. This guide walks through every step, the exact commands, and how to recover when something stalls.

Hermes vs. Codex Remote: What’s Actually Running on Your Machine

Many first‑timers think Hermes is a way to control Codex from WeChat. That’s not wrong, but it misses the core difference – Hermes is an execution agent, not a remote terminal for Codex.

  • Codex Remote is for ad‑hoc coding: you connect, ask it to modify code, run tests, show diffs, and you wait for the result. It’s session‑based and human‑initiated.

  • Hermes works the other way: tasks can be scheduled, run in the background, and deliver results proactively. It can read files, execute shell commands, manage services, and even send you daily digests – all without you opening a terminal. You can ask it to check a service status while you’re out, or set a cron‑like job to email a report to your WeChat every morning.

You can run both side‑by‑side. Codex Remote is still better for quick code edits; Hermes handles recurring and background workflows. Installing Hermes does not break Codex Remote.

What You Need Before Starting

This tutorial assumes you are connecting from a Mac to a remote Linux machine, installing Hermes there, and linking it to your personal WeChat. Confirm you have:

  • A Linux or macOS machine that stays online (a VPS or home server works).
  • SSH credentials (username, IP address, and password or key) for that machine.
  • A ChatGPT account that can access Codex.
  • A personal WeChat account.

Git must be installed on the Linux/macOS side – check with git --version.

This guide does not cover Windows, Docker, NAS appliances, enterprise WeChat, or group chatbots. The WeChat integration uses an iLink bot identity; group chats are unreliable, so we use direct private messages.

Step 1: Install Hermes on the Target Machine

SSH into your Linux machine:

ssh <username>@<server-address>

Accept the host key if prompted, then enter your password.

Inside, verify Git:

git --version

Then run the official install command. The installer handles Python, uv, Node.js, and other dependencies:

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

If you install directly on macOS, use source ~/.zshrc.

Check that Hermes is available:

command -v hermes
hermes --version
hermes doctor

You should see the path, version, and no fatal errors from doctor. Warnings are usually fine – follow any on‑screen suggestions.

Step 2: Log in to Codex and Select a Model

The Provider is how Hermes calls an AI model. We use openai‑codex, which authenticates via your ChatGPT/Codex account – no separate API key needed.

On the Linux machine, run:

hermes model

Follow the menu:

  1. Choose OpenAI.
  2. Choose ChatGPT or Codex Subscription.
  3. Open the URL shown in your browser (on your Mac or phone) and log in to your ChatGPT account.
  4. Back in the terminal, pick an available model.

Verify the configuration:

hermes config get model
hermes status

Look for Provider: openai-codex and a non‑empty model name. If no models appear, rerun hermes model and double‑check you used the account that has Codex access.

Step 3: Connect WeChat – Gateway Setup and Pairing

The Gateway is a persistent service that relays messages between WeChat and Hermes. It receives incoming messages, passes them to the agent, and sends replies back.

Run:

hermes gateway setup

Select Weixin from the list. When asked about private chat access, choose pairing – not open. The open mode lets any WeChat user talk to your machine without approval, which you almost never want.

A QR code appears in the terminal. Scan it with your WeChat app and confirm. Once you see “WeChat connected”, the credentials are saved. This creates a separate iLink bot identity – it does not hand over your personal WeChat account.

Now install and start the Gateway as a background service:

hermes gateway install
hermes gateway start
hermes gateway status

It should show running.

Critical for remote machines: user services stop when you log out of SSH. To keep it alive, run:

sudo loginctl enable-linger "$USER"
hermes gateway restart

If you don’t have sudo, ask your admin to run the first command. On a VPS or headless server, you can also install a system‑wide Gateway, but never run both user‑level and system‑level simultaneously.

After any configuration change, restart with:

hermes gateway restart

Step 4: Approve the First WeChat Pairing

In WeChat, send a message to the bot:

hello

The first time, the bot will reply that it doesn’t recognise you and provide a pairing code. If it answers directly without a code, the policy is not pairing – go back and rerun hermes gateway setup to change it.

Back on the Linux terminal, run:

hermes pairing list
hermes pairing approve weixin <pairing-code>

Replace <pairing-code> with the actual characters from WeChat. The code is one‑time; never share it.

After approval, send hello again in WeChat. A normal response means the full chain works.

Everyday Usage: Commands, Background Jobs, and Approvals

Once the link is live, WeChat becomes your interface to the Linux machine.

Check and switch models:

/model

This shows the current model, the provider, all available models, and the command to change the default.

Long‑running tasks: prefix with /bg. For example:

/bg Check the test results and last 20 Git commits in /home/punk/project/, and give me a Chinese summary when done.

The task runs in the background; you can keep chatting. Results arrive automatically when finished.

Approving commands: Hermes will ask for /approve in WeChat when a command needs confirmation. Use this only when it explicitly says “command pending approval”. Do not confuse this with the initial pairing approval, which is done via the terminal.

Final Validation: Test After SSH Logout

Don’t stop after one hello reply. Run this full validation:

  1. Send /status in WeChat – confirm it returns session, model, and provider info.
  2. Send a read‑only task:

    Only show me the OS type and current directory. Do not modify any file.

    Verify it returns machine info without altering anything.

  3. Exit SSH, wait a minute, and send hello again from WeChat. If you still get a reply, your Gateway survives logout – mission accomplished.

Quick Checklist

  • [ ] SSH into target Linux, verify Git exists (git --version)
  • [ ] Run official install, source profile, check hermes --version and hermes doctor
  • [ ] hermes model – choose OpenAI → ChatGPT or Codex Subscription → web auth → pick model
  • [ ] hermes gateway setup – select Weixin, pairing policy, scan QR
  • [ ] hermes gateway install && hermes gateway start
  • [ ] sudo loginctl enable-linger "$USER" (essential for remote Linux)
  • [ ] Send hello in WeChat, obtain pairing code
  • [ ] Terminal: hermes pairing approve weixin <pairing-code>
  • [ ] Send hello again, confirm reply
  • [ ] Test /status, read‑only task, and logout‑persistence

FAQ – Troubleshooting Common Issues

Terminal says hermes: command not found

Run source ~/.bashrc (Linux) or source ~/.zshrc (macOS). If still missing, open a new shell.

No Weixin option in gateway setup

Install the messaging extension first:

cd ~/.hermes/hermes-agent
uv pip install -e ".[messaging]"
hermes gateway setup

Gateway shows running but WeChat doesn’t reply

Check logs and restart:

hermes gateway status
hermes logs gateway -n 120
hermes gateway restart

If logs mention missing WEIXIN_ACCOUNT_ID or WEIXIN_TOKEN, rerun hermes gateway setup to re‑scan and save credentials.

QR code expired or scan doesn’t connect

QR codes expire. Exit the wizard and rerun hermes gateway setup. If the terminal can’t display the QR, open the URL provided in the terminal in your browser.

WeChat stops replying after SSH logout

You missed the enable-linger step. Re‑SSH and run:

sudo loginctl enable-linger "$USER"
hermes gateway restart
hermes gateway status

“Another Gateway is using this WeChat token”

A single WeChat token can only be used by one Gateway instance. Check if another terminal, service, or machine is running the same account. Stop the duplicate and restart yours.

Codex authentication expired or model unavailable

Re‑authenticate:

hermes model
hermes gateway restart

Models may vary by account and version – rely on the list from hermes model and /model in WeChat.

WeChat keeps saying it doesn’t know you

Send hello again to get a fresh pairing code, then approve it:

hermes pairing list
hermes pairing approve weixin <new-code>

I don’t understand the error messages

Run the unified diagnostic:

hermes doctor

It checks installation, environment, and missing dependencies. If you still need help, share the output of hermes doctor and hermes logs gateway -n 120 with your support contact – but remove any tokens, account IDs, and server addresses first.

Validation date: 2026-09-07. Tested with Hermes Agent v0.21.0. Model names and menu labels may change with versions and accounts – always refer to the actual output from the terminal and WeChat. This article does not constitute security advice; after linking WeChat, Hermes can read files and run commands. Always run it under a regular Linux user, not root, and avoid giving it sensitive keys or production credentials.

About the author: Punk – M.Sc. in Management from USTC, AI prompt and tutorial writer, creator of Punk Skills series, 8‑figure earnings in 3 months, Learn in Public advocate, 2.4M views on FDE articles. Follow @AdrianPunk115 on X.