How to Set Up Hermes Slack on ZimaOS and Fix Gateway Errors

Hermes Agent can connect to Slack without exposing a public webhook endpoint because its current Slack integration uses Socket Mode. The community report behind this page reached most of that setup successfully: the user created a new Slack app, obtained an xoxb- bot token and an xapp- app-level token, ran hermes gateway setup inside the ZimaOS Hermes container, and invited the bot into a Slack channel.

The failure happened when Hermes tried to restart its gateway. The CLI returned PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock', and although the app appeared in Slack, an @Hermes mention produced no response. Current ZimaSpace documentation now explicitly identifies /opt/data permission errors as a Hermes ownership problem that can occur after gateway operations have previously been run as root. Current Hermes Slack documentation also adds several setup requirements that are safer to verify than manually guessing scopes.

What Happened in the ZimaOS Hermes Slack Report

The May 2026 community post used a clean ZimaOS Hermes installation and a new Slack workspace. The user created a Slack app with Socket Mode enabled, copied both required token types, and configured Slack through the Hermes gateway wizard.

The key sequence was:

1. Create a Slack app and enable Socket Mode.
2. Obtain a Bot User OAuth Token beginning with xoxb-.
3. Obtain an App-Level Token beginning with xapp-.
4. Run hermes gateway setup inside the Hermes container.
5. Select Slack and enter the two tokens.
6. Accept the prompt to restart the gateway.

The restart failed with:

PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock'

The user then restarted the gateway from the Hermes Web UI, invited @Hermes into a Slack channel, and saw Slack confirm the app was added. However, a channel mention still received no reply. That means there were potentially two layers to troubleshoot: the ZimaOS-side gateway process and the Slack-side event configuration.

Use the Current Hermes Slack Manifest Instead of Rebuilding Every Scope Manually

Current Hermes documentation recommends generating a Slack app manifest. This is safer than manually recreating every OAuth scope, slash command, event subscription, and Socket Mode setting from memory.

Inside a current Hermes environment, generate the manifest with:

hermes slack manifest --agent-view --write

The generated file is written to:

~/.hermes/slack-manifest.json

Then create a new Slack app from that manifest in Slack's app administration interface. Current Hermes documentation explains that the manifest declares the built-in commands, required scopes, event subscriptions, and Socket Mode configuration together.

For the current upstream procedure, see the Hermes Agent Slack setup guide.

The Two Slack Tokens Hermes Needs

Hermes uses two different Slack credentials, and they are not interchangeable:

• Bot token: begins with xoxb- and becomes SLACK_BOT_TOKEN.
• App-level token: begins with xapp-, must support Socket Mode, and becomes SLACK_APP_TOKEN.

A current Hermes environment file can contain:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_ALLOWED_USERS=U01ABC2DEF3

SLACK_ALLOWED_USERS uses Slack Member IDs, not display names. If the tokens are correct but the requesting user is not allowed, Hermes may still appear connected while refusing to process that user's messages.

Never publish real xoxb- or xapp- values in a community post, screenshot, Git repository, or support log. Revoke and regenerate a token if it has been exposed.

Channel Mentions Require the Correct Slack Events

A bot being visible in a channel is not proof that Slack is delivering message events to Hermes. Current Hermes documentation calls out event subscriptions as a common source of failures.

For a manually configured Slack app, verify the events required by the current Hermes version. The current documentation includes events such as:

• app_mention for direct @Hermes mentions.
• message.channels for messages in public channels where the bot is a member.
• message.groups when private-channel support is needed.
• message.im for direct messages.

If you change scopes or event subscriptions after installing the Slack app, reinstall the app to the workspace when Slack prompts you. Otherwise the displayed settings and the permissions actually granted to the installed bot can differ.

Invite Hermes to the Channel Before Testing

Hermes does not automatically join every Slack channel. Invite it explicitly:

/invite @Hermes

Then test a simple mention from a Slack user whose Member ID is included in the Hermes allowlist. If direct messages work but public-channel mentions do not, focus on app_mention, message.channels, channel membership, and the installed app permissions before changing the ZimaOS networking configuration.

Why /opt/data/gateway.lock Can Return Permission Denied

