@foxden-app/foxclaw 0.3.18 → 0.4.0

package/dist/update.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { spawn, spawnSync } from 'node:child_process';
 const PACKAGE_SPEC = '@foxden-app/foxclaw@latest';
+const CODEX_PACKAGE_SPEC = '@openai/codex@latest';
 const UPDATE_STATUS_FILENAME = 'self-update.json';
 export function selfUpdateStatusPath(statusPath) {
     return path.join(path.dirname(statusPath), UPDATE_STATUS_FILENAME);
@@ -33,6 +34,7 @@ export function resolveSelfUpdateInstaller(entryPoint, nodePath = process.execPa
                 command: pnpmCommand,
                 installArgs: ['add', '--global', PACKAGE_SPEC],
                 rootArgs: ['root', '--global'],
+                pnpmHome,
             };
         }
         const npmCommandName = process.platform === 'win32' ? 'npm.cmd' : 'npm';
@@ -43,6 +45,7 @@ export function resolveSelfUpdateInstaller(entryPoint, nodePath = process.execPa
             command: npmCommand,
             installArgs: ['exec', '--yes', '--package=pnpm@latest', '--', 'pnpm', 'add', '--global', PACKAGE_SPEC],
             rootArgs: ['exec', '--yes', '--package=pnpm@latest', '--', 'pnpm', 'root', '--global'],
+            pnpmHome,
         };
     }
     const adjacentNpm = path.join(path.dirname(nodePath), process.platform === 'win32' ? 'npm.cmd' : 'npm');
@@ -53,6 +56,65 @@ export function resolveSelfUpdateInstaller(entryPoint, nodePath = process.execPa
         rootArgs: ['root', '--global'],
     };
 }
+export function resolveCodexUpdateInstaller(codexCliBin, nodePath = process.execPath, exists = fs.existsSync, env = process.env, realpath = fs.realpathSync, readText = (target) => fs.readFileSync(target, 'utf8')) {
+    const resolved = resolveManagedCodexEntryPoint(codexCliBin, realpath, readText);
+    if (!resolved)
+        return null;
+    const normalized = resolved.replace(/\\/g, '/');
+    const pnpmManaged = normalized.includes('/global/') && normalized.includes('/.pnpm/@openai+codex@');
+    const npmManaged = normalized.includes('/lib/node_modules/@openai/codex/')
+        || normalized.includes('/npm/node_modules/@openai/codex/');
+    if (!pnpmManaged && !npmManaged) {
+        return null;
+    }
+    const installer = resolveSelfUpdateInstaller(resolved, nodePath, exists, env);
+    return {
+        ...installer,
+        installArgs: installer.installArgs.map((argument) => (argument === PACKAGE_SPEC ? CODEX_PACKAGE_SPEC : argument)),
+    };
+}
+function resolveManagedCodexEntryPoint(codexCliBin, realpath, readText) {
+    const pending = [codexCliBin];
+    const visited = new Set();
+    while (pending.length > 0 && visited.size < 4) {
+        const candidate = pending.shift();
+        let resolved = candidate;
+        try {
+            resolved = realpath(candidate);
+        }
+        catch {
+            // Wrapper inspection below can still reveal its managed target.
+        }
+        if (visited.has(resolved))
+            continue;
+        visited.add(resolved);
+        const normalized = resolved.replace(/\\/g, '/');
+        if (isManagedCodexPackagePath(normalized)) {
+            return resolved;
+        }
+        let contents = '';
+        try {
+            contents = readText(resolved);
+        }
+        catch {
+            continue;
+        }
+        const embeddedPackageRoot = contents.match(/\/[^\s"']*\/global\/[^\s"']*\/\.pnpm\/@openai\+codex@[^\s"']*\/node_modules\/@openai\/codex/)?.[0];
+        if (embeddedPackageRoot) {
+            return path.join(embeddedPackageRoot, 'bin', 'codex.js');
+        }
+        const wrappedExecutable = contents.match(/\bexec\s+"([^"]*codex[^"]*)"/)?.[1];
+        if (wrappedExecutable) {
+            pending.push(wrappedExecutable);
+        }
+    }
+    return null;
+}
+function isManagedCodexPackagePath(normalized) {
+    return (normalized.includes('/global/') && normalized.includes('/.pnpm/@openai+codex@'))
+        || normalized.includes('/lib/node_modules/@openai/codex/')
+        || normalized.includes('/npm/node_modules/@openai/codex/');
+}
 export function readSelfUpdateStatus(statusFile) {
     try {
         const parsed = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
@@ -69,6 +131,7 @@ export function readSelfUpdateStatus(statusFile) {
             locale: parsed.locale,
             fromVersion: parsed.fromVersion,
             toVersion: typeof parsed.toVersion === 'string' ? parsed.toVersion : null,
+            ...(typeof parsed.codexUpdate === 'string' ? { codexUpdate: parsed.codexUpdate } : {}),
             error: typeof parsed.error === 'string' ? parsed.error : null,
             updatedAt: parsed.updatedAt,
         };
@@ -97,6 +160,7 @@ export function createSelfUpdateRuntime(options) {
                 locale,
                 fromVersion: options.version,
                 toVersion: null,
+                codexUpdate: null,
                 error: null,
                 updatedAt: new Date().toISOString(),
             });
@@ -106,7 +170,7 @@ export function createSelfUpdateRuntime(options) {
                 const child = spawn(options.nodePath, [options.entryPoint, 'update', '--notification-file', statusFile], {
                     detached: true,
                     stdio: ['ignore', logFd, logFd],
-                    env: process.env,
+                    env: options.codexCliBin ? { ...process.env, CODEX_CLI_BIN: options.codexCliBin } : process.env,
                 });
                 child.unref();
             }
@@ -117,6 +181,7 @@ export function createSelfUpdateRuntime(options) {
                     locale,
                     fromVersion: options.version,
                     toVersion: null,
+                    codexUpdate: null,
                     error: formatError(error),
                     updatedAt: new Date().toISOString(),
                 });
