feat: improve gateway services and auto-reply commands

2026-01-11 02:17:10 +01:00
parent df55d45b6f
commit e0bf86f06c
52 changed files with 888 additions and 213 deletions
--- a/docs/cli/gateway.md
+++ b/docs/cli/gateway.md
@@ -77,7 +77,7 @@ clawdbot gateway health --url ws://127.0.0.1:18789
 - your configured remote gateway (if set), and
 - localhost (loopback) **even if remote is configured**.

-If multiple gateways are reachable, it prints all of them and warns this is an unconventional setup (usually you want only one gateway).
+If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use profiles for redundancy, but most installs still run a single gateway.

 ```bash
 clawdbot gateway status
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -156,7 +156,7 @@ Chat messages support `/...` commands (text and native). See [/tools/slash-comma
 Highlights:
 - `/status` for quick diagnostics.
 - `/config` for persisted config changes.
- `/debug` for runtime-only config overrides (memory, not disk).
+- `/debug` for runtime-only config overrides (memory, not disk; requires `commands.debug: true`).

 ## Setup + onboarding

@@ -448,7 +448,7 @@ Subcommands:
 Notes:
 - `daemon status` probes the Gateway RPC by default using the daemon’s resolved port/config (override with `--url/--token/--password`).
 - `daemon status` supports `--no-probe`, `--deep`, and `--json` for scripting.
- `daemon status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans).
+- `daemon status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans). Profile-named Clawdbot services are treated as first-class and aren't flagged as "extra".
 - `daemon status` prints which config path the CLI uses vs which config the daemon likely uses (service env), plus the resolved probe target URL.
 - `daemon install` defaults to Node runtime; use `--runtime bun` only when WhatsApp is disabled.
 - `daemon install` options: `--port`, `--runtime`, `--token`, `--force`.
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -14,6 +14,7 @@ provider mixes reasoning into normal text.
 ## Runtime debug overrides

 Use `/debug` in chat to set **runtime-only** config overrides (memory, not disk).
+`/debug` is disabled by default; enable with `commands.debug: true`.
 This is handy when you need to toggle obscure settings without editing `clawdbot.json`.

 Examples:
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -614,6 +614,8 @@ Controls how chat commands are enabled across connectors.
  commands: {
    native: false,          // register native commands when supported
    text: true,             // parse slash commands in chat messages
+    config: false,          // allow /config (writes to disk)
+    debug: false,           // allow /debug (runtime-only overrides)
    restart: false,         // allow /restart + gateway restart tool
    useAccessGroups: true   // enforce access-group allowlists/policies for commands
  }
@@ -625,6 +627,8 @@ Notes:
 - `commands.text: false` disables parsing chat messages for commands.
 - `commands.native: true` registers native commands on supported connectors (Discord/Slack/Telegram). Platforms without native commands still rely on text commands.
 - `commands.native: false` skips native registration; Discord/Telegram clear previously registered commands on startup. Slack commands are managed in the Slack app.
+- `commands.config: true` enables `/config` (reads/writes `clawdbot.json`).
+- `commands.debug: true` enables `/debug` (runtime-only overrides).
 - `commands.restart: true` enables `/restart` and the gateway tool restart action.
 - `commands.useAccessGroups: false` allows commands to bypass access-group allowlists/policies.

--- a/docs/gateway/doctor.md
+++ b/docs/gateway/doctor.md
@@ -172,8 +172,9 @@ switch to legacy names if the current image is missing.
 ### 7) Gateway service migrations and cleanup hints
 Doctor detects legacy Clawdis gateway services (launchd/systemd/schtasks) and
 offers to remove them and install the Clawdbot service using the current gateway
-port. It can also scan for extra gateway-like services and print cleanup hints
-to ensure only one gateway runs per machine.
+port. It can also scan for extra gateway-like services and print cleanup hints.
+Profile-named Clawdbot gateway services are considered first-class and are not
+flagged as "extra."

 ### 8) Security warnings
 Doctor emits warnings when a provider is open to DMs without an allowlist, or
--- a/docs/gateway/index.md
+++ b/docs/gateway/index.md
@@ -51,6 +51,16 @@ pnpm gateway:watch

 Supported if you isolate state + config and use unique ports.

+Service names are profile-aware:
+- macOS: `com.clawdbot.<profile>`
+- Linux: `clawdbot-gateway-<profile>.service`
+- Windows: `Clawdbot Gateway (<profile>)`
+
+Install metadata is embedded in the service config:
+- `CLAWDBOT_SERVICE_MARKER=clawdbot`
+- `CLAWDBOT_SERVICE_KIND=gateway`
+- `CLAWDBOT_SERVICE_VERSION=<version>`
+
 ### Dev profile (`--dev`)

 Fast path: run a fully-isolated dev instance (config/state/workspace) without touching your primary setup.
@@ -160,7 +170,8 @@ See also: [Presence](/concepts/presence) for how presence is produced/deduped an
  - StandardOut/Err: file paths or `syslog`
 - On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
 - LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
-  - `clawdbot daemon install` writes `~/Library/LaunchAgents/com.clawdbot.gateway.plist`.
+  - `clawdbot daemon install` writes `~/Library/LaunchAgents/com.clawdbot.gateway.plist`
+    (or `com.clawdbot.<profile>.plist`).
  - `clawdbot doctor` audits the LaunchAgent config and can update it to current defaults.

 ## Daemon management (CLI)
@@ -184,15 +195,18 @@ Notes:
 - `daemon status` prints config path + probe target to avoid “localhost vs LAN bind” confusion and profile mismatches.
 - `daemon status` includes the last gateway error line when the service looks running but the port is closed.
 - `logs` tails the Gateway file log via RPC (no manual `tail`/`grep` needed).
- If other gateway-like services are detected, the CLI warns. We recommend **one gateway per machine**; one gateway can host multiple agents.
+- If other gateway-like services are detected, the CLI warns unless they are Clawdbot profile services.
+  We still recommend **one gateway per machine** unless you need redundant profiles.
  - Cleanup: `clawdbot daemon uninstall` (current service) and `clawdbot doctor` (legacy migrations).
 - `daemon install` is a no-op when already installed; use `clawdbot daemon install --force` to reinstall (profile/env/path changes).

 Bundled mac app:
- Clawdbot.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled `com.clawdbot.gateway`.
+- Clawdbot.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled
+  `com.clawdbot.gateway` (or `com.clawdbot.<profile>`).
 - To stop it cleanly, use `clawdbot daemon stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`).
 - To restart, use `clawdbot daemon restart` (or `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`).
  - `launchctl` only works if the LaunchAgent is installed; otherwise use `clawdbot daemon install` first.
+  - Replace the label with `com.clawdbot.<profile>` when running a named profile.

 ## Supervision (systemd user unit)
 Clawdbot installs a **systemd user service** by default on Linux/WSL2. We
@@ -203,10 +217,10 @@ required, shared supervision).
 `clawdbot daemon install` writes the user unit. `clawdbot doctor` audits the
 unit and can update it to match the current recommended defaults.

-Create `~/.config/systemd/user/clawdbot-gateway.service`:
+Create `~/.config/systemd/user/clawdbot-gateway[-<profile>].service`:
 ```
 [Unit]