The current ZimaSpace Hermes Agent guide now documents an /opt/data permission problem. It states that this is usually caused by running Hermes Gateway as root previously, leaving root-owned files inside $HERMES_HOME.

ZimaSpace's documented container workflow is to enter the container as the dedicated hermes user:

docker exec -it -u hermes hermes bash

Then activate the Hermes virtual environment:

source /opt/hermes/.venv/bin/activate

Messaging configuration can then be opened with:

hermes gateway setup

If the gateway immediately fails on /opt/data/gateway.lock, do not repeatedly run the entire gateway as root. First confirm the identity and ownership involved:

id
ls -ld /opt/data
ls -l /opt/data/gateway.lock 2>/dev/null

The current ZimaSpace guide recommends checking Hermes logs in the ZimaOS Dashboard and using a root shell only temporarily when file ownership must be repaired. Do not apply a blind recursive ownership change to /opt/data unless you have verified which files belong to Hermes and what user/group the installed ZimaOS package expects.

Restart the Gateway Only After Hermes Can Write Its Runtime Files

In the community report, clicking Restart Gateway in the Web UI was not enough to prove the gateway was healthy. If the underlying process cannot create or update its lock file, the UI action can still leave the Slack integration unavailable.

After correcting the actual ownership issue, enter the container as the hermes user, activate the environment, and run or restart the gateway using the commands supported by your installed Hermes release. Watch the ZimaOS Hermes logs while sending a test Slack message.

A useful troubleshooting split is:

• No gateway startup: investigate /opt/data permissions and Hermes logs.
• Gateway runs, but no Slack connection: verify the xapp- token and Socket Mode.
• Slack connection exists, but channel mentions are silent: verify app events, channel membership, reinstall status, and SLACK_ALLOWED_USERS.
• DM works but channel does not: focus on channel events and permissions rather than the model provider.

Use the Hermes Web Dashboard for Status, Not as the Only Health Check

The ZimaSpace guide exposes the Hermes Web Dashboard at:

http://ZIMAOS_LAN_IP:9119

The dashboard can show running status, sessions, and model settings. It is useful for restarting and observing the gateway, but combine it with logs when a process-level permission error occurs.

Hermes Slack on ZimaOS Troubleshooting Checklist

1. Confirm the Hermes model configuration itself works before adding Slack.
2. Enter the ZimaOS container as the hermes user, not as root for normal gateway operation.
3. Use the current Hermes Slack manifest when possible instead of manually guessing scopes.
4. Confirm the xoxb- bot token and xapp- app token belong to the same intended Slack app.
5. Confirm Socket Mode is enabled.
6. Confirm your Slack Member ID is in SLACK_ALLOWED_USERS.
7. Invite Hermes to the channel you are testing.
8. Verify app_mention and the required message events are subscribed.
9. Reinstall the Slack app after changing scopes or event subscriptions when Slack requests it.
10. If /opt/data/gateway.lock fails, inspect ownership and ZimaOS Hermes logs before restarting again.
11. After the gateway is healthy, test a DM and one channel mention separately.

Hermes Slack on ZimaOS FAQ

What does the gateway.lock permission error mean?

It means the Hermes process cannot access the runtime lock file at the expected location. Current ZimaSpace documentation says an /opt/data permission error is usually associated with files left root-owned after Hermes Gateway was run as root.

Should I run Hermes Gateway as root to fix it?

Not as the normal solution. ZimaSpace documents entering the container as the hermes user for normal Hermes operations. A root shell should only be used temporarily when you have confirmed that ownership needs repair.

Why is the Hermes bot visible in Slack but not replying?

Being installed and invited only proves that Slack knows about the app. Hermes still needs a healthy gateway, valid Socket Mode connection, correct event subscriptions, appropriate workspace permissions, and an allowed Slack Member ID.

Does Hermes Slack need a public webhook URL?

No. Current Hermes Slack integration uses Socket Mode over WebSockets, so the Hermes instance can remain behind a firewall without a public inbound Slack webhook endpoint.

What is the best current way to configure the Slack app?

Use the current Hermes-generated Slack manifest when your installed Hermes release supports it. That reduces errors caused by missing scopes, event subscriptions, or slash-command definitions.