clawdbot 2026.1.4 → 2026.1.5

package/dist/infra/dotenv.js

@@ -0,0 +1,15 @@
+import fs from "node:fs";
+import path from "node:path";
+import dotenv from "dotenv";
+import { resolveConfigDir } from "../utils.js";
+export function loadDotEnv(opts) {
+    const quiet = opts?.quiet ?? true;
+    // Load from process CWD first (dotenv default).
+    dotenv.config({ quiet });
+    // Then load global fallback: ~/.clawdbot/.env (or CLAWDBOT_STATE_DIR/.env),
+    // without overriding any env vars already present.
+    const globalEnvPath = path.join(resolveConfigDir(process.env), ".env");
+    if (!fs.existsSync(globalEnvPath))
+        return;
+    dotenv.config({ quiet, path: globalEnvPath, override: false });
+}

package/dist/infra/shell-env.js

@@ -0,0 +1,79 @@
+import { execFileSync } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+function isTruthy(raw) {
+    if (!raw)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+function resolveShell(env) {
+    const shell = env.SHELL?.trim();
+    return shell && shell.length > 0 ? shell : "/bin/sh";
+}
+export function loadShellEnvFallback(opts) {
+    const logger = opts.logger ?? console;
+    const exec = opts.exec ?? execFileSync;
+    if (!opts.enabled)
+        return { ok: true, applied: [], skippedReason: "disabled" };
+    const hasAnyKey = opts.expectedKeys.some((key) => Boolean(opts.env[key]?.trim()));
+    if (hasAnyKey) {
+        return { ok: true, applied: [], skippedReason: "already-has-keys" };
+    }
+    const timeoutMs = typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs)
+        ? Math.max(0, opts.timeoutMs)
+        : DEFAULT_TIMEOUT_MS;
+    const shell = resolveShell(opts.env);
+    let stdout;
+    try {
+        stdout = exec(shell, ["-l", "-c", "env -0"], {
+            encoding: "buffer",
+            timeout: timeoutMs,
+            maxBuffer: DEFAULT_MAX_BUFFER_BYTES,
+            env: opts.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[clawdbot] shell env fallback failed: ${msg}`);
+        return { ok: false, error: msg, applied: [] };
+    }
+    const shellEnv = new Map();
+    const parts = stdout.toString("utf8").split("\0");
+    for (const part of parts) {
+        if (!part)
+            continue;
+        const eq = part.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = part.slice(0, eq);
+        const value = part.slice(eq + 1);
+        if (!key)
+            continue;
+        shellEnv.set(key, value);
+    }
+    const applied = [];
+    for (const key of opts.expectedKeys) {
+        if (opts.env[key]?.trim())
+            continue;
+        const value = shellEnv.get(key);
+        if (!value?.trim())
+            continue;
+        opts.env[key] = value;
+        applied.push(key);
+    }
+    return { ok: true, applied };
+}
+export function shouldEnableShellEnvFallback(env) {
+    return isTruthy(env.CLAWDBOT_LOAD_SHELL_ENV);
+}
+export function resolveShellEnvFallbackTimeoutMs(env) {
+    const raw = env.CLAWDBOT_SHELL_ENV_TIMEOUT_MS?.trim();
+    if (!raw)
+        return DEFAULT_TIMEOUT_MS;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed))
+        return DEFAULT_TIMEOUT_MS;
+    return Math.max(0, parsed);
+}

package/dist/infra/system-events.js

@@ -1,10 +1,14 @@
 // Lightweight in-memory queue for human-readable system events that should be
-// prefixed to the next main-session prompt/heartbeat. We intentionally avoid
-// persistence to keep events ephemeral.
+// prefixed to the next prompt. We intentionally avoid persistence to keep
+// events ephemeral. Events are session-scoped; callers that don't specify a
+// session key default to "main".
+const DEFAULT_SESSION_KEY = "main";
 const MAX_EVENTS = 20;
-const queue = [];
-let lastText = null;
-let lastContextKey = null;
+const queues = new Map();
+function normalizeSessionKey(key) {
+    const trimmed = typeof key === "string" ? key.trim() : "";
+    return trimmed || DEFAULT_SESSION_KEY;
+}
 function normalizeContextKey(key) {
     if (!key)
         return null;
@@ -13,32 +17,55 @@ function normalizeContextKey(key) {
         return null;
     return trimmed.toLowerCase();
 }
-export function isSystemEventContextChanged(contextKey) {
+export function isSystemEventContextChanged(contextKey, sessionKey) {
+    const key = normalizeSessionKey(sessionKey);
+    const existing = queues.get(key);
     const normalized = normalizeContextKey(contextKey);
-    return normalized !== lastContextKey;
+    return normalized !== (existing?.lastContextKey ?? null);
 }
 export function enqueueSystemEvent(text, options) {
+    const key = normalizeSessionKey(options?.sessionKey);
+    const entry = queues.get(key) ??
+        (() => {
+            const created = {
+                queue: [],
+                lastText: null,
+                lastContextKey: null,
+            };
+            queues.set(key, created);
+            return created;
+        })();
     const cleaned = text.trim();
     if (!cleaned)
         return;
-    lastContextKey = normalizeContextKey(options?.contextKey);
-    if (lastText === cleaned)
+    entry.lastContextKey = normalizeContextKey(options?.contextKey);
+    if (entry.lastText === cleaned)
         return; // skip consecutive duplicates
-    lastText = cleaned;
-    queue.push({ text: cleaned, ts: Date.now() });
-    if (queue.length > MAX_EVENTS)
-        queue.shift();
-}
-export function drainSystemEvents() {
-    const out = queue.map((e) => e.text);
-    queue.length = 0;
-    lastText = null;
-    lastContextKey = null;
+    entry.lastText = cleaned;
+    entry.queue.push({ text: cleaned, ts: Date.now() });
+    if (entry.queue.length > MAX_EVENTS)
+        entry.queue.shift();
+}
+export function drainSystemEvents(sessionKey) {
+    const key = normalizeSessionKey(sessionKey);
+    const entry = queues.get(key);
+    if (!entry || entry.queue.length === 0)
+        return [];
+    const out = entry.queue.map((e) => e.text);
+    entry.queue.length = 0;
+    entry.lastText = null;
+    entry.lastContextKey = null;
+    queues.delete(key);
     return out;
 }
-export function peekSystemEvents() {
-    return queue.map((e) => e.text);
+export function peekSystemEvents(sessionKey) {
+    const key = normalizeSessionKey(sessionKey);
+    return queues.get(key)?.queue.map((e) => e.text) ?? [];
+}
+export function hasSystemEvents(sessionKey) {
+    const key = normalizeSessionKey(sessionKey);
+    return (queues.get(key)?.queue.length ?? 0) > 0;
 }
-export function hasSystemEvents() {
-    return queue.length > 0;
+export function resetSystemEventsForTest() {
+    queues.clear();
 }

package/dist/macos/relay.js

@@ -22,9 +22,15 @@ async function main() {
         console.log(BUNDLED_VERSION);
         process.exit(0);
     }
+    if (process.env.CLAWDBOT_SMOKE_QR === "1") {
+        const { renderQrPngBase64 } = await import("../web/qr-image.js");
+        await renderQrPngBase64("clawdbot-smoke");
+        console.log("smoke: qr ok");
+        return;
+    }
     await patchBunLongForProtobuf();
-    const { default: dotenv } = await import("dotenv");
-    dotenv.config({ quiet: true });
+    const { loadDotEnv } = await import("../infra/dotenv.js");
+    loadDotEnv({ quiet: true });
     const { ensureClawdbotCliOnPath } = await import("../infra/path-env.js");
     ensureClawdbotCliOnPath();
     const { enableConsoleCapture } = await import("../logging.js");

package/dist/telegram/bot.js

@@ -3,6 +3,7 @@ import { Buffer } from "node:buffer";
 import { apiThrottler } from "@grammyjs/transformer-throttler";
 import { Bot, InputFile, webhookCallback } from "grammy";
 import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js";
+import { hasControlCommand } from "../auto-reply/command-detection.js";
 import { formatAgentEnvelope } from "../auto-reply/envelope.js";
 import { getReplyFromConfig } from "../auto-reply/reply.js";
 import { loadConfig } from "../config/config.js";
@@ -76,9 +77,28 @@ export function createTelegramBot(opts) {
                 }
             }
             const botUsername = ctx.me?.username?.toLowerCase();
+            const allowFromList = Array.isArray(allowFrom)
+                ? allowFrom.map((entry) => String(entry).trim()).filter(Boolean)
+                : [];
+            const senderId = msg.from?.id ? String(msg.from.id) : "";
+            const senderUsername = msg.from?.username ?? "";
+            const commandAuthorized = allowFromList.length === 0 ||
+                allowFromList.includes("*") ||
+                (senderId && allowFromList.includes(senderId)) ||
+                (senderId && allowFromList.includes(`telegram:${senderId}`)) ||
+                (senderUsername &&
+                    allowFromList.some((entry) => entry.toLowerCase() === senderUsername.toLowerCase() ||
+                        entry.toLowerCase() === `@${senderUsername.toLowerCase()}`));
             const wasMentioned = Boolean(botUsername) && hasBotMention(msg, botUsername);
+            const hasAnyMention = (msg.entities ?? msg.caption_entities ?? []).some((ent) => ent.type === "mention");
+            const shouldBypassMention = isGroup &&
+                resolveGroupRequireMention(chatId) &&
+                !wasMentioned &&
+                !hasAnyMention &&
+                commandAuthorized &&
+                hasControlCommand(msg.text ?? msg.caption ?? "");
             if (isGroup && resolveGroupRequireMention(chatId) && botUsername) {
-                if (!wasMentioned) {
+                if (!wasMentioned && !shouldBypassMention) {
                     logger.info({ chatId, reason: "no-mention" }, "skipping group message");
                     return;
                 }
@@ -109,6 +129,8 @@ export function createTelegramBot(opts) {
                 ChatType: isGroup ? "group" : "direct",
                 GroupSubject: isGroup ? (msg.chat.title ?? undefined) : undefined,
                 SenderName: buildSenderName(msg),
+                SenderId: senderId || undefined,
+                SenderUsername: senderUsername || undefined,
                 Surface: "telegram",
                 MessageSid: String(msg.message_id),
                 ReplyToId: replyTarget?.id,
@@ -119,6 +141,7 @@ export function createTelegramBot(opts) {
                 MediaPath: media?.path,
                 MediaType: media?.contentType,
                 MediaUrl: media?.path,
+                CommandAuthorized: commandAuthorized,
             };
             if (replyTarget && shouldLogVerbose()) {
                 const preview = replyTarget.body.replace(/\s+/g, " ").slice(0, 120);

package/dist/utils.js

@@ -94,6 +94,12 @@ export function resolveUserPath(input) {
     }
     return path.resolve(trimmed);
 }
+export function resolveConfigDir(env = process.env, homedir = os.homedir) {
+    const override = env.CLAWDBOT_STATE_DIR?.trim();
+    if (override)
+        return resolveUserPath(override);
+    return path.join(homedir(), ".clawdbot");
+}
 export function resolveHomeDir() {
     const envHome = process.env.HOME?.trim();
     if (envHome)
@@ -129,5 +135,5 @@ export function shortenHomeInString(input) {
         return input;
     return input.split(home).join("~");
 }
-// Fixed configuration root; legacy ~/.clawdbot is no longer used.
-export const CONFIG_DIR = path.join(os.homedir(), ".clawdbot");
+// Configuration root; can be overridden via CLAWDBOT_STATE_DIR.
+export const CONFIG_DIR = resolveConfigDir();

package/dist/web/auto-reply.js

@@ -1,4 +1,5 @@
 import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js";
+import { hasControlCommand } from "../auto-reply/command-detection.js";
 import { formatAgentEnvelope } from "../auto-reply/envelope.js";
 import { normalizeGroupActivation, parseActivationCommand, } from "../auto-reply/group-activation.js";
 import { HEARTBEAT_PROMPT, stripHeartbeatToken, } from "../auto-reply/heartbeat.js";
@@ -592,32 +593,24 @@ export async function monitorWebProvider(verbose, listenerFactory = monitorWebIn
         const defaultActivation = requireMention === false ? "always" : "mention";
         return (normalizeGroupActivation(entry?.groupActivation) ?? defaultActivation);
     };
-    const resolveOwnerList = (selfE164) => {
+    const resolveCommandAllowFrom = () => {
         const allowFrom = mentionConfig.allowFrom;
-        const raw = Array.isArray(allowFrom) && allowFrom.length > 0
-            ? allowFrom
-            : selfE164
-                ? [selfE164]
-                : [];
+        const raw = Array.isArray(allowFrom) && allowFrom.length > 0 ? allowFrom : [];
         return raw
             .filter((entry) => Boolean(entry && entry !== "*"))
             .map((entry) => normalizeE164(entry))
             .filter((entry) => Boolean(entry));
     };
-    const isOwnerSender = (msg) => {
+    const isCommandAuthorized = (msg) => {
+        const allowFrom = resolveCommandAllowFrom();
+        if (allowFrom.length === 0)
+            return true;
+        if (mentionConfig.allowFrom?.includes("*"))
+            return true;
         const sender = normalizeE164(msg.senderE164 ?? "");
         if (!sender)
             return false;
-        const owners = resolveOwnerList(msg.selfE164 ?? undefined);
-        return owners.includes(sender);
-    };
-    const isStatusCommand = (body) => {
-        const trimmed = body.trim().toLowerCase();
-        if (!trimmed)
-            return false;
-        return (trimmed === "/status" ||
-            trimmed === "status" ||
-            trimmed.startsWith("/status "));
+        return allowFrom.includes(sender);
     };
     const stripMentionsForCommand = (text, selfE164) => {
         let result = text;
@@ -888,6 +881,7 @@ export async function monitorWebProvider(verbose, listenerFactory = monitorWebIn
                 SenderName: msg.senderName,
                 SenderE164: msg.senderE164,
                 WasMentioned: msg.wasMentioned,
+                CommandAuthorized: isCommandAuthorized(msg),
                 Surface: "whatsapp",
             }, {
                 onReplyStart: msg.sendComposing,
@@ -992,10 +986,13 @@ export async function monitorWebProvider(verbose, listenerFactory = monitorWebIn
                     noteGroupMember(conversationId, msg.senderE164, msg.senderName);
                     const commandBody = stripMentionsForCommand(msg.body, msg.selfE164);
                     const activationCommand = parseActivationCommand(commandBody);
-                    const isOwner = isOwnerSender(msg);
-                    const statusCommand = isStatusCommand(commandBody);
-                    const shouldBypassMention = isOwner && (activationCommand.hasCommand || statusCommand);
-                    if (activationCommand.hasCommand && !isOwner) {
+                    const commandAuthorized = isCommandAuthorized(msg);
+                    const statusCommand = hasControlCommand(commandBody);
+                    const hasAnyMention = (msg.mentionedJids?.length ?? 0) > 0;
+                    const shouldBypassMention = commandAuthorized &&
+                        (activationCommand.hasCommand || statusCommand) &&
+                        !hasAnyMention;
+                    if (activationCommand.hasCommand && !commandAuthorized) {
                         logVerbose(`Ignoring /activation from non-owner in group ${conversationId}`);
                         return;
                     }

package/dist/web/inbound.js

@@ -58,7 +58,7 @@ export async function monitorWebInbox(options) {
         }
     };
     const handleMessagesUpsert = async (upsert) => {
-        if (upsert.type !== "notify")
+        if (upsert.type !== "notify" && upsert.type !== "append")
             return;
         for (const msg of upsert.messages ?? []) {
             const id = msg.key?.id ?? undefined;
@@ -129,6 +129,10 @@ export async function monitorWebInbox(options) {
                 // Self-chat mode: never auto-send read receipts (blue ticks) on behalf of the owner.
                 logVerbose(`Self-chat mode: skipping read receipt for ${id}`);
             }
+            // If this is history/offline catch-up, we marked it as read above,
+            // but we skip triggering the auto-reply logic to avoid spamming old context.
+            if (upsert.type === "append")
+                continue;
             let body = extractText(msg.message ?? undefined);
             if (!body) {
                 body = extractMediaPlaceholder(msg.message ?? undefined);

package/dist/web/qr-image.js

@@ -1,8 +1,8 @@
-import { createRequire } from "node:module";
 import { deflateSync } from "node:zlib";
-const require = createRequire(import.meta.url);
-const QRCode = require("qrcode-terminal/vendor/QRCode");
-const QRErrorCorrectLevel = require("qrcode-terminal/vendor/QRCode/QRErrorCorrectLevel");
+import QRCodeModule from "qrcode-terminal/vendor/QRCode";
+import QRErrorCorrectLevelModule from "qrcode-terminal/vendor/QRCode/QRErrorCorrectLevel";
+const QRCode = QRCodeModule;
+const QRErrorCorrectLevel = QRErrorCorrectLevelModule;
 function createQrMatrix(input) {
     const qr = new QRCode(-1, QRErrorCorrectLevel.L);
     qr.addData(input);

package/dist/web/session.js

@@ -1,7 +1,6 @@
 import { randomUUID } from "node:crypto";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { DisconnectReason, fetchLatestBaileysVersion, makeCacheableSignalKeyStore, makeWASocket, useMultiFileAuthState, } from "@whiskeysockets/baileys";
 import qrcode from "qrcode-terminal";
@@ -9,10 +8,10 @@ import { resolveDefaultSessionStorePath } from "../config/sessions.js";
 import { danger, info, success } from "../globals.js";
 import { getChildLogger, toPinoLikeLogger } from "../logging.js";
 import { defaultRuntime } from "../runtime.js";
-import { CONFIG_DIR, ensureDir, jidToE164 } from "../utils.js";
+import { CONFIG_DIR, ensureDir, jidToE164, resolveConfigDir, } from "../utils.js";
 import { VERSION } from "../version.js";
 export function resolveWebAuthDir() {
-    return path.join(os.homedir(), ".clawdbot", "credentials");
+    return path.join(resolveConfigDir(), "credentials");
 }
 function resolveWebCredsPath() {
     return path.join(resolveWebAuthDir(), "creds.json");

package/docs/agent.md

@@ -3,7 +3,6 @@ summary: "Agent runtime (embedded p-mono), workspace contract, and session boots
 read_when:
   - Changing agent runtime, workspace bootstrap, or session behavior
 ---
-<!-- {% raw %} -->
 # Agent Runtime 🤖
 
 CLAWDBOT runs a single embedded agent runtime derived from **p-mono** (internal name: **p**).
@@ -101,4 +100,3 @@ At minimum, set:
 ---
 
 *Next: [Group Chats](./group-messages.md)* 🦞
-<!-- {% endraw %} -->

package/docs/assets/markdown.css

@@ -3,6 +3,10 @@
   line-height: 1.7;
 }
 
+.mdx-content > h1:first-of-type {
+  display: none;
+}
+
 .markdown h1,
 .markdown h2,
 .markdown h3,
@@ -127,4 +131,3 @@
   font-family: var(--font-pixel);
   letter-spacing: 0.06em;
 }
-

package/docs/audio.md

@@ -3,7 +3,6 @@ summary: "How inbound audio/voice notes are downloaded, transcribed, and injecte
 read_when:
   - Changing audio transcription or media handling
 ---
-<!-- {% raw %} -->
 # Audio / Voice Notes — 2025-12-05
 
 ## What works
@@ -47,4 +46,3 @@ Requires `OPENAI_API_KEY` in env and `openai` CLI installed:
 ## Gotchas
 - Ensure your CLI exits 0 and prints plain text; JSON needs to be massaged via `jq -r .text`.
 - Keep timeouts reasonable (`timeoutSeconds`, default 45s) to avoid blocking the reply queue.
-<!-- {% endraw %} -->

package/docs/clawd.md

@@ -4,7 +4,6 @@ read_when:
   - Onboarding a new assistant instance
   - Reviewing safety/permission implications
 ---
-<!-- {% raw %} -->
 # Building a personal assistant with CLAWDBOT (Clawd-style)
 
 CLAWDBOT is a WhatsApp + Telegram + Discord gateway for **Pi** agents. This guide is the “personal assistant” setup: one dedicated WhatsApp number that behaves like your always-on agent.
@@ -196,4 +195,3 @@ Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).
 - Cron + wakeups: [Cron + wakeups](./cron.md)
 - macOS menu bar companion: [Clawdbot macOS app](./clawdbot-mac.md)
 - Security: [Security](./security.md)
-<!-- {% endraw %} -->

package/docs/configuration.md

@@ -3,7 +3,6 @@ summary: "All configuration options for ~/.clawdbot/clawdbot.json with examples"
 read_when:
   - Adding or modifying config fields
 ---
-<!-- {% raw %} -->
 # Configuration 🔧
 
 CLAWDBOT reads an optional **JSON5** config from `~/.clawdbot/clawdbot.json` (comments + trailing commas allowed).
@@ -60,6 +59,36 @@ To prevent the bot from responding to WhatsApp @-mentions in groups (only respon
 
 ## Common options
 
+### Env vars + `.env`
+
+CLAWDBOT reads env vars from the parent process (shell, launchd/systemd, CI, etc.).
+
+Additionally, it loads:
+- `.env` from the current working directory (if present)
+- a global fallback `.env` from `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`)
+
+Neither `.env` file overrides existing env vars.
+
+### `env.shellEnv` (optional)
+
+Opt-in convenience: if enabled and none of the expected keys are set yet, CLAWDBOT runs your login shell and imports only the missing expected keys (never overrides).
+This effectively sources your shell profile.
+
+```json5
+{
+  env: {
+    shellEnv: {
+      enabled: true,
+      timeoutMs: 15000
+    }
+  }
+}
+```
+
+Env var equivalent:
+- `CLAWDBOT_LOAD_SHELL_ENV=1`
+- `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`
+
 ### `identity`
 
 Optional agent identity used for defaults and UX. This is written by the macOS onboarding assistant.
@@ -434,6 +463,17 @@ Controls the embedded agent runtime (model/thinking/verbose/timeouts).
 `imageModel` selects an image-capable model for the `image` tool.
 `imageModelFallbacks` lists ordered fallback image models for the `image` tool.
 
+Clawdbot also ships a few built-in `modelAliases` shorthands (when an `agent` section exists):
+
+- `opus` -> `anthropic/claude-opus-4-5`
+- `sonnet` -> `anthropic/claude-sonnet-4-5`
+- `gpt` -> `openai/gpt-5.2`
+- `gpt-mini` -> `openai/gpt-5-mini`
+- `gemini` -> `google/gemini-3-pro-preview`
+- `gemini-flash` -> `google/gemini-3-flash-preview`
+
+If you configure the same alias name (case-insensitive) yourself, your value wins (defaults never override).
+
 ```json5
 {
   agent: {
@@ -508,6 +548,20 @@ Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
 - `timeoutSec`: auto-kill after this runtime (seconds, default 1800)
 - `cleanupMs`: how long to keep finished sessions in memory (ms, default 1800000)
 
+`agent.tools` configures a global tool allow/deny policy (deny wins).
+This is applied even when the Docker sandbox is **off**.
+
+Example (disable browser/canvas everywhere):
+```json5
+{
+  agent: {
+    tools: {
+      deny: ["browser", "canvas"]
+    }
+  }
+}
+```
+
 `agent.elevated` controls elevated (host) bash access:
 - `enabled`: allow elevated mode (default true)
 - `allowFrom`: per-surface allowlists (empty = disabled)
@@ -962,10 +1016,16 @@ Requires full Gateway restart:
 
 To run multiple gateways on one host, isolate per-instance state + config and use unique ports:
 - `CLAWDBOT_CONFIG_PATH` (per-instance config)
-- `CLAWDBOT_STATE_DIR` (sessions/creds/logs)
+- `CLAWDBOT_STATE_DIR` (sessions/creds)
 - `agent.workspace` (memories)
 - `gateway.port` (unique per instance)
 
+Convenience flags (CLI):
+- `clawdbot --dev …` → uses `~/.clawdbot-dev` + shifts ports from base `19001`
+- `clawdbot --profile <name> …` → uses `~/.clawdbot-<name>` (port via config/env/flags)
+
+See `docs/gateway.md` for the derived port mapping (gateway/bridge/browser/canvas).
+
 Example:
 ```bash
 CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \
@@ -1174,4 +1234,3 @@ Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron + wa
 ---
 
 *Next: [Agent Runtime](./agent.md)* 🦞
-<!-- {% endraw %} -->

package/docs/docs.json

@@ -27,11 +27,19 @@
         "pages": [
           "index",
           "onboarding",
-          "wizard",
           "clawd",
           "faq"
         ]
       },
+      {
+        "group": "Installation",
+        "pages": [
+          "wizard",
+          "nix",
+          "docker",
+          "setup"
+        ]
+      },
       {
         "group": "Core Concepts",
         "pages": [

package/docs/faq.md

@@ -118,6 +118,24 @@ pnpm clawdbot login
 
 **If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/` to your server. The auth is just a JSON file.
 
+### How are env vars loaded?
+
+CLAWDBOT reads env vars from the parent process (shell, launchd/systemd, CI, etc.). It also loads `.env` files:
+- `.env` in the current working directory
+- global fallback: `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`)
+
+Neither `.env` file overrides existing env vars.
+
+Optional convenience: import missing expected keys from your login shell env (sources your shell profile):
+
+```json5
+{
+  env: { shellEnv: { enabled: true, timeoutMs: 15000 } }
+}
+```
+
+Or set `CLAWDBOT_LOAD_SHELL_ENV=1` (timeout: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`).
+
 ### Does enterprise OAuth work?
 
 **Not currently.** Enterprise accounts use SSO which requires a different auth flow that pi-coding-agent doesn't support yet.
@@ -530,23 +548,30 @@ Use `/model` to switch without restarting:
 /model sonnet
 /model haiku
 /model opus
+/model gpt
+/model gpt-mini
+/model gemini
+/model gemini-flash
 ```
 
+Clawdbot ships a few default model shorthands (you can override them in config):
+`opus`, `sonnet`, `gpt`, `gpt-mini`, `gemini`, `gemini-flash`.
+
 **Setup:** Configure allowed models and aliases in `clawdbot.json`:
 
 ```json
 {
   "agent": {
-    "model": "anthropic/claude-opus-4-5-20251022",
+    "model": "anthropic/claude-opus-4-5",
     "allowedModels": [
-      "anthropic/claude-opus-4-5-20251022",
-      "anthropic/claude-sonnet-4-5-20251022",
-      "anthropic/claude-haiku-4-5-20251001"
+      "anthropic/claude-opus-4-5",
+      "anthropic/claude-sonnet-4-5",
+      "anthropic/claude-haiku-4-5"
     ],
     "modelAliases": {
-      "opus": "anthropic/claude-opus-4-5-20251022",
-      "sonnet": "anthropic/claude-sonnet-4-5-20251022",
-      "haiku": "anthropic/claude-haiku-4-5-20251001"
+      "opus": "anthropic/claude-opus-4-5",
+      "sonnet": "anthropic/claude-sonnet-4-5",
+      "haiku": "anthropic/claude-haiku-4-5"
     }
   }
 }