mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-28 01:21:43 +00:00
docs: expand Docusaurus coverage across CLI, tools, skills, and skins (#1232)
- add code-derived reference pages for slash commands, tools, toolsets, bundled skills, and official optional skills - document the skin system and link visual theming separately from conversational personality - refresh quickstart, configuration, environment variable, and messaging docs to match current provider, gateway, and browser behavior - fix stale command, session, and Home Assistant configuration guidance
This commit is contained in:
Teknium
GitHub
parent
2bf6b7ad1a
commit
984f00e0b0
26 changed files with 1228 additions and 397 deletions
|
|
@ -202,7 +202,7 @@ Replace the ID with the actual channel ID (right-click → Copy Channel ID with
|
|||
|
||||
## Bot Behavior
|
||||
|
||||
- **Server channels**: The bot responds to all messages from allowed users in channels it can access. It does **not** require a mention or prefix — any message from an allowed user is treated as a prompt.
|
||||
- **Server channels**: By default the bot requires an `@mention` before it responds in server channels. You can disable that globally with `DISCORD_REQUIRE_MENTION=false` or allow specific channels to be mention-free via `DISCORD_FREE_RESPONSE_CHANNELS`.
|
||||
- **Direct messages**: DMs always work, even without the Message Content Intent enabled (Discord exempts DMs from this requirement). However, you should still enable the intent for server channel support.
|
||||
- **Conversations**: Each channel or DM maintains its own conversation context.
|
||||
|
||||
|
|
|
|||
|
|
@ -130,33 +130,22 @@ The Home Assistant gateway adapter connects via WebSocket and subscribes to `sta
|
|||
By default, **no events are forwarded**. You must configure at least one of `watch_domains`, `watch_entities`, or `watch_all` to receive events. Without filters, a warning is logged at startup and all state changes are silently dropped.
|
||||
:::
|
||||
|
||||
Configure which events the agent sees in `~/.hermes/config.yaml` under the Home Assistant platform's `extra` section:
|
||||
Configure which events the agent sees in `~/.hermes/gateway.json` under the Home Assistant platform's `extra` section:
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
messaging:
|
||||
platforms:
|
||||
homeassistant:
|
||||
extra:
|
||||
# Watch specific domains (recommended)
|
||||
watch_domains:
|
||||
- climate
|
||||
- binary_sensor
|
||||
- alarm_control_panel
|
||||
- light
|
||||
|
||||
# Watch specific entities (in addition to domains)
|
||||
watch_entities:
|
||||
- sensor.front_door_battery
|
||||
|
||||
# Ignore noisy entities
|
||||
ignore_entities:
|
||||
- sensor.uptime
|
||||
- sensor.cpu_usage
|
||||
- sensor.memory_usage
|
||||
|
||||
# Per-entity cooldown (seconds)
|
||||
cooldown_seconds: 30
|
||||
```json
|
||||
{
|
||||
"platforms": {
|
||||
"homeassistant": {
|
||||
"enabled": true,
|
||||
"extra": {
|
||||
"watch_domains": ["climate", "binary_sensor", "alarm_control_panel", "light"],
|
||||
"watch_entities": ["sensor.front_door_battery"],
|
||||
"ignore_entities": ["sensor.uptime", "sensor.cpu_usage", "sensor.memory_usage"],
|
||||
"cooldown_seconds": 30
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Setting | Default | Description |
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ hermes gateway status # Check service status
|
|||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/new` or `/reset` | Start fresh conversation |
|
||||
| `/new` or `/reset` | Start a fresh conversation |
|
||||
| `/model [provider:model]` | Show or change the model (supports `provider:model` syntax) |
|
||||
| `/provider` | Show available providers with auth status |
|
||||
| `/personality [name]` | Set a personality |
|
||||
|
|
@ -72,8 +72,13 @@ hermes gateway status # Check service status
|
|||
| `/stop` | Stop the running agent |
|
||||
| `/sethome` | Set this chat as the home channel |
|
||||
| `/compress` | Manually compress conversation context |
|
||||
| `/title [name]` | Set or show the session title |
|
||||
| `/resume [name]` | Resume a previously named session |
|
||||
| `/usage` | Show token usage for this session |
|
||||
| `/insights [days]` | Show usage insights and analytics |
|
||||
| `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display |
|
||||
| `/rollback [number]` | List or restore filesystem checkpoints |
|
||||
| `/background <prompt>` | Run a prompt in a separate background session |
|
||||
| `/reload-mcp` | Reload MCP servers from config |
|
||||
| `/update` | Update Hermes Agent to the latest version |
|
||||
| `/help` | Show available commands |
|
||||
|
|
@ -92,7 +97,7 @@ Sessions reset based on configurable policies:
|
|||
| Policy | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| Daily | 4:00 AM | Reset at a specific hour each day |
|
||||
| Idle | 120 min | Reset after N minutes of inactivity |
|
||||
| Idle | 1440 min | Reset after N minutes of inactivity |
|
||||
| Both | (combined) | Whichever triggers first |
|
||||
|
||||
Configure per-platform overrides in `~/.hermes/gateway.json`:
|
||||
|
|
@ -204,7 +209,7 @@ Each platform has its own toolset:
|
|||
| Slack | `hermes-slack` | Full tools including terminal |
|
||||
| Signal | `hermes-signal` | Full tools including terminal |
|
||||
| Email | `hermes-email` | Full tools including terminal |
|
||||
| Home Assistant | `hermes-gateway` | Full tools + HA device control (ha_list_entities, ha_get_state, ha_call_service, ha_list_services) |
|
||||
| Home Assistant | `hermes-homeassistant` | Full tools + HA device control (ha_list_entities, ha_get_state, ha_call_service, ha_list_services) |
|
||||
|
||||
## Next Steps
|
||||
|
||||
|
|
|
|||
|
|
@ -192,8 +192,8 @@ The adapter monitors the SSE connection and automatically reconnects if:
|
|||
| **Messages not received** | Check that `SIGNAL_ALLOWED_USERS` includes the sender's number in E.164 format (with `+` prefix) |
|
||||
| **"signal-cli not found on PATH"** | Install signal-cli and ensure it's in your PATH, or use Docker |
|
||||
| **Connection keeps dropping** | Check signal-cli logs for errors. Ensure Java 17+ is installed. |
|
||||
| **Group messages ignored** | `SIGNAL_GROUP_POLICY` defaults to `disabled`. Set to `allowlist` or `open`. |
|
||||
| **Bot responds to everyone** | Set `SIGNAL_DM_POLICY=pairing` or `allowlist` and configure `SIGNAL_ALLOWED_USERS` |
|
||||
| **Group messages ignored** | Configure `SIGNAL_GROUP_ALLOWED_USERS` with specific group IDs, or `*` to allow all groups. |
|
||||
| **Bot responds to no one** | Configure `SIGNAL_ALLOWED_USERS`, use DM pairing, or explicitly allow all users through gateway policy if you want broader access. |
|
||||
| **Duplicate messages** | Ensure only one signal-cli instance is listening on your phone number |
|
||||
|
||||
---
|
||||
|
|
@ -205,8 +205,8 @@ The adapter monitors the SSE connection and automatically reconnects if:
|
|||
:::
|
||||
|
||||
- Phone numbers are redacted in all log output
|
||||
- Use `SIGNAL_DM_POLICY=pairing` (default) for safe onboarding of new users
|
||||
- Keep groups disabled unless you specifically need group support
|
||||
- Use DM pairing or explicit allowlists for safe onboarding of new users
|
||||
- Keep groups disabled unless you specifically need group support, or allowlist only the groups you trust
|
||||
- Signal's end-to-end encryption protects message content in transit
|
||||
- The signal-cli session data in `~/.local/share/signal-cli/` contains account credentials — protect it like a password
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ the steps below.
|
|||
|
||||
| Component | Value |
|
||||
|-----------|-------|
|
||||
| **Library** | `@slack/bolt` (Socket Mode) |
|
||||
| **Library** | `slack-bolt` / `slack_sdk` for Python (Socket Mode) |
|
||||
| **Connection** | WebSocket — no public URL required |
|
||||
| **Auth tokens needed** | Bot Token (`xoxb-`) + App-Level Token (`xapp-`) |
|
||||
| **User identification** | Slack Member IDs (e.g., `U01ABC2DEF3`) |
|
||||
|
|
|
|||
|
|
@ -6,13 +6,10 @@ description: "Set up Hermes Agent as a WhatsApp bot via the built-in Baileys bri
|
|||
|
||||
# WhatsApp Setup
|
||||
|
||||
Hermes connects to WhatsApp through a built-in bridge using [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js)
|
||||
(Baileys-based). This works by emulating a WhatsApp Web session — **not** through the official
|
||||
WhatsApp Business API. No Meta developer account or Business verification is required.
|
||||
Hermes connects to WhatsApp through a built-in bridge based on **Baileys**. This works by emulating a WhatsApp Web session — **not** through the official WhatsApp Business API. No Meta developer account or Business verification is required.
|
||||
|
||||
:::warning Unofficial API — Ban Risk
|
||||
WhatsApp does **not** officially support third-party bots outside the Business API. Using
|
||||
whatsapp-web.js carries a small risk of account restrictions. To minimize risk:
|
||||
WhatsApp does **not** officially support third-party bots outside the Business API. Using a third-party bridge carries a small risk of account restrictions. To minimize risk:
|
||||
- **Use a dedicated phone number** for the bot (not your personal number)
|
||||
- **Don't send bulk/spam messages** — keep usage conversational
|
||||
- **Don't automate outbound messaging** to people who haven't messaged first
|
||||
|
|
@ -20,7 +17,7 @@ whatsapp-web.js carries a small risk of account restrictions. To minimize risk:
|
|||
|
||||
:::warning WhatsApp Web Protocol Updates
|
||||
WhatsApp periodically updates their Web protocol, which can temporarily break compatibility
|
||||
with whatsapp-web.js. When this happens, Hermes will update the bridge dependency. If the
|
||||
with third-party bridges. When this happens, Hermes will update the bridge dependency. If the
|
||||
bot stops working after a WhatsApp update, pull the latest Hermes version and re-pair.
|
||||
:::
|
||||
|
||||
|
|
@ -38,21 +35,7 @@ bot stops working after a WhatsApp update, pull the latest Hermes version and re
|
|||
- **Node.js v18+** and **npm** — the WhatsApp bridge runs as a Node.js process
|
||||
- **A phone with WhatsApp** installed (for scanning the QR code)
|
||||
|
||||
**On Linux headless servers**, you also need Chromium/Puppeteer dependencies:
|
||||
|
||||
```bash
|
||||
# Debian / Ubuntu
|
||||
sudo apt-get install -y \
|
||||
libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
|
||||
libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 \
|
||||
libpango-1.0-0 libcairo2 libasound2 libxshmfence1
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install -y \
|
||||
nss atk at-spi2-atk cups-libs libdrm libxkbcommon \
|
||||
libXcomposite libXdamage libXrandr mesa-libgbm \
|
||||
pango cairo alsa-lib
|
||||
```
|
||||
Unlike older browser-driven bridges, the current Baileys-based bridge does **not** require a local Chromium or Puppeteer dependency stack.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -112,9 +95,6 @@ Add the following to your `~/.hermes/.env` file:
|
|||
WHATSAPP_ENABLED=true
|
||||
WHATSAPP_MODE=bot # "bot" or "self-chat"
|
||||
WHATSAPP_ALLOWED_USERS=15551234567 # Comma-separated phone numbers (with country code, no +)
|
||||
|
||||
# Optional
|
||||
WHATSAPP_HOME_CONTACT=15551234567 # Default contact for proactive/scheduled messages
|
||||
```
|
||||
|
||||
Then start the gateway:
|
||||
|
|
@ -130,12 +110,11 @@ The gateway starts the WhatsApp bridge automatically using the saved session.
|
|||
|
||||
## Session Persistence
|
||||
|
||||
The whatsapp-web.js `LocalAuth` strategy saves your session to the `.wwebjs_auth` folder inside
|
||||
your Hermes data directory (`~/.hermes/`). This means:
|
||||
The Baileys bridge saves its session under `~/.hermes/whatsapp/session`. This means:
|
||||
|
||||
- **Sessions survive restarts** — you don't need to re-scan the QR code every time
|
||||
- The session data includes encryption keys and device credentials
|
||||
- **Do not share or commit the `.wwebjs_auth` folder** — it grants full access to the WhatsApp account
|
||||
- **Do not share or commit this session directory** — it grants full access to the WhatsApp account
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -170,9 +149,9 @@ Hermes supports voice on WhatsApp:
|
|||
|---------|----------|
|
||||
| **QR code not scanning** | Ensure terminal is wide enough (60+ columns). Try a different terminal. Make sure you're scanning from the correct WhatsApp account (bot number, not personal). |
|
||||
| **QR code expires** | QR codes refresh every ~20 seconds. If it times out, restart `hermes whatsapp`. |
|
||||
| **Session not persisting** | Check that `~/.hermes/.wwebjs_auth/` exists and is writable. On Docker, mount this as a volume. |
|
||||
| **Logged out unexpectedly** | WhatsApp unlinks devices after ~14 days of phone inactivity. Keep the phone on and connected to WiFi. Re-pair with `hermes whatsapp`. |
|
||||
| **"Execution context was destroyed"** | Chromium crashed. Install the Puppeteer dependencies listed in Prerequisites. On low-RAM servers, add swap space. |
|
||||
| **Session not persisting** | Check that `~/.hermes/whatsapp/session` exists and is writable. If containerized, mount it as a persistent volume. |
|
||||
| **Logged out unexpectedly** | WhatsApp unlinks devices after long inactivity. Keep the phone on and connected to the network, then re-pair with `hermes whatsapp` if needed. |
|
||||
| **Bridge crashes or reconnect loops** | Restart the gateway, update Hermes, and re-pair if the session was invalidated by a WhatsApp protocol change. |
|
||||
| **Bot stops working after WhatsApp update** | Update Hermes to get the latest bridge version, then re-pair. |
|
||||
| **Messages not being received** | Verify `WHATSAPP_ALLOWED_USERS` includes the sender's number (with country code, no `+` or spaces). |
|
||||
|
||||
|
|
@ -186,8 +165,8 @@ of authorized users. Without this setting, the gateway will **deny all incoming
|
|||
safety measure.
|
||||
:::
|
||||
|
||||
- The `.wwebjs_auth` folder contains full session credentials — protect it like a password
|
||||
- Set file permissions: `chmod 700 ~/.hermes/.wwebjs_auth`
|
||||
- The `~/.hermes/whatsapp/session` directory contains full session credentials — protect it like a password
|
||||
- Set file permissions: `chmod 700 ~/.hermes/whatsapp/session`
|
||||
- Use a **dedicated phone number** for the bot to isolate risk from your personal account
|
||||
- If you suspect compromise, unlink the device from WhatsApp → Settings → Linked Devices
|
||||
- Phone numbers in logs are partially redacted, but review your log retention policy
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue