From 360c95dca75e1d4834ff7ea209e8c86e2b06adf9 Mon Sep 17 00:00:00 2001
From: Dan Lewis <dglewi@gmail.com>
Date: Mon, 26 Jan 2026 21:04:25 -0900
Subject: [PATCH] fix(docs): correct docker pairing instructions and update
 error message

Docker networking makes connections appear remote, forcing pairing. The previous docs led users to a broken UI path.

Changes:

- Remove instructions to use non-existent 'Settings -> Token' UI

- Document correct CLI-based pairing workflow for Docker

- Update gateway error message to suggest correct fix
---
 docs/install/docker.md                        | 30 +++++++++++++++++--
 .../server/ws-connection/message-handler.ts   |  2 +-
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/docs/install/docker.md b/docs/install/docker.md
index 8ca80e53b..1688b1fac 100644
--- a/docs/install/docker.md
+++ b/docs/install/docker.md
@@ -11,8 +11,8 @@ Docker is **optional**. Use it only if you want a containerized gateway or to va
 
 ## Is Docker right for me?
 
-- **Yes**: you want an isolated, throwaway gateway environment or to run Moltbot on a host without local installs.
-- **No**: you’re running on your own machine and just want the fastest dev loop. Use the normal install flow instead.
+- **Yes**: you want an isolated gateway environment (for security or reproducibility), or you prefer not to install dependencies on your host.
+- **No**: you trust the software and want the fastest dev loop. Use the normal install flow instead.
 - **Sandboxing note**: agent sandboxing uses Docker too, but it does **not** require the full gateway to run in Docker. See [Sandboxing](/gateway/sandboxing).
 
 This guide covers:
@@ -50,7 +50,18 @@ Optional env vars:
 
 After it finishes:
 - Open `http://127.0.0.1:18789/` in your browser.
-- Paste the token into the Control UI (Settings → token).
+- The dashboard will show **"Pairing Required"** (because Docker containers appear as remote devices).
+- To approve the pairing:
+
+```bash
+# List pending requests (find your browser request)
+docker compose run --rm clawdbot-cli devices list
+
+# Approve it
+docker compose run --rm clawdbot-cli devices approve <request-id>
+```
+
+> **Note:** If you change `.env`, you must run `docker compose up -d` to apply it. `docker compose restart` is not enough.
 
 It writes config/workspace on the host:
 - `~/.clawdbot/`
@@ -187,6 +198,19 @@ docker compose run --rm moltbot-cli channels add --channel discord --token "<tok
 
 Docs: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord)
 
+### Running agent commands
+
+When running `clawdbot agent` from the CLI container, use `--url` to connect to the
+gateway container (the default `127.0.0.1:18789` refers to the CLI container's own
+loopback, not the gateway):
+
+```bash
+docker compose run --rm clawdbot-cli agent --agent main --message "test" --url ws://clawdbot-gateway:18789
+```
+
+Note: The CLI container and gateway container share the same config volume
+(`~/.clawdbot/`), so authentication tokens are available automatically.
+
 ### Health check
 
 ```bash
diff --git a/src/gateway/server/ws-connection/message-handler.ts b/src/gateway/server/ws-connection/message-handler.ts
index d1f6ae511..81ad707c6 100644
--- a/src/gateway/server/ws-connection/message-handler.ts
+++ b/src/gateway/server/ws-connection/message-handler.ts
@@ -83,7 +83,7 @@ function formatGatewayAuthFailureMessage(params: {
   const isCli = isGatewayCliClient(client);
   const isControlUi = client?.id === GATEWAY_CLIENT_IDS.CONTROL_UI;
   const isWebchat = isWebchatClient(client);
-  const uiHint = "open a tokenized dashboard URL or paste token in Control UI settings";
+  const uiHint = "open a tokenized dashboard URL or use 'clawdbot devices approve' to pair";
   const tokenHint = isCli
     ? "set gateway.remote.token to match gateway.auth.token"
     : isControlUi || isWebchat