@@ -137,7 +202,10 @@ export function createSelfUpdateRuntime(options) {
 export function performSelfUpdate(options) {
     const env = options.env ?? process.env;
     let toVersion = null;
+    let codexUpdate = null;
     try {
+        codexUpdate = updateManagedCodexCli(options.codexCliBin ?? env.CODEX_CLI_BIN ?? '', options.nodePath, env);
+        console.log(`[UPDATE] ${codexUpdate}`);
         const installer = resolveSelfUpdateInstaller(options.entryPoint, options.nodePath, fs.existsSync, env);
         const installerEnv = buildInstallerEnv(options.entryPoint, installer, env);
         console.log(`[UPDATE] Installing ${PACKAGE_SPEC} with ${installer.manager}...`);
@@ -146,7 +214,7 @@ export function performSelfUpdate(options) {
         toVersion = readInstalledPackageVersion(updatedEntryPoint);
         console.log('[UPDATE] Running checks and restarting the FoxClaw service...');
         runInherited(options.nodePath, [updatedEntryPoint, 'start'], installerEnv);
-        completeNotification(options.notificationFile, 'succeeded', toVersion, null);
+        completeNotification(options.notificationFile, 'succeeded', toVersion, codexUpdate, null);
         console.log(`[OK] FoxClaw updated and restarted: ${options.version} -> ${toVersion}`);
         return {
             ok: true,
@@ -157,7 +225,7 @@ export function performSelfUpdate(options) {
     }
     catch (error) {
         const message = formatError(error);
-        completeNotification(options.notificationFile, 'failed', toVersion, message);
+        completeNotification(options.notificationFile, 'failed', toVersion, codexUpdate, message);
         console.error(`[FAIL] FoxClaw update failed: ${message}`);
         return {
             ok: false,
@@ -167,6 +235,23 @@ export function performSelfUpdate(options) {
         };
     }
 }
+function updateManagedCodexCli(codexCliBin, nodePath, env) {
+    if (!codexCliBin) {
+        return 'Codex CLI update skipped: CODEX_CLI_BIN is not configured.';
+    }
+    const installer = resolveCodexUpdateInstaller(codexCliBin, nodePath, fs.existsSync, env);
+    if (!installer) {
+        return 'Codex CLI update skipped: configured installation is not a recognized global npm/pnpm package.';
+    }
+    try {
+        const installerEnv = buildInstallerEnv(fs.realpathSync(codexCliBin), installer, env);
+        runInherited(installer.command, installer.installArgs, installerEnv);
+        return `Codex CLI updated with ${installer.manager}.`;
+    }
+    catch (error) {
+        return `Codex CLI update failed without blocking FoxClaw update: ${formatError(error)}`;
+    }
+}
 function executableCandidates(commandName, nodePath, env, preferred = []) {
     return [
         ...preferred,
@@ -175,7 +260,9 @@ function executableCandidates(commandName, nodePath, env, preferred = []) {
     ].filter((candidate, index, all) => candidate && all.indexOf(candidate) === index);
 }
 function buildInstallerEnv(entryPoint, installer, env) {
-    const pnpmHome = installer.manager === 'pnpm' ? inferPnpmHomeFromEntryPoint(entryPoint) : null;
+    const pnpmHome = installer.manager === 'pnpm'
+        ? installer.pnpmHome ?? inferPnpmHomeFromEntryPoint(entryPoint)
+        : null;
     if (!pnpmHome) {
         return env;
     }
@@ -230,7 +317,7 @@ function readInstalledPackageVersion(updatedEntryPoint) {
         return 'unknown';
     }
 }
-function completeNotification(notificationFile, state, toVersion, error) {
+function completeNotification(notificationFile, state, toVersion, codexUpdate, error) {
     if (!notificationFile) {
         return;
     }
@@ -242,6 +329,7 @@ function completeNotification(notificationFile, state, toVersion, error) {
         ...pending,
         state,
         toVersion,
+        codexUpdate,
         error,
         updatedAt: new Date().toISOString(),
     });

package/docs/agent-assisted-install.md

@@ -8,7 +8,7 @@ This works well with Codex, OpenClaw, QwenPaw, Hermes, OpenCode, Kimi CLI, or an
 
 Prepare these values before asking the agent:
 
-- `TG_BOT_TOKEN`: Telegram bot token from `@BotFather`
+- `TG_BOT_TOKENS`: one or more comma-separated Telegram bot tokens from `@BotFather`
 - `TG_ALLOWED_USER_ID`: your numeric Telegram user id
 - `DEFAULT_CWD`: the folder where Codex should work
 
@@ -17,7 +17,7 @@ Optional later:
 - `TG_ALLOWED_CHAT_ID`
 - `TG_ALLOWED_TOPIC_ID`
 
-Use private Telegram chat first. Configure groups/topics only after private chat works.
+Use private Telegram chat first. Configure groups/topics only after private chat works. Multiple tokens mean independent Codex runtimes inside one service; validate each bot privately.
 
 ## Copy-Paste Prompt
 
@@ -33,7 +33,7 @@ Published package:
 Use private Telegram chat first. Do not configure group/topic mode unless I explicitly provide TG_ALLOWED_CHAT_ID or TG_ALLOWED_TOPIC_ID.
 
 Here are the required values:
-TG_BOT_TOKEN=<paste token here>
+TG_BOT_TOKENS=<paste one token, or comma-separated tokens here>
 TG_ALLOWED_USER_ID=<paste numeric Telegram user id here>
 DEFAULT_CWD=<paste absolute working directory here>
 
@@ -45,17 +45,18 @@ Tasks:
 5. Run foxclaw init, then write ~/.foxclaw/.env. Never print or commit the bot token.
 6. Run foxclaw doctor.
 7. Start FoxClaw with foxclaw start.
-8. Ask me to send /help and /status to the Telegram bot.
+8. Ask me to send /help, /status, and /auth privately to each configured Telegram bot; confirm /auth names that bot runtime.
 9. Verify the final state:
    - foxclaw.service is active/enabled on Linux
    - foxclaw status works
-10. Report the commands used, the final status, and the log command I should use if something stops working. Redact TG_BOT_TOKEN and never print the full token or full .env content.
+10. Report the commands used, the final status, and the log command I should use if something stops working. Redact TG_BOT_TOKENS and never print the full token or full .env content.
+11. If multiple bots are enabled, confirm foxclaw status lists independent app-servers; group-chat tests must mention or reply to the intended bot.
 ```
 
 ## Safety Notes
 
 - Do not paste bot tokens into public issue trackers or public chat logs.
 - Do not commit `.env`.
-- When reporting results, redact `TG_BOT_TOKEN`.
+- When reporting results, redact `TG_BOT_TOKENS` and legacy `TG_BOT_TOKEN`.
 - Do not use `/` or your whole home directory as `DEFAULT_CWD` for a first install.
 - Use `foxclaw start` for normal service startup. Use foreground `foxclaw serve` only when troubleshooting.

package/docs/install-for-beginners.md

@@ -123,7 +123,7 @@ npm install -g @foxden-app/foxclaw
 foxclaw init
 ```
 
-This creates the config file at `~/.foxclaw/.env` and prompts for the Telegram bot token, your numeric Telegram user id, and the default workspace.
+This creates the config file at `~/.foxclaw/.env` and prompts for one or more comma-separated Telegram bot tokens, your numeric Telegram user id, and the default workspace. New installs use `TG_BOT_TOKENS`; legacy `TG_BOT_TOKEN` is only for existing single-bot configurations.
 
 If you prefer pnpm:
 
@@ -143,7 +143,7 @@ nano ~/.foxclaw/.env
 For a first private-chat install, fill only the important values:
 
 ```dotenv
-TG_BOT_TOKEN=123456789:replace_with_your_bot_token
+TG_BOT_TOKENS=123456789:replace_with_your_bot_token
 TG_ALLOWED_USER_ID=123456789
 TG_ALLOWED_CHAT_ID=
 TG_ALLOWED_TOPIC_ID=
@@ -154,6 +154,14 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 Keep `TG_ALLOWED_CHAT_ID=` and `TG_ALLOWED_TOPIC_ID=` empty for the first install. Do not delete those lines; leaving them empty means private-chat mode.
 
+Start with one bot. To add three independent Codex lanes later, put the tokens on the same line:
+
+```dotenv
+TG_BOT_TOKENS=123456789:token_a,234567890:token_b,345678901:token_c
+```
+
+FoxClaw still installs one service, but each bot receives its own app-server, session home, and current auth selection. After startup, privately send `/help` and `/status` to each bot.
+
 `DEFAULT_CWD` must be a real folder. Examples:
 
 ```dotenv
@@ -176,7 +184,7 @@ You want to see:
 ```text
 [OK] node >= 24
 [OK] codex cli available
-[OK] telegram bot token configured
+[OK] telegram bot token(s) configured
 [OK] telegram allowed user configured
 [OK] default cwd exists
 ```
@@ -280,7 +288,7 @@ Update FoxClaw later:
 foxclaw update
 ```
 
-You can also send `/update` in an authorized Telegram chat. When no turn, approval, or question is active, it upgrades, checks, restarts the service, and reports the result after restart.
+You can also send `/update` in an authorized Telegram chat. When every Telegram bot runtime, an enabled Weixin default runtime, and auth mirror writes are idle, it attempts to update an npm/pnpm-managed Codex CLI, upgrades FoxClaw, checks, restarts the service, and reports the result through the bot that started it.
 
 ## Next Step
 

package/docs/troubleshooting.md

@@ -20,7 +20,7 @@ journalctl --user -u foxclaw.service -f
 | --- | --- | --- |
 | `[FAIL] node >= 24` | Your current shell is using an older Node.js. | Install or activate Node.js 24+ by any method, then rerun `foxclaw doctor`. If the service uses old Node, reinstall it from a Node 24+ shell with `foxclaw start`. |
 | `[FAIL] codex cli available` | The `codex` command is not in PATH. | Install Codex CLI or fix PATH, then confirm `codex --version` works. |
-| `[FAIL] telegram bot token configured` | `TG_BOT_TOKEN` is missing from `.env`. | Copy the token from `@BotFather` into `.env`. |
+| `[FAIL] telegram bot token(s) configured` | Neither `TG_BOT_TOKENS` nor legacy `TG_BOT_TOKEN` is present in `.env`. | Put one or more comma-separated `@BotFather` tokens in `TG_BOT_TOKENS`. |
 | `[FAIL] telegram allowed user configured` | `TG_ALLOWED_USER_ID` is missing from `.env`. | Get your numeric id from `@userinfobot` and add it to `.env`. |
 | `[FAIL] default cwd exists` | `DEFAULT_CWD` points to a folder that does not exist. | Create the folder or change `DEFAULT_CWD` to an existing absolute path. |
 
@@ -182,6 +182,18 @@ Bridge logs are stored here:
 tail -f ~/.foxclaw/logs/service.log
 ```
 
+## Checking Multi-Bot Mode
+
+After configuring `TG_BOT_TOKENS`, `foxclaw status` should contain one bot id, connection status, and independent app-server for each token. Send `/status` privately to any bot to see the runtime summary; send `/auth` to confirm the panel names the current `@botname` and its auth directory.
+
+Each isolated app-server log is stored at:
+
+```bash
+tail -f ~/.foxclaw/logs/codex-app-server-bot<id>.log
+```
+
+When multiple bots share a group, unaddressed messages intentionally do not trigger them; mention `@botname`, reply to the intended bot, or send `/status@botname`. When enabled, Weixin stays on the default Codex runtime and does not appear inside an isolated Telegram bot's thread list.
+
 ## ChatGPT Backend 403 Or Unable To Load Site
 
 If Telegram shows `ChatGPT backend 403 Forbidden`, or the app-server log contains `Unable to load site`, `cf-ray`, or `chatgpt.com/backend-api`, the auth file is not necessarily broken. The service process is usually reaching ChatGPT with the wrong network/proxy/IP.

package/docs/user-manual.md

@@ -100,7 +100,7 @@ Both install the same published npm package. Use one global package manager cons
 
 ### 1.6 Fill In The Config
 
-`foxclaw init` creates the default config file at `~/.foxclaw/.env` and prompts for the Telegram bot token, your numeric Telegram user id, and the default workspace. If the current shell has proxy variables such as `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY`, it also asks whether to save them into the FoxClaw config. When `HTTP_PROXY` or `HTTPS_PROXY` is configured, FoxClaw passes it to systemd/launchd explicitly and enables Node's env proxy support. Press Enter on any field to skip it, then edit manually if needed:
+`foxclaw init` creates the default config file at `~/.foxclaw/.env` and prompts for one or more comma-separated Telegram bot tokens, your numeric Telegram user id, and the default workspace. If the current shell has proxy variables such as `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY`, it also asks whether to save them into the FoxClaw config. When `HTTP_PROXY` or `HTTPS_PROXY` is configured, FoxClaw passes it to systemd/launchd explicitly and enables Node's env proxy support. Press Enter on any field to skip it, then edit manually if needed:
 
 ```bash
 $EDITOR ~/.foxclaw/.env
@@ -109,7 +109,7 @@ $EDITOR ~/.foxclaw/.env
 Minimum private-chat config:
 
 ```dotenv
-TG_BOT_TOKEN=123456789:replace_with_your_bot_token
+TG_BOT_TOKENS=123456789:replace_with_your_bot_token
 TG_ALLOWED_USER_ID=123456789
 TG_ALLOWED_CHAT_ID=
 TG_ALLOWED_TOPIC_ID=
@@ -120,7 +120,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 Fields:
 
-- `TG_BOT_TOKEN`: the token from `@BotFather`.
+- `TG_BOT_TOKENS`: one or more `@BotFather` tokens separated by commas. The legacy single-bot `TG_BOT_TOKEN` setting remains compatible.
 - `TG_ALLOWED_USER_ID`: your numeric Telegram user id.
 - `TG_ALLOWED_CHAT_ID`: leave empty for the first private-chat setup.
 - `TG_ALLOWED_TOPIC_ID`: leave empty unless binding a Telegram topic.
@@ -136,7 +136,7 @@ foxclaw start
 foxclaw status
 ```
 
-For later upgrades, run `foxclaw update`. It uses the npm or pnpm installation method currently managing FoxClaw, upgrades globally, runs checks, and restarts the background service.
+For later upgrades, run `foxclaw update`. It uses the npm or pnpm installation method currently managing FoxClaw, attempts to update a globally npm/pnpm-managed Codex CLI, runs checks, and restarts the background service.
 
 Linux service logs:
 
@@ -230,10 +230,10 @@ Later commands are sorted by recent usage. Plain text, photos, and files continu
 
 ### 3.2 `/status`, `/account`, `/quota`, `/update`
 
-- `/status`: FoxClaw, app-server, current thread binding, model, access, and Codex usage summary. Local session, token, and visible-reply-throughput metrics use a background-generated historical snapshot instead of scanning large logs during the request; throughput is computed end-to-end for completed turns, excluding reasoning tokens while including waiting and tool execution time.
+- `/status`: FoxClaw, app-server, current thread binding, model, access, and Codex usage summary. In multi-bot mode it also lists every bot's connection, current auth, active turns, and the most recent auth mirror and service/Codex update outcomes. Local session, token, and visible-reply-throughput metrics use a background-generated historical snapshot instead of scanning large logs during the request; throughput is computed end-to-end for completed turns, excluding reasoning tokens while including waiting and tool execution time.
 - `/account`: current Codex account.
 - `/quota`: Codex usage and quota window.
-- `/update`: upgrade FoxClaw, run checks, and restart the service; it refuses while a turn, approval, or question is active, then reports the result after restart.
+- `/update`: upgrade FoxClaw, attempt to update an npm/pnpm-managed Codex CLI, run checks, and restart the service; it refuses while any Telegram bot runtime, an enabled Weixin default runtime, or an auth mirror write is busy, then reports the result through the initiating bot after restart.
 
 ### 3.3 `/config`, `/requirements`, `/provider`
 
@@ -335,11 +335,11 @@ Watch mode mirrors live turn progress and approval requests. The watching chat i
 
 ## 6. Codex Login And Auth Rotation
 
-This is a key FoxClaw feature. Codex auth is usually stored at `~/.codex/auth.json`. FoxClaw stores multiple accounts as candidate files and switches which candidate the active `auth.json` points to.
+This is a key FoxClaw feature. Codex auth is usually stored at `~/.codex/auth.json`. FoxClaw stores multiple accounts as candidate files and switches which candidate the active `auth.json` points to. In `TG_BOT_TOKENS` mode, each bot has an isolated Codex home, app-server, and current candidate, so bots can run and switch accounts independently; isolated Telegram runtimes force file-backed credential storage. Validated login/refresh credentials are safely mirrored between bot homes, but sessions are never shared.
 
 ### 6.1 File Format
 
-Candidate files live in the Codex auth directory, usually `~/.codex/`. If `CODEX_AUTH_DIR` is set, FoxClaw uses that directory.
+In single-bot compatibility mode, candidate files live in the Codex auth directory, usually `~/.codex/`. If `CODEX_AUTH_DIR` is set, FoxClaw uses that directory. Multi-bot mode treats that directory as its candidate source and stores isolated bot copies under `~/.foxclaw/codex/telegram/bot<id>/home/`.
 
 Recommended layout:
 
@@ -357,7 +357,7 @@ FoxClaw recognizes candidate names in these forms:
 - `auth.json.<name>`
 - `auth.json-<name>`
 
-`auth.json` is what Codex currently uses. When switching accounts, FoxClaw points `auth.json` at one candidate. Candidate contents are Codex-generated JSON; FoxClaw treats those private fields as opaque and you should not hand-write them.
+`auth.json` is what Codex currently uses. When switching accounts, FoxClaw points `auth.json` at one candidate. Candidate contents are Codex-generated JSON and should not be hand-written. In multi-bot mode, FoxClaw mirrors a candidate only when its account identity matches and its refresh timestamp is newer, preventing a same-name candidate from overwriting a different account.
 
 If you already have a working `auth.json`, you can save it as a candidate:
 
@@ -387,7 +387,7 @@ If the login is cancelled or fails, FoxClaw tries to restore the previous auth t
 
 ### 6.3 The `/auth` Panel
 
-`/auth` lists candidate accounts, the current account, and the auth directory. It also provides buttons for switching, disabling, login, and reload. The `5h|7d` numbers before each filename are the last recorded remaining percentages for the two quota windows; the current auth is refreshed when the panel opens, while other candidates are not switched merely to query quota.
+`/auth` lists candidate accounts, the current account, and the auth directory. It also provides buttons for switching, disabling, login, and reload. In multi-bot mode the panel names the `@botname` runtime being managed, because private chats, groups, and topics on one bot share that bot's current auth. The `5h|7d` numbers before each filename are the last recorded remaining percentages for the two quota windows; the current auth is refreshed when the panel opens, while other candidates are not switched merely to query quota.
 
 Approximation:
 
@@ -416,7 +416,7 @@ Equivalent commands:
 - `/auth disable <n>`: skip candidate n during auto-rotation.
 - `/auth reload` or `/auth_reload`: restart app-server and reload the current `auth.json`.
 
-If active turns, pending approvals, pending user inputs, or MCP elicitations exist, FoxClaw refuses manual auth switching to avoid changing accounts mid-request.
+If the requesting bot runtime has active turns, pending approvals, pending user inputs, or MCP elicitations, FoxClaw refuses manual auth switching to avoid changing accounts mid-request; another idle bot is unaffected.
 
 ### 6.4 How Auto-Rotation Works
 
@@ -452,7 +452,7 @@ auth.json_backup       # backup account, enable or disable as needed
 
 ## 8. Safety
 
-- Do not share `TG_BOT_TOKEN`, `~/.codex/auth.json*`, or `.env`.
+- Do not share `TG_BOT_TOKENS`, `TG_BOT_TOKEN`, `~/.codex/auth.json*`, or `.env`.
 - Do not use `/`, `/home`, `/Users`, or your whole home directory as the first `DEFAULT_CWD`.
 - When unsure, use `/permissions read-only` or select `Read-only` in `/setup`.
 - Group mode still only accepts `TG_ALLOWED_USER_ID`, but use trusted groups.

package/docs/zh/agent-assisted-install.md

@@ -8,7 +8,7 @@
 
 先准备这几个值：
 
-- `TG_BOT_TOKEN`：从 `@BotFather` 拿到的 Telegram bot token
+- `TG_BOT_TOKENS`：从 `@BotFather` 拿到的一个或多个 Telegram bot token，多项用逗号分隔
 - `TG_ALLOWED_USER_ID`：你的 Telegram 数字用户 ID
 - `DEFAULT_CWD`：希望 Codex 默认工作的目录
 
@@ -17,7 +17,7 @@
 - `TG_ALLOWED_CHAT_ID`
 - `TG_ALLOWED_TOPIC_ID`
 
-第一次请先用 Telegram 私聊跑通。群组和话题模式等私聊稳定后再开。
+第一次请先用 Telegram 私聊跑通。群组和话题模式等私聊稳定后再开。多个 token 表示同一服务内多个独立 Codex runtime；每个 bot 都必须单独完成私聊验收。
 
 ## 复制给 agent 的安装提示词
 
@@ -32,7 +32,7 @@
 先使用 Telegram 私聊模式。除非我明确提供 TG_ALLOWED_CHAT_ID 或 TG_ALLOWED_TOPIC_ID，否则不要配置群组/话题模式。
 
 必需配置：
-TG_BOT_TOKEN=<把 token 粘贴在这里>
+TG_BOT_TOKENS=<粘贴一个 token，或多个逗号分隔 token>
 TG_ALLOWED_USER_ID=<把 Telegram 数字用户 ID 粘贴在这里>
 DEFAULT_CWD=<把绝对工作目录粘贴在这里>
 
@@ -44,17 +44,18 @@ DEFAULT_CWD=<把绝对工作目录粘贴在这里>
 5. 运行 foxclaw init，然后写入 ~/.foxclaw/.env。不要打印或提交 bot token。
 6. 运行 foxclaw doctor。
 7. 用 foxclaw start 启动 FoxClaw。
-8. 让我在 Telegram bot 里发送 /help 和 /status。
+8. 让我在每个已配置的 Telegram bot 私聊里发送 /help、/status 和 /auth；确认 /auth 显示对应 bot runtime。
 9. 验证最终状态：
    - Linux 上 foxclaw.service 处于 active/enabled
    - foxclaw status 可以正常输出
-10. 汇报执行过的命令、最终状态和后续看日志的命令。请隐藏 TG_BOT_TOKEN，不要打印完整 token 或完整 .env。
+10. 汇报执行过的命令、最终状态和后续看日志的命令。请隐藏 TG_BOT_TOKENS，不要打印完整 token 或完整 .env。
+11. 如果启用了多个 bot，确认 foxclaw status 列出独立 app-server；群聊测试必须点名或回复目标 bot。
 ```
 
 ## 安全注意事项
 
 - 不要把 bot token 粘贴到公开 issue、公开聊天或代码仓库。
 - 不要提交 `.env`。
-- 汇报结果时隐藏 `TG_BOT_TOKEN`。
+- 汇报结果时隐藏 `TG_BOT_TOKENS` 和兼容变量 `TG_BOT_TOKEN`。
 - 第一次安装不要把 `/`、整个 `/Users`、整个 `/home` 或完整 home 目录设为 `DEFAULT_CWD`。
 - 日常启动用 `foxclaw start`；只有排障时才用前台模式 `foxclaw serve`。

package/docs/zh/foxclaw-skill.md

@@ -10,15 +10,17 @@
 
 ## 基本流程
 
-1. 准备 `TG_BOT_TOKEN`、`TG_ALLOWED_USER_ID` 和 `DEFAULT_CWD`。
+1. 准备 `TG_BOT_TOKENS`（一个或多个逗号分隔的 bot token）、`TG_ALLOWED_USER_ID` 和 `DEFAULT_CWD`。
 2. 让 Codex 使用 `skills/foxclaw`。
 3. 如果是远程机器，提供 SSH 目标。
 4. 让 Codex 执行安装、写配置、跑 `foxclaw doctor`。
-5. 启动服务后，在 Telegram bot 里发送 `/help` 和 `/status` 验证。
+5. 启动服务后，在每个配置的 Telegram bot 私聊里发送 `/help`、`/status` 和 `/auth` 验证。
 
 ## 注意事项
 
 - 不要让 agent 把完整 bot token 打印到日志或提交到仓库。
 - 第一次请先用私聊模式跑通。
+- 多个 token 会在同一服务中建立多个独立 Codex home、session 与 auth 选择；群组中必须点名或回复目标 bot。
+- 同时启用微信时，微信仍使用默认 Codex runtime，不共享隔离 Telegram bot 的线程。
 - 不要把整个 home 目录或根目录作为首次 `DEFAULT_CWD`。
 - 只有在 `doctor` 通过、服务已启动、Telegram 首条消息验证通过后，才算安装完成。

package/docs/zh/install-for-beginners.md

@@ -121,7 +121,7 @@ npm install -g @foxden-app/foxclaw
 foxclaw init
 ```
 
-这会创建默认配置文件 `~/.foxclaw/.env`，并提示你填写 Telegram bot token、Telegram 数字用户 ID 和默认工作目录。
+这会创建默认配置文件 `~/.foxclaw/.env`，并提示你填写一个或多个 Telegram bot token（多个用英文逗号分隔）、Telegram 数字用户 ID 和默认工作目录。新安装使用 `TG_BOT_TOKENS`；旧的 `TG_BOT_TOKEN` 仅用于兼容已有单 bot 配置。
 
 如果你用 pnpm：
 
@@ -141,7 +141,7 @@ nano ~/.foxclaw/.env
 第一次私聊模式只需要重点填写这些值：
 
 ```dotenv
-TG_BOT_TOKEN=123456789:replace_with_your_bot_token
+TG_BOT_TOKENS=123456789:replace_with_your_bot_token
 TG_ALLOWED_USER_ID=123456789
 TG_ALLOWED_CHAT_ID=
 TG_ALLOWED_TOPIC_ID=
@@ -152,6 +152,14 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 `TG_ALLOWED_CHAT_ID=` 和 `TG_ALLOWED_TOPIC_ID=` 第一次保持为空，不要删掉这两行；留空表示私聊模式。
 
+只有一个 bot 时先按上面的配置跑通即可。需要三条互不打断的 Codex 会话时，把多个 token 写在同一行：
+
+```dotenv
+TG_BOT_TOKENS=123456789:token_a,234567890:token_b,345678901:token_c
+```
+
+FoxClaw 仍只安装一个服务，但每个 bot 会有独立 app-server、会话目录和当前 auth。服务启动后请分别私聊每个 bot 发送 `/help` 与 `/status`。
+
 `DEFAULT_CWD` 必须是真实存在的目录，例如：
 
 ```dotenv
@@ -174,7 +182,7 @@ foxclaw doctor
 ```text
 [OK] node >= 24
 [OK] codex cli available
-[OK] telegram bot token configured
+[OK] telegram bot token(s) configured
 [OK] telegram allowed user configured
 [OK] default cwd exists
 ```
@@ -278,7 +286,7 @@ foxclaw uninstall-systemd
 foxclaw update
 ```
 
-也可以在已授权的 Telegram 私聊里发送 `/update`。它会在当前没有运行中回复、审批或待确认问题时，完成升级、自检和服务重启，并在重启后回报结果。
+也可以在已授权的 Telegram 私聊里发送 `/update`。它会在所有 Telegram bot、已启用的微信默认 runtime 和 auth 镜像写入都空闲时，尝试升级 npm/pnpm 安装的 Codex CLI，完成 FoxClaw 升级、自检和服务重启，并在发起命令的 bot 中回报结果。
 
 如果 `~/.foxclaw/.env` 已经存在，`foxclaw init` 会先询问是否更新 Telegram 和工作目录相关字段，其它配置保持不变。
 

package/docs/zh/troubleshooting.md

@@ -20,7 +20,7 @@ journalctl --user -u foxclaw.service -f
 | --- | --- | --- |
 | `[FAIL] node >= 24` | 当前 shell 使用的是旧版 Node.js。 | 先用任意方式安装或切换到 Node.js 24+，再重新执行 `foxclaw doctor`。如果服务仍用旧 Node，从 Node 24+ 的 shell 里重新执行 `foxclaw start`。 |
 | `[FAIL] codex cli available` | `codex` 命令不在 PATH 里。 | 安装 Codex CLI 或修正 PATH，再确认 `codex --version` 可用。 |
-| `[FAIL] telegram bot token configured` | `.env` 里缺少 `TG_BOT_TOKEN`。 | 从 `@BotFather` 复制 token，填入 `.env`。 |
+| `[FAIL] telegram bot token(s) configured` | `.env` 里没有 `TG_BOT_TOKENS`，也没有兼容变量 `TG_BOT_TOKEN`。 | 从 `@BotFather` 复制一个或多个 token，用逗号分隔填入 `TG_BOT_TOKENS`。 |
 | `[FAIL] telegram allowed user configured` | `.env` 里缺少 `TG_ALLOWED_USER_ID`。 | 从 `@userinfobot` 获取数字 ID，填入 `.env`。 |
 | `[FAIL] default cwd exists` | `DEFAULT_CWD` 指向不存在的目录。 | 创建该目录，或把 `DEFAULT_CWD` 改成一个真实存在的绝对路径。 |
 
@@ -183,6 +183,18 @@ Bridge 日志默认在：
 tail -f ~/.foxclaw/logs/service.log
 ```
 
+## 多 bot 模式核查
+
+配置 `TG_BOT_TOKENS` 后，`foxclaw status` 的 `bots` 列表应为每个 token 显示一个 bot id、连接状态和独立 app-server。私聊任一 bot 发送 `/status` 会显示全部 runtime 摘要；发送 `/auth` 应显示当前 `@botname` 和该 bot 的 auth 目录。
+
+每个隔离 app-server 的日志路径为：
+
+```bash
+tail -f ~/.foxclaw/logs/codex-app-server-bot<id>.log
+```
+
+群组里配置了多个 bot 时，普通未点名消息不会触发它们；使用 `@botname`、回复目标 bot，或 `/status@botname`。微信启用后仍使用默认 Codex runtime，不会出现在某个 Telegram bot 的隔离线程中。
+
 ## ChatGPT 后端 403 或 Unable to load site
 
 如果 Telegram 里看到 `ChatGPT backend 403 Forbidden`，或者 app-server 日志里出现 `Unable to load site`、`cf-ray`、`chatgpt.com/backend-api`，通常不是 `auth.json` 文件坏了，而是服务进程访问 ChatGPT 后端时没有走正确网络。