-Description=Clawdbot Gateway
+Description=Clawdbot Gateway (profile: <profile>, v<version>)
 After=network-online.target
 Wants=network-online.target

@@ -227,16 +241,16 @@ sudo loginctl enable-linger youruser
 Onboarding runs this on Linux/WSL2 (may prompt for sudo; writes `/var/lib/systemd/linger`).
 Then enable the service:
 ```
-systemctl --user enable --now clawdbot-gateway.service
+systemctl --user enable --now clawdbot-gateway[-<profile>].service
 ```

 **Alternative (system service)** - for always-on or multi-user servers, you can
 install a systemd **system** unit instead of a user unit (no lingering needed).
-Create `/etc/systemd/system/clawdbot-gateway.service` (copy the unit above,
+Create `/etc/systemd/system/clawdbot-gateway[-<profile>].service` (copy the unit above,
 switch `WantedBy=multi-user.target`, set `User=` + `WorkingDirectory=`), then:
 ```
 sudo systemctl daemon-reload
-sudo systemctl enable --now clawdbot-gateway.service
+sudo systemctl enable --now clawdbot-gateway[-<profile>].service
 ```

 ## Windows (WSL2)
@@ -249,7 +263,7 @@ Windows installs should use **WSL2** and follow the Linux systemd section above.
 - Debug: subscribe to `tick` and `presence` events; ensure `status` shows linked/auth age; presence entries show Gateway host and connected clients.

 ## Safety guarantees
- Only one Gateway per host; all sends/agent calls must go through it.
+- Assume one Gateway per host by default; if you run multiple profiles, isolate ports/state and target the right instance.
 - No fallback to direct Baileys connections; if the Gateway is down, sends fail fast.
 - Non-connect first frames or malformed JSON are rejected and the socket is closed.
 - Graceful shutdown: emit `shutdown` event before closing; clients must handle close + reconnect.
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -48,8 +48,8 @@ Doctor/daemon will show runtime state (PID/last exit) and log hints.
 - Preferred: `clawdbot logs --follow`
 - File logs (always): `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or your configured `logging.file`)
 - macOS LaunchAgent (if installed): `$CLAWDBOT_STATE_DIR/logs/gateway.log` and `gateway.err.log`
- Linux systemd (if installed): `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager`
- Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST`
+- Linux systemd (if installed): `journalctl --user -u clawdbot-gateway[-<profile>].service -n 200 --no-pager`
+- Windows: `schtasks /Query /TN "Clawdbot Gateway (<profile>)" /V /FO LIST`

 **Enable more logging:**
 - Bump file log detail (persisted JSONL):
@@ -324,7 +324,7 @@ If the gateway is supervised by launchd, killing the PID will just respawn it. S
 ```bash
 clawdbot daemon status
 clawdbot daemon stop
-# Or: launchctl bootout gui/$UID/com.clawdbot.gateway
+# Or: launchctl bootout gui/$UID/com.clawdbot.gateway (replace with com.clawdbot.<profile> if needed)
 ```

 **Fix 2: Port is busy (find the listener)**
@@ -360,7 +360,7 @@ clawdbot providers login --verbose
 | Log | Location |
 |-----|----------|
 | Gateway file logs (structured) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or `logging.file`) |
