@foxden-app/foxclaw 0.3.17 → 0.3.19

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
 
@@ -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>
 
@@ -49,13 +49,13 @@ Tasks:
 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.
 ```
 
 ## 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

@@ -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=
@@ -176,7 +176,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 +280,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 bot is idle with no approval or question active, it attempts to update an npm/pnpm-managed Codex CLI, upgrades FoxClaw, checks, restarts the service, and reports the result after restart.
 
 ## 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. |
 

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 output-speed metrics use a background-generated historical snapshot instead of scanning large logs during the request.
+- `/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.
 - `/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 bot runtime has a turn, approval, or question active, then reports the result 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; validated login/refresh credentials are safely mirrored between bot homes.
 
 ### 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:
 
@@ -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 默认工作的目录
 
@@ -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=<把绝对工作目录粘贴在这里>
 
@@ -48,13 +48,13 @@ DEFAULT_CWD=<把绝对工作目录粘贴在这里>
 9. 验证最终状态：
    - Linux 上 foxclaw.service 处于 active/enabled
    - foxclaw status 可以正常输出
-10. 汇报执行过的命令、最终状态和后续看日志的命令。请隐藏 TG_BOT_TOKEN，不要打印完整 token 或完整 .env。
+10. 汇报执行过的命令、最终状态和后续看日志的命令。请隐藏 TG_BOT_TOKENS，不要打印完整 token 或完整 .env。
 ```
 
 ## 安全注意事项
 
 - 不要把 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,7 +10,7 @@
 
 ## 基本流程
 
-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`。

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

@@ -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=
@@ -174,7 +174,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 +278,7 @@ foxclaw uninstall-systemd
 foxclaw update
 ```
 
-也可以在已授权的 Telegram 私聊里发送 `/update`。它会在当前没有运行中回复、审批或待确认问题时，完成升级、自检和服务重启，并在重启后回报结果。
+也可以在已授权的 Telegram 私聊里发送 `/update`。它会在所有 bot 都没有运行中回复、审批或待确认问题时，尝试升级 npm/pnpm 安装的 Codex CLI，完成 FoxClaw 升级、自检和服务重启，并在重启后回报结果。
 
 如果 `~/.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` 改成一个真实存在的绝对路径。 |
 

package/docs/zh/user-manual.md

@@ -100,7 +100,7 @@ foxclaw init
 
 ### 1.6 填写配置
 
-`foxclaw init` 会创建默认配置文件 `~/.foxclaw/.env`，并提示填写 Telegram bot token、Telegram 数字用户 ID 和默认工作目录。如果当前 shell 里有 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 等代理变量，它也会询问是否写入 FoxClaw 配置。配置了 `HTTP_PROXY` 或 `HTTPS_PROXY` 后，FoxClaw 会在安装服务时显式传给 systemd/launchd，并启用 Node 的 env proxy。任何一项都可以直接回车跳过，之后再手动编辑：
+`foxclaw init` 会创建默认配置文件 `~/.foxclaw/.env`，并提示填写一个或多个 Telegram bot token（逗号分隔）、Telegram 数字用户 ID 和默认工作目录。如果当前 shell 里有 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 等代理变量，它也会询问是否写入 FoxClaw 配置。配置了 `HTTP_PROXY` 或 `HTTPS_PROXY` 后，FoxClaw 会在安装服务时显式传给 systemd/launchd，并启用 Node 的 env proxy。任何一项都可以直接回车跳过，之后再手动编辑：
 
 ```bash
 $EDITOR ~/.foxclaw/.env
@@ -109,7 +109,7 @@ $EDITOR ~/.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=
@@ -120,7 +120,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 字段说明：
 
-- `TG_BOT_TOKEN`：从 `@BotFather` 拿到的 bot token。
+- `TG_BOT_TOKENS`：从 `@BotFather` 拿到的一个或多个 bot token，多项用英文逗号分隔。旧版单 bot 配置 `TG_BOT_TOKEN` 仍兼容。
 - `TG_ALLOWED_USER_ID`：你的 Telegram 数字用户 ID。
 - `TG_ALLOWED_CHAT_ID`：第一次保持为空，表示私聊模式。
 - `TG_ALLOWED_TOPIC_ID`：第一次保持为空，表示不绑定 Telegram 话题。
@@ -136,7 +136,7 @@ foxclaw start
 foxclaw status
 ```
 
-后续升级只需运行 `foxclaw update`；它会使用当前安装 FoxClaw 的 npm 或 pnpm，全局升级后执行自检并重启后台服务。
+后续升级只需运行 `foxclaw update`；它会使用当前安装 FoxClaw 的 npm 或 pnpm，尝试同时升级由 npm/pnpm 全局安装的 Codex CLI，然后执行自检并重启后台服务。
 
 Linux 查看服务日志：
 
@@ -230,10 +230,10 @@ TG_ALLOWED_TOPIC_ID=42
 
 ### 3.2 `/status`、`/account`、`/quota`、`/update`
 
