@foxden-app/foxclaw 0.3.18 → 0.3.19

package/dist/store/database.js

@@ -8,10 +8,16 @@ export class BridgeStore {
         fs.mkdirSync(path.dirname(dbPath), { recursive: true });
         this.db = new DatabaseSync(dbPath);
         this.db.exec(`
-      CREATE TABLE IF NOT EXISTS telegram_offsets (
-        bot_key TEXT PRIMARY KEY,
-        update_id INTEGER NOT NULL
-      );
+      CREATE TABLE IF NOT EXISTS telegram_offsets (
+        bot_key TEXT PRIMARY KEY,
+        update_id INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS telegram_private_scopes (
+        bot_id TEXT PRIMARY KEY,
+        scope_id TEXT NOT NULL,
+        chat_id TEXT NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
       CREATE TABLE IF NOT EXISTS chat_bindings (
         chat_id TEXT PRIMARY KEY,
         thread_id TEXT NOT NULL,
@@ -110,6 +116,13 @@ export class BridgeStore {
         disabled INTEGER NOT NULL DEFAULT 0,
         updated_at INTEGER NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS codex_auth_candidate_runtime (
+        runtime_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        disabled INTEGER NOT NULL DEFAULT 0,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (runtime_id, name)
+      );
     `);
         this.ensureColumn('thread_cache', 'name', 'TEXT');
         this.ensureColumn('thread_cache', 'model_provider', 'TEXT');
@@ -136,6 +149,17 @@ export class BridgeStore {
       ON CONFLICT(bot_key) DO UPDATE SET update_id = excluded.update_id
     `).run(botKey, updateId);
     }
+    rememberTelegramPrivateScope(botId, scopeId, chatId) {
+        this.db.prepare(`
+      INSERT INTO telegram_private_scopes (bot_id, scope_id, chat_id, updated_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(bot_id) DO UPDATE SET scope_id = excluded.scope_id, chat_id = excluded.chat_id, updated_at = excluded.updated_at
+    `).run(botId, scopeId, chatId, Date.now());
+    }
+    getTelegramPrivateChatId(botId) {
+        const row = this.db.prepare('SELECT chat_id FROM telegram_private_scopes WHERE bot_id = ?').get(botId);
+        return row ? String(row.chat_id) : null;
+    }
     getBinding(chatId) {
         const row = this.db.prepare('SELECT chat_id, thread_id, cwd, updated_at FROM chat_bindings WHERE chat_id = ?').get(chatId);
         if (!row)
@@ -462,11 +486,23 @@ export class BridgeStore {
       ON CONFLICT(scope_id) DO UPDATE SET context_token = excluded.context_token, updated_at = excluded.updated_at
     `).run(scopeId, contextToken, Date.now());
     }
-    listDisabledCodexAuthCandidateNames() {
+    listDisabledCodexAuthCandidateNames(runtimeId = 'default') {
+        if (runtimeId !== 'default') {
+            const runtimeRows = this.db.prepare('SELECT name FROM codex_auth_candidate_runtime WHERE runtime_id = ? AND disabled = 1').all(runtimeId);
+            return new Set(runtimeRows.map(row => String(row.name)));
+        }
         const rows = this.db.prepare('SELECT name FROM codex_auth_candidates WHERE disabled = 1').all();
         return new Set(rows.map(row => String(row.name)));
     }
-    setCodexAuthCandidateDisabled(name, disabled) {
+    setCodexAuthCandidateDisabled(name, disabled, runtimeId = 'default') {
+        if (runtimeId !== 'default') {
+            this.db.prepare(`
+        INSERT INTO codex_auth_candidate_runtime (runtime_id, name, disabled, updated_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT(runtime_id, name) DO UPDATE SET disabled = excluded.disabled, updated_at = excluded.updated_at
+      `).run(runtimeId, name, disabled ? 1 : 0, Date.now());
+            return;
+        }
         this.db.prepare(`
       INSERT INTO codex_auth_candidates (name, disabled, updated_at)
       VALUES (?, ?, ?)

package/dist/telegram/addressing.d.ts

@@ -27,6 +27,7 @@ interface DefaultScopeParams {
     allowedChatId: string | null;
     allowedTopicId: number | null;
     topicId: number | null;
+    requireExplicitGroupAddressing?: boolean;
 }
 export declare function resolveTelegramAddressing(params: ResolveTelegramAddressingParams): TelegramAddressingDecision;
 export declare function isDefaultTelegramScope(params: DefaultScopeParams): boolean;

package/dist/telegram/addressing.js

@@ -21,6 +21,9 @@ export function isDefaultTelegramScope(params) {
     if (params.chatType === 'private') {
         return true;
     }
+    if (params.requireExplicitGroupAddressing) {
+        return false;
+    }
     if (params.allowedChatId === null) {
         return false;
     }

package/dist/telegram/gateway.d.ts

@@ -34,12 +34,15 @@ export declare class TelegramGateway extends EventEmitter {
     private readonly pollIntervalMs;
     private readonly store;
     private readonly logger;
+    private readonly namespacedScopes;
     private running;
     private botKey;
     private botUsername;
     private botUserId;
-    constructor(botToken: string, allowedUserId: string, allowedChatId: string | null, pollIntervalMs: number, store: BridgeStore, logger: Logger);
+    constructor(botToken: string, allowedUserId: string, allowedChatId: string | null, pollIntervalMs: number, store: BridgeStore, logger: Logger, namespacedScopes?: boolean);
     get username(): string | null;
+    get identity(): string | null;
+    initializeIdentity(): Promise<string>;
     start(): Promise<void>;
     stop(): void;
     sendMessage(chatId: string, text: string, inlineKeyboard?: Array<Array<{

package/dist/telegram/gateway.js

@@ -11,11 +11,12 @@ export class TelegramGateway extends EventEmitter {
     pollIntervalMs;
     store;
     logger;
+    namespacedScopes;
     running = false;
     botKey;
     botUsername = null;
     botUserId = null;
-    constructor(botToken, allowedUserId, allowedChatId, pollIntervalMs, store, logger) {
+    constructor(botToken, allowedUserId, allowedChatId, pollIntervalMs, store, logger, namespacedScopes = false) {
         super();
         this.botToken = botToken;
         this.allowedUserId = allowedUserId;
@@ -23,16 +24,26 @@ export class TelegramGateway extends EventEmitter {
         this.pollIntervalMs = pollIntervalMs;
         this.store = store;
         this.logger = logger;
+        this.namespacedScopes = namespacedScopes;
         this.botKey = `telegram:${crypto.createHash('sha256').update(this.botToken).digest('hex').slice(0, 8)}`;
     }
     get username() {
         return this.botUsername;
     }
+    get identity() {
+        return this.botUserId === null ? null : `bot${this.botUserId}`;
+    }
+    async initializeIdentity() {
+        await this.resolveBotIdentity(true);
+        return this.identity;
+    }
     async start() {
         if (this.running)
             return;
         this.running = true;
-        await this.resolveBotIdentity();
+        if (this.botUserId === null) {
+            await this.resolveBotIdentity(this.namespacedScopes);
+        }
         await this.registerCommands();
         void this.pollLoop();
     }
@@ -134,12 +145,16 @@ export class TelegramGateway extends EventEmitter {
     async downloadResolvedFile(remoteFilePath, destinationPath) {
         return downloadTelegramFile(this.botToken, remoteFilePath, destinationPath);
     }
-    async resolveBotIdentity() {
+    async resolveBotIdentity(required = false) {
         const result = await callTelegramApi(this.botToken, 'getMe', {});
         if (result.ok && result.result) {
             this.botKey = `telegram:bot${result.result.id}`;
             this.botUserId = result.result.id;
             this.botUsername = result.result.username ?? null;
+            return;
+        }
+        if (required) {
+            throw new Error(result.description || 'Failed to resolve Telegram bot identity');
         }
     }
     async registerCommands() {
@@ -187,7 +202,7 @@ export class TelegramGateway extends EventEmitter {
             const attachments = extractAttachments(update.message);
             const text = update.message.text ?? update.message.caption ?? '';
             const topicId = update.message.message_thread_id ?? null;
-            const scopeId = toTelegramBridgeScopeId(createTelegramScopeId(String(update.message.chat.id), topicId));
+            const scopeId = toTelegramBridgeScopeId(createTelegramScopeId(String(update.message.chat.id), topicId), this.namespacedScopes ? this.identity : null);
             const entities = update.message.text ? (update.message.entities ?? []) : (update.message.caption_entities ?? []);
             const replyToBot = this.botUserId !== null && update.message.reply_to_message?.from?.id === this.botUserId;
             if (text || attachments.length > 0) {
@@ -204,6 +219,9 @@ export class TelegramGateway extends EventEmitter {
                     replyToBot,
                     ...(update.message.from.language_code ? { languageCode: update.message.from.language_code } : {}),
                 });
+                if (update.message.chat.type === 'private' && this.identity) {
+                    this.store.rememberTelegramPrivateScope(this.identity, scopeId, String(update.message.chat.id));
+                }
                 return;
             }
         }
@@ -216,7 +234,7 @@ export class TelegramGateway extends EventEmitter {
             this.emit('callback', {
                 chatId: String(update.callback_query.message.chat.id),
                 topicId,
-                scopeId: toTelegramBridgeScopeId(createTelegramScopeId(String(update.callback_query.message.chat.id), topicId)),
+                scopeId: toTelegramBridgeScopeId(createTelegramScopeId(String(update.callback_query.message.chat.id), topicId), this.namespacedScopes ? this.identity : null),
                 userId: String(update.callback_query.from.id),
                 data: update.callback_query.data,
                 callbackQueryId: update.callback_query.id,

package/dist/types.d.ts

@@ -340,4 +340,11 @@ export interface RuntimeStatus {
         telegram: boolean;
         weixin: boolean;
     };
+    bots?: Array<{
+        id: string;
+        username: string | null;
+        connected: boolean;
+        activeTurns: number;
+        codexAppServer?: RuntimeStatus['codexAppServer'];
+    }>;
 }

package/dist/update.d.ts

@@ -6,6 +6,7 @@ export interface SelfUpdateStatus {
     locale: AppLocale;
     fromVersion: string;
     toVersion: string | null;
+    codexUpdate?: string | null;
     error: string | null;
     updatedAt: string;
 }
@@ -19,6 +20,7 @@ export interface SelfUpdateInstaller {
     command: string;
     installArgs: string[];
     rootArgs: string[];
+    pnpmHome?: string;
 }
 interface CreateSelfUpdateRuntimeOptions {
     entryPoint: string;
@@ -26,12 +28,14 @@ interface CreateSelfUpdateRuntimeOptions {
     version: string;
     statusPath: string;
     logPath: string;
+    codexCliBin?: string;
 }
 interface PerformSelfUpdateOptions {
     entryPoint: string;
     nodePath: string;
     version: string;
     notificationFile?: string;
+    codexCliBin?: string;
     env?: NodeJS.ProcessEnv;
 }
 export interface SelfUpdateOutcome {
@@ -43,6 +47,7 @@ export interface SelfUpdateOutcome {
 export declare function selfUpdateStatusPath(statusPath: string): string;
 export declare function inferPnpmHomeFromEntryPoint(entryPoint: string): string | null;
 export declare function resolveSelfUpdateInstaller(entryPoint: string, nodePath?: string, exists?: (target: string) => boolean, env?: NodeJS.ProcessEnv): SelfUpdateInstaller;
+export declare function resolveCodexUpdateInstaller(codexCliBin: string, nodePath?: string, exists?: (target: string) => boolean, env?: NodeJS.ProcessEnv, realpath?: (target: string) => string, readText?: (target: string) => string): SelfUpdateInstaller | null;
 export declare function readSelfUpdateStatus(statusFile: string): SelfUpdateStatus | null;
 export declare function writeSelfUpdateStatus(statusFile: string, status: SelfUpdateStatus): void;
 export declare function createSelfUpdateRuntime(options: CreateSelfUpdateRuntimeOptions): SelfUpdateRuntime;

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:
 
@@ -233,7 +233,7 @@ Later commands are sorted by recent usage. Plain text, photos, and files continu
 - `/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`。