-| Gateway service logs (supervisor) | macOS: `$CLAWDBOT_STATE_DIR/logs/gateway.log` + `gateway.err.log` (default: `~/.clawdbot/logs/...`; profiles use `~/.clawdbot-<profile>/logs/...`)<br />Linux: `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager`<br />Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST` |
+| Gateway service logs (supervisor) | macOS: `$CLAWDBOT_STATE_DIR/logs/gateway.log` + `gateway.err.log` (default: `~/.clawdbot/logs/...`; profiles use `~/.clawdbot-<profile>/logs/...`)<br />Linux: `journalctl --user -u clawdbot-gateway[-<profile>].service -n 200 --no-pager`<br />Windows: `schtasks /Query /TN "Clawdbot Gateway (<profile>)" /V /FO LIST` |
 | Session files | `$CLAWDBOT_STATE_DIR/agents/<agentId>/sessions/` |
 | Media cache | `$CLAWDBOT_STATE_DIR/media/` |
 | Credentials | `$CLAWDBOT_STATE_DIR/credentials/` |
--- a/docs/install/updating.md
+++ b/docs/install/updating.md
@@ -124,9 +124,9 @@ clawdbot logs --follow
 ```

 If you’re supervised:
- macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`
- Linux systemd user service: `systemctl --user restart clawdbot-gateway.service`
- Windows (WSL2): `systemctl --user restart clawdbot-gateway.service`
+- macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/com.clawdbot.gateway` (use `com.clawdbot.<profile>` if set)
+- Linux systemd user service: `systemctl --user restart clawdbot-gateway[-<profile>].service`
+- Windows (WSL2): `systemctl --user restart clawdbot-gateway[-<profile>].service`
  - `launchctl`/`systemctl` only work if the service is installed; otherwise run `clawdbot daemon install`.

 Runbook + exact service labels: [Gateway runbook](/gateway)