-- `/status`：查看 FoxClaw、app-server、当前绑定线程、模型、权限和 Codex 用量摘要。本地 session/Token/输出速度使用后台生成的历史快照，避免状态查询现场扫描大量日志。
+- `/status`：查看 FoxClaw、app-server、当前绑定线程、模型、权限和 Codex 用量摘要。本地 session/Token/可见答复吞吐使用后台生成的历史快照，避免状态查询现场扫描大量日志；答复吞吐按完成轮次端到端耗时计算，排除推理 token，但包含等待与工具执行时间。
 - `/account`：查看当前 Codex 登录账号。
 - `/quota`：查看 Codex 用量和额度窗口。
-- `/update`：升级 FoxClaw、自检并重启服务；当前有运行中回复、审批或待确认问题时会拒绝执行，重启后会回报结果。
+- `/update`：升级 FoxClaw，并尝试升级 npm/pnpm 安装的 Codex CLI，然后自检和重启服务；任意 bot runtime 有运行中回复、审批或待确认问题时都会拒绝执行，重启后会回报结果。
 
 ### 3.3 `/config`、`/requirements`、`/provider`
 
@@ -335,11 +335,11 @@ FoxClaw 的聊天是“绑定线程”的。你在手机上打开某个 Codex
 
 ## 6. Codex 登录和 auth 轮转
 
-这是 FoxClaw 的特色功能。Codex 的登录状态通常保存在 `~/.codex/auth.json`。FoxClaw 把多个账号保存成候选文件，并通过切换 `auth.json` 指向哪个候选来换号。
+这是 FoxClaw 的特色功能。Codex 的登录状态通常保存在 `~/.codex/auth.json`。FoxClaw 把多个账号保存成候选文件，并通过切换 `auth.json` 指向哪个候选来换号。启用 `TG_BOT_TOKENS` 多 bot 模式后，每个 bot 使用独立 Codex home、独立 app-server 和独立当前候选，因此可以并行运行、单独切号；已验证的登录/刷新凭据会安全镜像到其他 bot home。
 
 ### 6.1 文件格式
 
-候选文件放在 Codex auth 目录，默认是 `~/.codex/`。如果你设置了 `CODEX_AUTH_DIR`，则使用那个目录。
+单 bot 兼容模式的候选文件放在 Codex auth 目录，默认是 `~/.codex/`。如果你设置了 `CODEX_AUTH_DIR`，则使用那个目录。多 bot 模式以这个目录作为候选源，并在 `~/.foxclaw/codex/telegram/bot<id>/home/` 下为每个 bot 保存隔离副本。
 
 推荐命名：
 
@@ -357,7 +357,7 @@ FoxClaw 识别这些候选文件名：
 - `auth.json.<name>`
 - `auth.json-<name>`
 
-`auth.json` 是 Codex 当前使用的文件。切换账号时，FoxClaw 会把 `auth.json` 指向某个候选文件。候选文件内容是 Codex CLI 生成的 JSON，FoxClaw 不依赖里面的私密字段，也不建议手写这些字段。
+`auth.json` 是 Codex 当前使用的文件。切换账号时，FoxClaw 会把 `auth.json` 指向某个候选文件。候选文件内容是 Codex CLI 生成的 JSON，不建议手写这些字段。多 bot 镜像只在能校验同一账号标识且刷新时间更新时复制候选，避免同名候选意外覆盖成另一个账号。
 
 如果你已经有一个可用的 `auth.json`，可以先备份成候选：
 
@@ -416,7 +416,7 @@ Candidates: 2
 - `/auth disable <n>`：禁用第 n 个候选，自动轮转会跳过它。
 - `/auth reload` 或 `/auth_reload`：重启 app-server，重新加载当前 `auth.json`。
 
-切换 auth 时，如果当前还有活跃 turn、待审批、待用户输入或 MCP elicitation，FoxClaw 会先拒绝切换，避免中途换号破坏正在进行的请求。
+切换 auth 时，如果当前 bot runtime 还有活跃 turn、待审批、待用户输入或 MCP elicitation，FoxClaw 会先拒绝切换，避免中途换号破坏正在进行的请求；另一个空闲 bot 不受影响。
 
 ### 6.4 自动轮转如何工作
 
@@ -452,7 +452,7 @@ auth.json_backup       # 备用账号，可按需 enable/disable
 
 ## 8. 安全建议
 
-- 不要把 `TG_BOT_TOKEN`、`~/.codex/auth.json*` 或 `.env` 发给别人。
+- 不要把 `TG_BOT_TOKENS`、`TG_BOT_TOKEN`、`~/.codex/auth.json*` 或 `.env` 发给别人。
 - 第一次不要把 `DEFAULT_CWD` 设成 `/`、`/home`、`/Users` 或整个 home。
 - 不确定权限时，用 `/permissions read-only` 或 `/setup` 选 `Read-only`。
 - 群组模式只允许配置的 `TG_ALLOWED_USER_ID` 操作，但仍建议只放进可信群。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",