better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/open-webui.md

@@ -0,0 +1,296 @@
+---
+sidebar_position: 8
+title: "Open WebUI"
+description: "Connect Open WebUI to Hermes Agent via the OpenAI-compatible API server"
+---
+
+# Open WebUI Integration
+
+[Open WebUI](https://github.com/open-webui/open-webui) (126k★) is the most popular self-hosted chat interface for AI. With Hermes Agent's built-in API server, you can use Open WebUI as a polished web frontend for your agent — complete with conversation management, user accounts, and a modern chat interface.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A["Open WebUI<br/>browser UI<br/>port 3000"]
+    B["hermes-agent<br/>gateway API server<br/>port 8642"]
+    A -->|POST /v1/chat/completions| B
+    B -->|SSE streaming response| A
+```
+
+Open WebUI connects to Hermes Agent's API server just like it would connect to OpenAI. Hermes handles the requests with its full toolset — terminal, file operations, web search, memory, skills — and returns the final response.
+
+:::important Runtime location
+The API server is a **Hermes agent runtime**, not a pure LLM proxy. For each request, Hermes creates a server-side `AIAgent` on the API-server host. Tool calls run where that API server is running.
+
+For example, if a laptop points Open WebUI or another OpenAI-compatible client at a Hermes API server on a remote machine, `pwd`, file tools, browser tools, local MCP tools, and other workspace tools run on the remote API-server host, not on the laptop.
+:::
+
+Open WebUI talks to Hermes server-to-server, so you do not need `API_SERVER_CORS_ORIGINS` for this integration.
+
+## Quick Setup
+
+### 1. Enable the API server
+
+```bash
+hermes config set API_SERVER_ENABLED true
+hermes config set API_SERVER_KEY your-secret-key
+```
+
+`hermes config set` auto-routes the flag to `config.yaml` and the secret to `~/.hermes/.env`. If the gateway is already running, restart it so the change takes effect:
+
+```bash
+hermes gateway stop && hermes gateway
+```
+
+### 2. Start Hermes Agent gateway
+
+```bash
+hermes gateway
+```
+
+You should see:
+
+```
+[API Server] API server listening on http://127.0.0.1:8642
+```
+
+### 3. Verify the API server is reachable
+
+```bash
+curl -s http://127.0.0.1:8642/health
+# {"status": "ok", ...}
+
+curl -s -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8642/v1/models
+# {"object":"list","data":[{"id":"hermes-agent", ...}]}
+```
+
+If `/health` fails, the gateway didn't pick up `API_SERVER_ENABLED=true` — restart it. If `/v1/models` returns `401`, your `Authorization` header doesn't match `API_SERVER_KEY`.
+
+### 4. Start Open WebUI
+
+```bash
+docker run -d -p 3000:8080 \
+  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
+  -e OPENAI_API_KEY=your-secret-key \
+  -e ENABLE_OLLAMA_API=false \
+  --add-host=host.docker.internal:host-gateway \
+  -v open-webui:/app/backend/data \
+  --name open-webui \
+  --restart always \
+  ghcr.io/open-webui/open-webui:main
+```
+
+`ENABLE_OLLAMA_API=false` suppresses the default Ollama backend, which would otherwise show up empty and clutter the model picker. Omit it if you actually have Ollama running alongside.
+
+First launch takes 15–30 seconds: Open WebUI downloads sentence-transformer embedding models (~150MB) the first time it starts. Wait for `docker logs open-webui` to settle before opening the UI.
+
+### 5. Open the UI
+
+Go to **http://localhost:3000**. Create your admin account (the first user becomes admin). You should see your agent in the model dropdown (named after your profile, or **hermes-agent** for the default profile). Start chatting!
+
+## Docker Compose Setup
+
+For a more permanent setup, create a `docker-compose.yml`:
+
+```yaml
+services:
+  open-webui:
+    image: ghcr.io/open-webui/open-webui:main
+    ports:
+      - "3000:8080"
+    volumes:
+      - open-webui:/app/backend/data
+    environment:
+      - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
+      - OPENAI_API_KEY=your-secret-key
+      - ENABLE_OLLAMA_API=false
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: always
+
+volumes:
+  open-webui:
+```
+
+Then:
+
+```bash
+docker compose up -d
+```
+
+## Configuring via the Admin UI
+
+If you prefer to configure the connection through the UI instead of environment variables:
+
+1. Log in to Open WebUI at **http://localhost:3000**
+2. Click your **profile avatar** → **Admin Settings**
+3. Go to **Connections**
+4. Under **OpenAI API**, click the **wrench icon** (Manage)
+5. Click **+ Add New Connection**
+6. Enter:
+   - **URL**: `http://host.docker.internal:8642/v1`
+   - **API Key**: the exact same value as `API_SERVER_KEY` in Hermes
+7. Click the **checkmark** to verify the connection
+8. **Save**
+
+Your agent model should now appear in the model dropdown (named after your profile, or **hermes-agent** for the default profile).
+
+:::warning
+Environment variables only take effect on Open WebUI's **first launch**. After that, connection settings are stored in its internal database. To change them later, use the Admin UI or delete the Docker volume and start fresh.
+:::
+
+## API Type: Chat Completions vs Responses
+
+Open WebUI supports two API modes when connecting to a backend:
+
+| Mode | Format | When to use |
+|------|--------|-------------|
+| **Chat Completions** (default) | `/v1/chat/completions` | Recommended. Works out of the box. |
+| **Responses** (experimental) | `/v1/responses` | For server-side conversation state via `previous_response_id`. |
+
+### Using Chat Completions (recommended)
+
+This is the default and requires no extra configuration. Open WebUI sends standard OpenAI-format requests and Hermes Agent responds accordingly. Each request includes the full conversation history.
+
+### Using Responses API
+
+To use the Responses API mode:
+
+1. Go to **Admin Settings** → **Connections** → **OpenAI** → **Manage**
+2. Edit your hermes-agent connection
+3. Change **API Type** from "Chat Completions" to **"Responses (Experimental)"**
+4. Save
+
+With the Responses API, Open WebUI sends requests in the Responses format (`input` array + `instructions`), and Hermes Agent can preserve full tool call history across turns via `previous_response_id`. When `stream: true`, Hermes also streams spec-native `function_call` and `function_call_output` items, which enables custom structured tool-call UI in clients that render Responses events.
+
+:::note
+Open WebUI currently manages conversation history client-side even in Responses mode — it sends the full message history in each request rather than using `previous_response_id`. The main advantage of Responses mode today is the structured event stream: text deltas, `function_call`, and `function_call_output` items arrive as OpenAI Responses SSE events instead of Chat Completions chunks.
+:::
+
+## How It Works
+
+When you send a message in Open WebUI:
+
+1. Open WebUI sends a `POST /v1/chat/completions` request with your message and conversation history
+2. Hermes Agent creates a server-side `AIAgent` instance using the API server's profile, model/provider config, memory, skills, and configured API-server toolsets
+3. The agent processes your request — it may call tools (terminal, file operations, web search, etc.) on the API-server host
+4. As tools execute, **inline progress messages stream to the UI** so you can see what the agent is doing (e.g. `` `💻 ls -la` ``, `` `🔍 Python 3.12 release` ``)
+5. The agent's final text response streams back to Open WebUI
+6. Open WebUI displays the response in its chat interface
+
+Your agent has access to the same tools and capabilities as that API-server Hermes instance. If the API server is remote, those tools are remote too.
+
+If you need tools to run against your **local** workspace today, run Hermes locally and point it at a pure LLM provider or pure OpenAI-compatible model proxy (for example vLLM, LiteLLM, Ollama, llama.cpp, OpenAI, OpenRouter, etc.). A future split-runtime mode for "remote brain, local hands" is being tracked in [#18715](https://github.com/NousResearch/hermes-agent/issues/18715); it is not the behavior of the current API server.
+
+:::tip Tool Progress
+With streaming enabled (the default), you'll see brief inline indicators as tools run — the tool emoji and its key argument. These appear in the response stream before the agent's final answer, giving you visibility into what's happening behind the scenes.
+:::
+
+## Configuration Reference
+
+### Hermes Agent (API server)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `API_SERVER_ENABLED` | `false` | Enable the API server |
+| `API_SERVER_PORT` | `8642` | HTTP server port |
+| `API_SERVER_HOST` | `127.0.0.1` | Bind address |
+| `API_SERVER_KEY` | _(required)_ | Bearer token for auth. Match `OPENAI_API_KEY`. |
+
+### Open WebUI
+
+| Variable | Description |
+|----------|-------------|
+| `OPENAI_API_BASE_URL` | Hermes Agent's API URL (include `/v1`) |
+| `OPENAI_API_KEY` | Must be non-empty. Match your `API_SERVER_KEY`. |
+
+## Troubleshooting
+
+### No models appear in the dropdown
+
+- **Check the URL has `/v1` suffix**: `http://host.docker.internal:8642/v1` (not just `:8642`)
+- **Verify the gateway is running**: `curl http://localhost:8642/health` should return `{"status": "ok"}`
+- **Check model listing**: `curl -H "Authorization: Bearer your-secret-key" http://localhost:8642/v1/models` should return a list with `hermes-agent`
+- **Docker networking**: From inside Docker, `localhost` means the container, not your host. Use `host.docker.internal` or `--network=host`.
+- **Empty Ollama backend shadowing the picker**: If you omitted `ENABLE_OLLAMA_API=false`, Open WebUI shows an empty Ollama section above your Hermes models. Restart the container with `-e ENABLE_OLLAMA_API=false` or disable Ollama in **Admin Settings → Connections**.
+
+### Connection test passes but no models load
+
+This is almost always the missing `/v1` suffix. Open WebUI's connection test is a basic connectivity check — it doesn't verify model listing works.
+
+### Response takes a long time
+
+Hermes Agent may be executing multiple tool calls (reading files, running commands, searching the web) before producing its final response. This is normal for complex queries. The response appears all at once when the agent finishes.
+
+### "Invalid API key" errors
+
+Make sure your `OPENAI_API_KEY` in Open WebUI matches the `API_SERVER_KEY` in Hermes Agent.
+
+:::warning
+Open WebUI persists OpenAI-compatible connection settings in its own database after first launch. If you accidentally saved a wrong key in the Admin UI, fixing the environment variables alone is not enough — update or delete the saved connection in **Admin Settings → Connections**, or reset the Open WebUI data directory / database.
+:::
+
+## Multi-User Setup with Profiles
+
+To run separate Hermes instances per user — each with their own config, memory, and skills — use [profiles](/user-guide/profiles). Each profile runs its own API server on a different port and automatically advertises the profile name as the model in Open WebUI.
+
+### 1. Create profiles and configure API servers
+
+`API_SERVER_*` are env vars, not YAML config keys, so write them to each profile's `.env`. Pick ports outside the default-platform range (`8644` is the webhook adapter, `8645` is wecom-callback, `8646` is msgraph-webhook), e.g. `8650+`:
+
+```bash
+hermes profile create alice
+cat >> ~/.hermes/profiles/alice/.env <<EOF
+API_SERVER_ENABLED=true
+API_SERVER_PORT=8650
+API_SERVER_KEY=alice-secret
+EOF
+
+hermes profile create bob
+cat >> ~/.hermes/profiles/bob/.env <<EOF
+API_SERVER_ENABLED=true
+API_SERVER_PORT=8651
+API_SERVER_KEY=bob-secret
+EOF
+```
+
+### 2. Start each gateway
+
+```bash
+hermes -p alice gateway &
+hermes -p bob gateway &
+```
+
+### 3. Add connections in Open WebUI
+
+In **Admin Settings** → **Connections** → **OpenAI API** → **Manage**, add one connection per profile:
+
+| Connection | URL | API Key |
+|-----------|-----|---------|
+| Alice | `http://host.docker.internal:8650/v1` | `alice-secret` |
+| Bob | `http://host.docker.internal:8651/v1` | `bob-secret` |
+
+The model dropdown will show `alice` and `bob` as distinct models. You can assign models to Open WebUI users via the admin panel, giving each user their own isolated Hermes agent.
+
+:::tip Custom Model Names
+The model name defaults to the profile name. To override it, set `API_SERVER_MODEL_NAME` in the profile's `.env`:
+```bash
+hermes -p alice config set API_SERVER_MODEL_NAME "Alice's Agent"
+```
+:::
+
+## Linux Docker (no Docker Desktop)
+
+On Linux without Docker Desktop, `host.docker.internal` doesn't resolve by default. Options:
+
+```bash
+# Option 1: Add host mapping
+docker run --add-host=host.docker.internal:host-gateway ...
+
+# Option 2: Use host networking
+docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...
+
+# Option 3: Use Docker bridge IP
+docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...
+```

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/photon.md

@@ -0,0 +1,255 @@
+---
+sidebar_position: 18
+---
+
+# Photon iMessage
+
+Connect Hermes to **iMessage** through [Photon][photon], a managed
+service that handles the Apple line allocation and abuse-prevention
+layer so you don't have to run your own Mac relay.
+
+The free tier uses Photon's shared iMessage line pool — different
+recipients may see different sending numbers, but each conversation
+stays stable. The paid Business tier gives every user the same
+dedicated number; the plugin supports both, and the free tier is the
+recommended starting point.
+
+:::info Free to start
+Photon's shared-line pool is free. No subscription is required to send
+your first iMessage from Hermes — just a phone number we can bind to
+your account.
+:::
+
+## Architecture
+
+Photon is a **persistent-connection** channel, like Discord or Slack —
+**no webhook, no public URL, no signing secret to manage.**
+
+The `spectrum-ts` SDK holds a long-lived **gRPC stream** to Photon for
+both directions. Because the SDK is TypeScript-only, Hermes runs it in a
+small supervised **Node sidecar** and talks to it over loopback:
+
+- **Inbound** — the sidecar consumes the SDK's `app.messages` gRPC
+  stream and forwards each message to the Python adapter over a loopback
+  `GET /inbound` (NDJSON). The adapter dedupes and dispatches it to the
+  agent, reconnecting automatically if the stream drops.
+- **Outbound** — replies are loopback POSTs to the sidecar, which calls
+  `space.send(...)` on the SDK.
+
+The Python plugin starts, supervises, and shuts down the sidecar
+automatically.
+
+## Prerequisites
+
+- A Photon account — sign up at [app.photon.codes][app]
+- **Node.js 18.17 or newer** on PATH (`node --version`)
+- A phone number that can receive iMessage (used to bind your account)
+
+That's it — there is no public URL or tunnel to set up.
+
+## First-time setup
+
+Either run the unified gateway wizard and pick **Photon iMessage**:
+
+```bash
+hermes gateway setup
+```
+
+…or run the Photon setup directly (the wizard calls the same flow):
+
+```bash
+# Device-code login + project + user + sidecar deps, all in one
+hermes photon setup --phone +15551234567
+```
+
+The setup, in order:
+
+1. **Device login** (`client_id=photon-cli`) — opens
+   `https://app.photon.codes/` for approval and stores the bearer token.
+2. **Finds or creates** the `Hermes Agent` project on your account.
+3. **Enables Spectrum**, reads the project's Spectrum id, and rotates
+   the project secret.
+4. **Registers your phone number** as a Spectrum user — skipped if a
+   user with that number already exists, so re-running is safe.
+5. **Prints your assigned iMessage line** — the number you text to reach
+   your agent.
+6. **Runs `npm install`** inside the plugin's sidecar directory. On
+   read-only / immutable install trees (hosted Docker images, Podman,
+   Nix) the sidecar automatically falls back to a writable mirror under
+   `~/.hermes/photon/sidecar`; set `PHOTON_SIDECAR_DIR` to pin an
+   explicit location.
+
+Runtime credentials are written to `~/.hermes/.env`
+(`PHOTON_PROJECT_ID` = the Spectrum project id, `PHOTON_PROJECT_SECRET`),
+the same place every other channel keeps its token. Management metadata
+(device token, dashboard project id) lives in `~/.hermes/auth.json` under
+`credential_pool.photon` / `credential_pool.photon_project`.
+
+## Authorizing users
+
+Photon uses the same authorization model as every other Hermes
+channel. Choose one approach:
+
+**DM pairing (default).** When an unknown number messages your Photon
+line, Hermes replies with a pairing code. Approve it with:
+
+```bash
+hermes pairing approve photon <CODE>
+```
+
+Use `hermes pairing list` to see pending codes and approved users.
+
+**Pre-authorize specific numbers** (in `~/.hermes/.env`):
+
+```bash
+PHOTON_ALLOWED_USERS=+15551234567,+15559876543
+```
+
+**Open access** (dev only, in `~/.hermes/.env`):
+
+```bash
+PHOTON_ALLOW_ALL_USERS=true
+```
+
+When `PHOTON_ALLOWED_USERS` is set, unknown senders are silently
+ignored rather than offered a pairing code (the allowlist signals you
+deliberately restricted access).
+
+### Require mentions in group chats
+
+By default Hermes responds to every authorized DM and group message.
+To make group chats opt-in, enable mention gating (DMs still always
+work):
+
+```yaml
+gateway:
+  platforms:
+    photon:
+      enabled: true
+      require_mention: true
+```
+
+With `require_mention: true`, group-chat messages are ignored unless
+they match a wake-word pattern. The defaults match `Hermes` and
+`@Hermes agent` variants. For a custom agent name, set regex patterns:
+
+```yaml
+gateway:
+  platforms:
+    photon:
+      require_mention: true
+      mention_patterns:
+        - '(?<![\w@])@?amos\b[,:\-]?'
+```
+
+Both keys also accept env vars (`PHOTON_REQUIRE_MENTION`,
+`PHOTON_MENTION_PATTERNS`). This is the same mention-gating model the
+BlueBubbles iMessage channel uses.
+
+## Start the gateway
+
+```bash
+hermes gateway start
+```
+
+You'll see something like:
+
+```
+[photon] connected — sidecar on 127.0.0.1:8789, streaming inbound over gRPC
+```
+
+Send an iMessage to your assigned number and Hermes will reply.
+
+## Status & troubleshooting
+
+```bash
+hermes photon status
+```
+
+Prints saved credentials, sidecar health, your registered number, and the
+assigned iMessage line Hermes uses. When a Photon token and dashboard project
+are available, `status` refreshes missing number rows from the dashboard
+without provisioning new lines.
+
+```
+Photon iMessage status
+──────────────────────
+  device token        : ✓ stored
+  dashboard project   : 3c90c3cc-0d44-4b50-...
+  spectrum project id : sp-...
+  project secret      : ✓ stored
+  my number           : +15551234567
+  assigned number     : +16282679185
+  node binary         : /usr/bin/node
+  sidecar deps        : ✓ installed
+```
+
+Common issues:
+
+- **`sidecar deps : ✗ run hermes photon install-sidecar`** — Node is
+  installed but `spectrum-ts` isn't. Run the suggested command.
+- **`device token : ✗ missing`** — run `hermes photon setup` to log in.
+- **`No iMessage line assigned yet`** — Spectrum is enabled but no line
+  has been provisioned; re-run `hermes photon setup` or check the
+  [dashboard][app].
+- **Sidecar won't start** — confirm `node --version` is 18.17+ and that
+  `hermes photon install-sidecar` completed without errors.
+
+## Limits today
+
+- **Inbound attachments are metadata-only.** Inbound events carry the
+  filename + MIME type; the agent sees a marker but can't yet read the
+  bytes. The SDK exposes attachment bytes via `content.read()`, so this
+  is a sidecar follow-up.
+- **Outbound attachments are supported.** Hermes sends images, voice
+  notes, video, and documents through spectrum-ts' `attachment()` /
+  `voice()` content builders via the sidecar's `/send-attachment`
+  endpoint. Captions arrive as a separate iMessage bubble after the
+  media.
+- **Native polls are supported.** Hermes sends poll content through
+  spectrum-ts' `poll()` builder via the sidecar's `/send-poll` endpoint.
+- **Read receipts are supported.** The sidecar marks an inbound iMessage
+  read after forwarding it to Hermes, so the sender sees `Read` without
+  waiting for a model/tool turn. Inbound receipts for Hermes-sent messages
+  are consumed as presence telemetry and never create an agent turn. Set
+  `PHOTON_READ_RECEIPTS=false` to keep messages at `Delivered`.
+- **Message effects are supported.** Hermes sends text with native iMessage
+  bubble/screen effects through spectrum-ts' iMessage `effect()` builder
+  via the sidecar's `/send-effect` endpoint.
+- **Photon's free quotas:** 5,000 messages per server per day,
+  50 new-conversation initiations per shared line per day. Increases
+  available — email `help@photon.codes`.
+- **Cron and standalone sends need the gateway running.** Out-of-process
+  senders (cron jobs, `hermes send`, the dashboard) reuse the sidecar the
+  gateway spawned — they read its port/token from
+  `<hermes-home>/runtime/photon-sidecar.json`, written once the sidecar
+  passes its health check and removed when it stops. If a standalone send
+  reports the gateway appears to be down, start (or restart) the gateway
+  first.
+- **Shared/free-tier lines can't initiate conversations with new
+  targets.** Photon-side policy: a shared line can only message a number
+  after that number has texted the line first. A cron/standalone send to a
+  brand-new recipient will be rejected by Photon even when Hermes is set
+  up correctly — either have the recipient message the line once, or move
+  to a dedicated line.
+
+## Env vars
+
+| Variable                  | Default            | Notes                                      |
+|---------------------------|--------------------|--------------------------------------------|
+| `PHOTON_PROJECT_ID`       | from `.env`        | Spectrum project id (the SDK's `projectId`); set by setup |
+| `PHOTON_PROJECT_SECRET`   | from `.env`        | Project secret; set by setup               |
+| `PHOTON_SIDECAR_PORT`     | `8789`             | Loopback port for the sidecar control + inbound channel |
+| `PHOTON_SIDECAR_AUTOSTART`| `true`             | Whether the adapter spawns the sidecar     |
+| `PHOTON_NODE_BIN`         | `which node`       | Override the Node binary path              |
+| `PHOTON_HOME_CHANNEL`     | (unset)            | Default space id for cron / notifications  |
+| `PHOTON_HOME_CHANNEL_NAME`| (unset)            | Human label for the home channel           |
+| `PHOTON_ALLOWED_USERS`    | (unset)            | Comma-separated E.164 allowlist            |
+| `PHOTON_ALLOW_ALL_USERS`  | `false`            | Dev only — accept any sender               |
+| `PHOTON_REQUIRE_MENTION`  | `false`            | Require a wake word before responding in groups |
+| `PHOTON_MENTION_PATTERNS` | Hermes wake words  | JSON list / comma / newline regex patterns for group mentions |
+| `PHOTON_DASHBOARD_HOST`   | `app.photon.codes` | Override the dashboard / device-login host |
+| `PHOTON_SPECTRUM_HOST`    | `spectrum.photon.codes` | Override the Spectrum API host |
+
+[photon]: https://photon.codes/
+[app]: https://app.photon.codes/

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/qqbot.md

@@ -0,0 +1,123 @@
+# QQ Bot
+
+Connect Hermes to QQ via the **Official QQ Bot API (v2)** — supporting private (C2C), group @-mentions, guild, and direct messages with voice transcription.
+
+## Overview
+
+The QQ Bot adapter uses the [Official QQ Bot API](https://bot.q.qq.com/wiki/develop/api-v2/) to:
+
+- Receive messages via a persistent **WebSocket** connection to the QQ Gateway
+- Send text and markdown replies via the **REST API**
+- Download and process images, voice messages, and file attachments
+- Transcribe voice messages using Tencent's built-in ASR or a configurable STT provider
+
+## Prerequisites
+
+1. **QQ Bot Application** — Register at [q.qq.com](https://q.qq.com):
+   - Create a new application and note your **App ID** and **App Secret**
+   - Enable the required intents: C2C messages, Group @-messages, Guild messages
+   - Configure your bot in sandbox mode for testing, or publish for production
+
+2. **Dependencies** — The adapter requires `aiohttp` and `httpx`:
+   ```bash
+   pip install aiohttp httpx
+   ```
+
+## Configuration
+
+### Interactive setup
+
+```bash
+hermes gateway setup
+```
+
+Select **QQ Bot** from the platform list and follow the prompts.
+
+### Manual configuration
+
+Set the required environment variables in `~/.hermes/.env`:
+
+```bash
+QQ_APP_ID=your-app-id
+QQ_CLIENT_SECRET=your-app-secret
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `QQ_APP_ID` | QQ Bot App ID (required) | — |
+| `QQ_CLIENT_SECRET` | QQ Bot App Secret (required) | — |
+| `QQBOT_HOME_CHANNEL` | OpenID for cron/notification delivery | — |
+| `QQBOT_HOME_CHANNEL_NAME` | Display name for home channel | `Home` |
+| `QQ_ALLOWED_USERS` | Comma-separated user OpenIDs for DM access | open (all users) |
+| `QQ_GROUP_ALLOWED_USERS` | Comma-separated group OpenIDs for group access | — |
+| `QQ_ALLOW_ALL_USERS` | Set to `true` to allow all DMs | `false` |
+| `QQ_PORTAL_HOST` | Override the QQ portal host (set to `sandbox.q.qq.com` for sandbox routing) | `q.qq.com` |
+| `QQ_STT_API_KEY` | API key for voice-to-text provider | — |
+| `QQ_STT_BASE_URL` | (Not read directly — set `platforms.qqbot.extra.stt.baseUrl` in `config.yaml` instead) | n/a |
+| `QQ_STT_MODEL` | STT model name | `glm-asr` |
+
+## Advanced Configuration
+
+For fine-grained control, add platform settings to `~/.hermes/config.yaml`:
+
+```yaml
+platforms:
+  qqbot:
+    enabled: true
+    extra:
+      app_id: "your-app-id"
+      client_secret: "your-secret"
+      markdown_support: true       # enable QQ markdown (msg_type 2). Config-only; no env-var equivalent.
+      dm_policy: "open"          # open | allowlist | disabled
+      allow_from:
+        - "user_openid_1"
+      group_policy: "open"       # open | allowlist | disabled
+      group_allow_from:
+        - "group_openid_1"
+      stt:
+        provider: "zai"          # zai (GLM-ASR), openai (Whisper), etc.
+        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
+        apiKey: "your-stt-key"
+        model: "glm-asr"
+```
+
+## Voice Messages (STT)
+
+Voice transcription works in two stages:
+
+1. **QQ built-in ASR** (free, always tried first) — QQ provides `asr_refer_text` in voice message attachments, which uses Tencent's own speech recognition
+2. **Configured STT provider** (fallback) — If QQ's ASR doesn't return text, the adapter calls an OpenAI-compatible STT API:
+
+   - **Zhipu/GLM (zai)**: Default provider, uses `glm-asr` model
+   - **OpenAI Whisper**: Set `QQ_STT_BASE_URL` and `QQ_STT_MODEL`
+   - Any OpenAI-compatible STT endpoint
+
+## Troubleshooting
+
+### Bot disconnects immediately (quick disconnect)
+
+This usually means:
+- **Invalid App ID / Secret** — Double-check your credentials at q.qq.com
+- **Missing permissions** — Ensure the bot has the required intents enabled
+- **Sandbox-only bot** — If the bot is in sandbox mode, it can only receive messages from QQ's sandbox test channel
+
+### Voice messages not transcribed
+
+1. Check if QQ's built-in `asr_refer_text` is present in the attachment data
+2. If using a custom STT provider, verify `QQ_STT_API_KEY` is set correctly
+3. Check gateway logs for STT error messages
+
+### Messages not delivered
+
+- Verify the bot's **intents** are enabled at q.qq.com
+- Check `QQ_ALLOWED_USERS` if DM access is restricted
+- For group messages, ensure the bot is **@mentioned** (group policy may require allowlisting)
+- Check `QQBOT_HOME_CHANNEL` for cron/notification delivery
+
+### Connection errors
+
+- Ensure `aiohttp` and `httpx` are installed: `pip install aiohttp httpx`
+- Check network connectivity to `api.sgroup.qq.com` and the WebSocket gateway
+- Review gateway logs for detailed error messages and reconnect behavior