--- a/docs/platforms/exe-dev.md
+++ b/docs/platforms/exe-dev.md
@@ -164,7 +164,7 @@ Control UI details: [Control UI](/web/control-ui)
 On Linux, Clawdbot uses a systemd **user** service. After `--install-daemon`, verify:

 ```bash
-systemctl --user status clawdbot-gateway.service
+systemctl --user status clawdbot-gateway[-<profile>].service
 ```

 If the service dies after logout, enable lingering:
--- a/docs/platforms/index.md
+++ b/docs/platforms/index.md
@@ -42,5 +42,5 @@ Use one of these (all supported):
 - Repair/migrate: `clawdbot doctor` (offers to install or fix the service)

 The service target depends on OS:
- macOS: LaunchAgent (`com.clawdbot.gateway`)
- Linux/WSL2: systemd user service
+- macOS: LaunchAgent (`com.clawdbot.gateway` or `com.clawdbot.<profile>`)
+- Linux/WSL2: systemd user service (`clawdbot-gateway[-<profile>].service`)
--- a/docs/platforms/linux.md
+++ b/docs/platforms/linux.md
@@ -64,11 +64,11 @@ live in the [Gateway runbook](/gateway).

 Minimal setup:

-Create `~/.config/systemd/user/clawdbot-gateway.service`:
+Create `~/.config/systemd/user/clawdbot-gateway[-<profile>].service`:

 ```
 [Unit]
-Description=Clawdbot Gateway
+Description=Clawdbot Gateway (profile: <profile>, v<version>)
 After=network-online.target
 Wants=network-online.target

@@ -84,5 +84,5 @@ WantedBy=default.target
 Enable it:

 ```
-systemctl --user enable --now clawdbot-gateway.service
+systemctl --user enable --now clawdbot-gateway[-<profile>].service
 ```
--- a/docs/platforms/mac/bundled-gateway.md
+++ b/docs/platforms/mac/bundled-gateway.md
@@ -63,10 +63,10 @@ Version injection:
 ## Launchd (Gateway as LaunchAgent)

 Label:
- `com.clawdbot.gateway`
+- `com.clawdbot.gateway` (or `com.clawdbot.<profile>`)

 Plist location (per-user):
- `~/Library/LaunchAgents/com.clawdbot.gateway.plist`
+- `~/Library/LaunchAgents/com.clawdbot.gateway.plist` (or `.../com.clawdbot.<profile>.plist`)

 Manager:
 - The macOS app owns LaunchAgent install/update for the bundled gateway.
--- a/docs/platforms/mac/child-process.md
+++ b/docs/platforms/mac/child-process.md
@@ -14,7 +14,8 @@ manually in a terminal.

 ## Default behavior (launchd)

- The app installs a per‑user LaunchAgent labeled `com.clawdbot.gateway`.
+- The app installs a per‑user LaunchAgent labeled `com.clawdbot.gateway`
+  (or `com.clawdbot.<profile>` when using `--profile`/`CLAWDBOT_PROFILE`).
 - When Local mode is enabled, the app ensures the LaunchAgent is loaded and
  starts the Gateway if needed.
 - Logs are written to the launchd gateway log path (visible in Debug Settings).
@@ -26,6 +27,8 @@ launchctl kickstart -k gui/$UID/com.clawdbot.gateway
 launchctl bootout gui/$UID/com.clawdbot.gateway
 ```

+Replace the label with `com.clawdbot.<profile>` when running a named profile.
+
 ## Attach‑only (developer mode)

 Attach‑only tells the app to **connect to an existing Gateway** without spawning
--- a/docs/platforms/macos.md
+++ b/docs/platforms/macos.md
@@ -31,13 +31,16 @@ node.

 ## Launchd control

