Merge 360c95dca7 into 4583f88626

docs/cli/agent.md

@@ -1,10 +1,10 @@
 ---
-summary: "CLI reference for `moltbot agent` (send one agent turn via the Gateway)"
+summary: "CLI reference for `clawdbot agent` (send one agent turn via the Gateway)"
 read_when:
   - You want to run one agent turn from scripts (optionally deliver reply)
 ---
 
-# `moltbot agent`
+# `clawdbot agent`
 
 Run an agent turn via the Gateway (use `--local` for embedded).
 Use `--agent <id>` to target a configured agent directly.
@@ -12,11 +12,26 @@ Use `--agent <id>` to target a configured agent directly.
 Related:
 - Agent send tool: [Agent send](/tools/agent-send)
 
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--url <url>` | Gateway WebSocket URL (for Docker setups where gateway is on a different host/container) |
+| `--local` | Run embedded agent locally instead of via gateway |
+| `--deliver` | Send the agent's reply back to the channel |
+| `--json` | Output result as JSON |
+| `--timeout <seconds>` | Override agent command timeout |
+
+See `clawdbot agent --help` for the full list of options.
+
 ## Examples
 
 ```bash
-moltbot agent --to +15555550123 --message "status update" --deliver
-moltbot agent --agent ops --message "Summarize logs"
-moltbot agent --session-id 1234 --message "Summarize inbox" --thinking medium
-moltbot agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
+clawdbot agent --to +15555550123 --message "status update" --deliver
+clawdbot agent --agent ops --message "Summarize logs"
+clawdbot agent --session-id 1234 --message "Summarize inbox" --thinking medium
+clawdbot agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
+
+# Docker: connect CLI container to gateway container
+docker compose run --rm clawdbot-cli agent --agent main --message "test" --url ws://clawdbot-gateway:18789
 ```

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

docs/tools/agent-send.md

@@ -1,11 +1,11 @@
 ---
-summary: "Direct `moltbot agent` CLI runs (with optional delivery)"
+summary: "Direct `clawdbot agent` CLI runs (with optional delivery)"
 read_when:
   - Adding or modifying the agent CLI entrypoint
 ---
-# `moltbot agent` (direct agent runs)
+# `clawdbot agent` (direct agent runs)
 
-`moltbot agent` runs a single agent turn without needing an inbound chat message.
+`clawdbot agent` runs a single agent turn without needing an inbound chat message.
 By default it goes **through the Gateway**; add `--local` to force the embedded
 runtime on the current machine.
 
@@ -21,7 +21,7 @@ runtime on the current machine.
 - Output:
   - default: prints reply text (plus `MEDIA:<url>` lines)
   - `--json`: prints structured payload + metadata
-- Optional delivery back to a channel with `--deliver` + `--channel` (target formats match `moltbot message --target`).
+- Optional delivery back to a channel with `--deliver` + `--channel` (target formats match `clawdbot message --target`).
 - Use `--reply-channel`/`--reply-to`/`--reply-account` to override delivery without changing the session.
 
 If the Gateway is unreachable, the CLI **falls back** to the embedded local run.
@@ -29,16 +29,20 @@ If the Gateway is unreachable, the CLI **falls back** to the embedded local run.
 ## Examples
 
 ```bash
-moltbot agent --to +15555550123 --message "status update"
-moltbot agent --agent ops --message "Summarize logs"
-moltbot agent --session-id 1234 --message "Summarize inbox" --thinking medium
-moltbot agent --to +15555550123 --message "Trace logs" --verbose on --json
-moltbot agent --to +15555550123 --message "Summon reply" --deliver
-moltbot agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
+clawdbot agent --to +15555550123 --message "status update"
+clawdbot agent --agent ops --message "Summarize logs"
+clawdbot agent --session-id 1234 --message "Summarize inbox" --thinking medium
+clawdbot agent --to +15555550123 --message "Trace logs" --verbose on --json
+clawdbot agent --to +15555550123 --message "Summon reply" --deliver
+clawdbot agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
+
+# Docker: connect CLI container to gateway container
+docker compose run --rm clawdbot-cli agent --agent main --message "test" --url ws://clawdbot-gateway:18789
 ```
 
 ## Flags
 
+- `--url <url>`: Gateway WebSocket URL (for Docker setups where gateway is on a different host/container)
 - `--local`: run locally (requires model provider API keys in your shell)
 - `--deliver`: send the reply to the chosen channel
 - `--channel`: delivery channel (`whatsapp|telegram|discord|googlechat|slack|signal|imessage`, default: `whatsapp`)

src/cli/program/register.agent.ts

@@ -45,6 +45,7 @@ export function registerAgentCommands(program: Command, args: { agentChannelOpti
       "--timeout <seconds>",
       "Override agent command timeout (seconds, default 600 or config value)",
     )
+    .option("--url <url>", "Gateway WebSocket URL (defaults to gateway.remote.url when configured)")
     .addHelpText(
       "after",
       () =>
@@ -66,6 +67,10 @@ ${formatHelpExamples([
     'moltbot agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"',
     "Send reply to a different channel/target.",
   ],
+  [
+    'docker compose run --rm clawdbot-cli agent --agent main --message "test" --url ws://clawdbot-gateway:18789',
+    "Connect from CLI container to gateway container (Docker).",
+  ],
 ])}
 
 ${theme.muted("Docs:")} ${formatDocsLink("/cli/agent", "docs.molt.bot/cli/agent")}`,

src/commands/agent-via-gateway.test.ts

@@ -123,4 +123,40 @@ describe("agentCliCommand", () => {
       fs.rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  it("passes url option to callGateway", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "clawdbot-agent-cli-"));
+    const store = path.join(dir, "sessions.json");
+    mockConfig(store);
+
+    vi.mocked(callGateway).mockResolvedValue({
+      runId: "idem-1",
+      status: "ok",
+      result: {
+        payloads: [{ text: "hello" }],
+        meta: { stub: true },
+      },
+    });
+
+    try {
+      await agentCliCommand(
+        {
+          message: "hi",
+          to: "+1555",
+          url: "ws://clawdbot-gateway:18789",
+        },
+        runtime,
+      );
+
+      expect(callGateway).toHaveBeenCalledTimes(1);
+      expect(callGateway).toHaveBeenCalledWith(
+        expect.objectContaining({
+          url: "ws://clawdbot-gateway:18789",
+        }),
+      );
+      expect(agentCommand).not.toHaveBeenCalled();
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

src/commands/agent-via-gateway.ts

@@ -50,6 +50,7 @@ export type AgentCliOpts = {
   runId?: string;
   extraSystemPrompt?: string;
   local?: boolean;
+  url?: string;
 };
 
 function parseTimeoutSeconds(opts: { cfg: ReturnType<typeof loadConfig>; timeout?: string }) {
@@ -118,6 +119,7 @@ export async function agentViaGatewayCommand(opts: AgentCliOpts, runtime: Runtim
     },
     async () =>
       await callGateway<GatewayAgentResponse>({
+        url: opts.url,
         method: "agent",
         params: {
           message: body,

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