docs: 30-day overhaul — correctness audit, PR coverage, Nous Portal weave, sidebar reorg (#33782)
* docs(audit): correctness pass across getting-started, reference, features, messaging, developer-guide, guides, integrations, user-guide * docs: add PR coverage for last 30d + Nous Portal weave + nav reorg + build fixes - Add docs for top user-visible PRs that shipped without docs (api-server session control, kanban features, telegram pin/edit, provider client tag, xAI retired-model migration, cron name lookup, --branch update flag, etc.) - Apply Nous Portal weave across 23 pages (tasteful one-liners on getting-started/learning-path, configuration, overview, vision, x-search, credential-pools, provider-routing, cron, codex-runtime, profiles, docker, messaging/index, multiple guides, plus FAQ + index promotion) - Reorganize sidebar: split Messaging into Popular/M365/Chinese/Other, Reference into Command/Configuration/Tools-Skills sub-categories, add orphan developer-guide pages (web-search-provider-plugin, browser-supervisor), move features from Integrations back to Features, fold lone spotify into Media & Web. - Regenerate skill stubs + catalogs (kanban-codex-lane, hermes-s6-container- supervision, web-pentest) - Fix broken anchor links (security/cron, configuration/fallback, telegram large-files, adding-platform-adapters step-by-step)
This commit is contained in:
Teknium
@@ -13,6 +13,8 @@ process does not need a public URL, a tunnel, or a TLS certificate. It connects,
|
||||
authenticates, and listens on a subscription — the same way a Telegram bot listens
|
||||
on a token.
|
||||
|
||||
> Run `hermes gateway setup` and pick **Google Chat** for a guided walk-through.
|
||||
|
||||
:::note Workspace edition
|
||||
Google Chat is part of Google Workspace. You can use this integration with a
|
||||
personal Workspace (`@yourdomain.com` registered through Google) or a work
|
||||
@@ -237,7 +239,7 @@ specifically, as the user who asked for the file.
|
||||
4. On the host, register the client with Hermes:
|
||||
|
||||
```bash
|
||||
python -m gateway.platforms.google_chat_user_oauth \
|
||||
python -m plugins.platforms.google_chat.oauth \
|
||||
--client-secret /path/to/client_secret.json
|
||||
```
|
||||
|
||||
@@ -330,7 +332,7 @@ The one-time host setup wasn't done. From a terminal on the host that runs
|
||||
Hermes:
|
||||
|
||||
```bash
|
||||
python -m gateway.platforms.google_chat_user_oauth \
|
||||
python -m plugins.platforms.google_chat.oauth \
|
||||
--client-secret /path/to/client_secret.json
|
||||
```
|
||||
|
||||
|
||||
@@ -250,3 +250,26 @@ Agent automatically:
|
||||
entity_id="light.hallway")
|
||||
3. Sends notification: "Front door opened. Hallway lights turned on."
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Environment variables not picked up.**
|
||||
The adapter reads credentials from `~/.hermes/.env` (auto-merged at startup) or
|
||||
from `config.yaml`. Double-check the file lives under the active Hermes profile
|
||||
home and that there's no stray quoting around the URL/token. Restart the gateway
|
||||
after editing — env changes are only applied on process start.
|
||||
|
||||
**`conversation entity not found` / agent never replies.**
|
||||
Home Assistant's conversation API requires a configured *Assist* conversation
|
||||
agent. In HA, open **Settings → Voice assistants → Add assistant** and note the
|
||||
resulting entity id (looks like `conversation.home_assistant` or
|
||||
`conversation.openai_<name>`). Set that entity id in the adapter's
|
||||
`conversation_entity` setting; the default may not exist on your instance.
|
||||
|
||||
**REST auth failing (`401 Unauthorized`).**
|
||||
The token must be a *Long-Lived Access Token* created from your HA user profile
|
||||
page (**Profile → Security → Long-lived access tokens**). Short-lived UI
|
||||
session tokens won't work. Also verify the base URL includes the scheme and
|
||||
port (e.g. `http://homeassistant.local:8123`) and is reachable from the host
|
||||
running Hermes — `curl -H "Authorization: Bearer <token>" <url>/api/` should
|
||||
return `{"message": "API running."}`.
|
||||
|
||||
@@ -10,6 +10,10 @@ Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Ho
|
||||
|
||||
For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see [Voice Mode](/user-guide/features/voice-mode) and [Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes).
|
||||
|
||||
:::tip
|
||||
Bots need both a model provider and tool providers (TTS, web). A [Nous Portal](/integrations/nous-portal) subscription bundles all of them.
|
||||
:::
|
||||
|
||||
## Platform Comparison
|
||||
|
||||
| Platform | Voice | Images | Files | Threads | Reactions | Typing | Streaming |
|
||||
|
||||
@@ -10,6 +10,8 @@ Run Hermes Agent as a [LINE](https://line.me/) bot via the official LINE Messagi
|
||||
|
||||
LINE is the dominant messaging app in Japan, Taiwan, and Thailand. If your users live there, this is how they reach you.
|
||||
|
||||
> Run `hermes gateway setup` and pick **LINE** for a guided walk-through.
|
||||
|
||||
## How the bot responds
|
||||
|
||||
| Context | Behavior |
|
||||
|
||||
@@ -36,12 +36,13 @@ Or via env vars in `~/.hermes/.env` (auto-merged on startup):
|
||||
|
||||
```bash
|
||||
MSGRAPH_WEBHOOK_ENABLED=true
|
||||
MSGRAPH_WEBHOOK_HOST=127.0.0.1
|
||||
MSGRAPH_WEBHOOK_PORT=8646
|
||||
MSGRAPH_WEBHOOK_CLIENT_STATE=<generate-with-openssl-rand-hex-32>
|
||||
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings
|
||||
```
|
||||
|
||||
Note: the bind host is read from `extra.host` in `config.yaml` (see the example above); there is no `MSGRAPH_WEBHOOK_HOST` env-var override.
|
||||
|
||||
Start the gateway: `hermes gateway run`. The listener exposes:
|
||||
|
||||
- `POST /msgraph/webhook` — change notifications from Graph
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
ntfy makes a great lightweight push channel for Hermes: subscribe to a topic from the [ntfy mobile app](https://ntfy.sh/docs/subscribe/phone/), send messages to the topic to talk to the agent, get the response back on your phone.
|
||||
|
||||
> Run `hermes gateway setup` and pick **ntfy** for a guided walk-through.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A topic name (any unique string — `hermes-myname-2026` works fine)
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
[SimpleX Chat](https://simplex.chat/) is a private, decentralised messaging platform where users own their contacts and groups. Unlike other platforms, SimpleX assigns no persistent user IDs — every contact is identified by an opaque internal ID generated at connection time, which makes it one of the most private messengers available.
|
||||
|
||||
> Run `hermes gateway setup` and pick **SimpleX** for a guided walk-through.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- The **simplex-chat** CLI installed and running as a daemon
|
||||
|
||||
@@ -8,6 +8,10 @@ description: "Set up the Microsoft Teams meeting summary pipeline with Microsoft
|
||||
|
||||
Use the Teams meeting pipeline when you want Hermes to ingest Microsoft Graph meeting events, fetch transcripts first, fall back to recordings plus STT when needed, and deliver a structured summary to downstream sinks.
|
||||
|
||||
Prerequisites: see [Microsoft Teams](./teams.md) for the underlying bot/credential setup.
|
||||
|
||||
> Run `hermes gateway setup` and pick **Teams Meetings** for a guided walk-through.
|
||||
|
||||
This page focuses on setup and enablement:
|
||||
- Graph credentials
|
||||
- webhook listener configuration
|
||||
|
||||
@@ -10,6 +10,8 @@ Connect Hermes Agent to Microsoft Teams as a bot. Unlike Slack's Socket Mode, Te
|
||||
|
||||
Need meeting summaries from Microsoft Graph events rather than normal bot conversations? Use the dedicated setup page: [Teams Meetings](/user-guide/messaging/teams-meetings).
|
||||
|
||||
> Run `hermes gateway setup` and pick **Microsoft Teams** for a guided walk-through.
|
||||
|
||||
## How the Bot Responds
|
||||
|
||||
| Context | Behavior |
|
||||
|
||||
@@ -319,7 +319,7 @@ With STT disabled, the gateway still downloads the voice/audio attachment into H
|
||||
|
||||
Your tools or skills can then read that path directly (e.g., hand it off to a local diarization pipeline, a richer transcription model, or upload it to long-term storage). The file extension reflects the original format Telegram delivered (`.ogg` for voice notes, `.mp3`/`.m4a`/etc. for audio attachments).
|
||||
|
||||
This pairs naturally with the [local Bot API server](#large-files-20mb--via-local-bot-api-server) section below, which lifts Telegram's 20MB getFile ceiling to 2GB — useful when the recordings you want to process are longer than a couple of minutes.
|
||||
This pairs naturally with the [local Bot API server](#large-files-20mb-via-local-bot-api-server) section below, which lifts Telegram's 20MB getFile ceiling to 2GB — useful when the recordings you want to process are longer than a couple of minutes.
|
||||
|
||||
### Outgoing Voice (Text-to-Speech)
|
||||
|
||||
@@ -1233,6 +1233,14 @@ HERMES_TELEGRAM_NOTIFICATIONS=all
|
||||
|
||||
Unknown values log a warning and fall back to `important`.
|
||||
|
||||
## Status messages edited in place
|
||||
|
||||
The Telegram adapter routes recurring agent status callbacks (e.g. "Compressing context…", "Calling tool…") through `send_or_update_status()`, which keeps a `{(chat_id, status_key) → message_id}` cache and **edits the existing bubble** on subsequent emits instead of appending a new one each time. Distinct `status_key` values get their own messages; distinct chats never collide. If the edit fails (e.g. the user deleted the message, or it's older than Telegram allows for edits), the cache entry is dropped and the next emit posts a fresh message and re-caches its ID. No config required — this is the default Telegram behavior. Other adapters that don't implement `send_or_update_status` fall through to plain `send()` unchanged.
|
||||
|
||||
## Pin incoming user message during agent turn
|
||||
|
||||
When a user sends a message that triggers an agent turn, the Telegram adapter pins that incoming message for the duration of the turn and unpins it when the response is finished — a lightweight visual indicator that the bot is actively working on the message rather than ignoring it. The pin uses `disable_notification=true` to avoid extra pings. No config required.
|
||||
|
||||
## Security
|
||||
|
||||
:::warning
|
||||
|
||||
@@ -12,6 +12,10 @@ Hermes supports two WeCom integration modes:
|
||||
- **WeCom Callback** (this page) — self-built app, receives encrypted XML callbacks. Shows as a first-class app in users' WeCom sidebar. Supports multi-corp routing.
|
||||
:::
|
||||
|
||||
See also: [WeCom Bot](./wecom.md) for the bot-style integration.
|
||||
|
||||
> Run `hermes gateway setup` and pick **WeCom Callback** for a guided walk-through.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. You register a self-built application in the WeCom Admin Console
|
||||
@@ -147,3 +151,28 @@ The crypto implementation is compatible with Tencent's official WXBizMsgCrypt SD
|
||||
- **No typing indicators** — the callback model doesn't support typing status
|
||||
- **Text only** — currently supports text messages for input; image/file/voice input not yet implemented. The agent is aware of outbound media capabilities via the WeCom platform hint (images, documents, video, voice).
|
||||
- **Response latency** — agent sessions take 3–30 minutes; users see the reply when processing completes
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Signature verification failing.**
|
||||
WeCom signs every request with the **Token** you registered in the admin
|
||||
console. A mismatch between the token configured in Hermes and the token the
|
||||
admin console expects is the most common cause. Re-copy both the **Token** and
|
||||
**EncodingAESKey** from the admin console — they're easy to truncate. Whitespace
|
||||
in `~/.hermes/.env` values around `=` will also break signature checks. After
|
||||
fixing, restart `hermes gateway run`.
|
||||
|
||||
**Callback URL not reachable / verification step fails.**
|
||||
WeCom hits the public URL you registered. Confirm:
|
||||
1. Your reverse proxy / tunnel forwards `/wecom/callback` to the gateway's port.
|
||||
2. The URL in the admin console is HTTPS (WeCom rejects plain HTTP).
|
||||
3. From outside your network, `curl -i https://<your-domain>/wecom/callback`
|
||||
returns something other than a timeout (a 4xx without query params is fine —
|
||||
it just means the listener is reachable).
|
||||
|
||||
**Port not reachable / listener not bound.**
|
||||
Check `hermes gateway run` logs for the bound host/port. If the adapter bound to
|
||||
`127.0.0.1` you must front it with a reverse proxy or tunnel — WeCom's servers
|
||||
can't reach loopback. Set `extra.host: 0.0.0.0` in `config.yaml` (plus
|
||||
`allowed_source_cidrs` if exposing directly) or keep loopback and use a tunnel
|
||||
such as Cloudflare Tunnel / nginx.
|
||||
|
||||
@@ -8,6 +8,8 @@ description: "Connect Hermes Agent to WeCom via the AI Bot WebSocket gateway"
|
||||
|
||||
Connect Hermes to [WeCom](https://work.weixin.qq.com/) (企业微信), Tencent's enterprise messaging platform. The adapter uses WeCom's AI Bot WebSocket gateway for real-time bidirectional communication — no public endpoint or webhook needed.
|
||||
|
||||
See also: [WeCom Callback](./wecom-callback.md) for inbound webhook setup.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A WeCom organization account
|
||||
|
||||
@@ -8,6 +8,8 @@ description: "Set up Hermes Agent as a WhatsApp bot via the built-in Baileys bri
|
||||
|
||||
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.
|
||||
|
||||
> Run `hermes gateway setup` and pick **WhatsApp** for a guided walk-through.
|
||||
|
||||
:::warning Unofficial API — Ban 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)
|
||||
|
||||
Reference in New Issue
Block a user