-The app manages a per‑user LaunchAgent labeled `com.clawdbot.gateway`.
+The app manages a per‑user LaunchAgent labeled `com.clawdbot.gateway`
+(or `com.clawdbot.<profile>` when using `--profile`/`CLAWDBOT_PROFILE`).

 ```bash
 launchctl kickstart -k gui/$UID/com.clawdbot.gateway
 launchctl bootout gui/$UID/com.clawdbot.gateway
 ```

+Replace the label with `com.clawdbot.<profile>` when running a named profile.
+
 If the LaunchAgent isn’t installed, enable it from the app or run
 `clawdbot daemon install`.

--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -606,6 +606,8 @@ Yes, but you must isolate:
 - `gateway.port` (unique ports)

 There are convenience CLI flags like `--dev` and `--profile <name>` that shift state dirs and ports.
+When using profiles, service names are suffixed (`com.clawdbot.<profile>`, `clawdbot-gateway-<profile>.service`,
+`Clawdbot Gateway (<profile>)`).

 ## Logging and debugging

@@ -627,8 +629,8 @@ clawdbot logs --follow

 Service/supervisor logs (when the gateway runs via launchd/systemd):
 - macOS: `$CLAWDBOT_STATE_DIR/logs/gateway.log` and `gateway.err.log` (default: `~/.clawdbot/logs/...`; profiles use `~/.clawdbot-<profile>/logs/...`)
- Linux: `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager`
- Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST`
+- Linux: `journalctl --user -u clawdbot-gateway[-<profile>].service -n 200 --no-pager`
+- Windows: `schtasks /Query /TN "Clawdbot Gateway (<profile>)" /V /FO LIST`

 See [Troubleshooting](/gateway/troubleshooting#log-locations) for more.

--- a/docs/tools/slash-commands.md
+++ b/docs/tools/slash-commands.md
@@ -18,6 +18,8 @@ Directives (`/think`, `/verbose`, `/reasoning`, `/elevated`) are parsed even whe
  commands: {
    native: false,
    text: true,
+    config: false,
+    debug: false,
    restart: false,
    useAccessGroups: true
  }
@@ -29,6 +31,8 @@ Directives (`/think`, `/verbose`, `/reasoning`, `/elevated`) are parsed even whe
 - `commands.native` (default `false`) registers native commands on Discord/Slack/Telegram.
  - `false` clears previously registered commands on Discord/Telegram at startup.
  - Slack commands are managed in the Slack app and are not removed automatically.
+- `commands.config` (default `false`) enables `/config` (reads/writes `clawdbot.json`).
+- `commands.debug` (default `false`) enables `/debug` (runtime-only overrides).
 - `commands.useAccessGroups` (default `true`) enforces allowlists/policies for commands.

 ## Command list
@@ -39,8 +43,8 @@ Text + native (when enabled):
 - `/status`
 - `/status` (show current status; includes a short usage line when available)
 - `/usage` (alias: `/status`)
- `/config show|get|set|unset` (persist config to disk, owner-only)
- `/debug show|set|unset|reset` (runtime overrides, owner-only)
+- `/config show|get|set|unset` (persist config to disk, owner-only; requires `commands.config: true`)
+- `/debug show|set|unset|reset` (runtime overrides, owner-only; requires `commands.debug: true`)
 - `/cost on|off` (toggle per-response usage line)
 - `/stop`
 - `/restart`
@@ -67,7 +71,7 @@ Notes:

 ## Debug overrides

-`/debug` lets you set **runtime-only** config overrides (memory, not disk). Owner-only.
+`/debug` lets you set **runtime-only** config overrides (memory, not disk). Owner-only. Disabled by default; enable with `commands.debug: true`.

 Examples:

@@ -85,7 +89,7 @@ Notes:

 ## Config updates

-`/config` writes to your on-disk config (`clawdbot.json`). Owner-only.
+`/config` writes to your on-disk config (`clawdbot.json`). Owner-only. Disabled by default; enable with `commands.config: true`.

 Examples: