@foxden-app/foxclaw 0.3.18 → 0.4.0

package/.env.example

@@ -1,5 +1,8 @@
-# Required: one bot token per device
-TG_BOT_TOKEN=<telegram_bot_token>
+# Required for new installs: one or more bot tokens for this host
+# Comma-separated bot tokens. Each bot gets an independent Codex runtime/auth selection.
+TG_BOT_TOKENS=<telegram_bot_token>
+# Backward-compatible single-runtime setup:
+# TG_BOT_TOKEN=<telegram_bot_token>
 
 # Required: only this Telegram user can control the bridge
 TG_ALLOWED_USER_ID=<telegram_user_id>
@@ -11,7 +14,9 @@ TG_ALLOWED_CHAT_ID=
 # Leave empty to use the whole allowed group as the default scope
 TG_ALLOWED_TOPIC_ID=
 
-# Optional Codex Desktop bridge settings
+# Optional Codex Desktop bridge settings.
+# In TG_BOT_TOKENS mode isolated Telegram runtimes start app-server directly and
+# do not auto-launch Codex Desktop; this remains applicable to the default/Weixin runtime.
 CODEX_APP_AUTOLAUNCH=true
 CODEX_APP_LAUNCH_CMD=codex app
 # Optional: persist the managed app-server pid/port and collect its stdout/stderr

package/README.md

@@ -40,7 +40,7 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex，
 - Git、Node、`.env` 都玩得转？直接往下看快速设置。
 - 卡住了？看 [故障排查](./docs/zh/troubleshooting.md)。
 
-最低要求：一个 Telegram bot token、你的 Telegram 数字用户 ID、Node.js 24+、一份已登录的 `codex` CLI。首次安装大约 10–20 分钟。
+最低要求：一个或多个 Telegram bot token、你的 Telegram 数字用户 ID、Node.js 24+、一份已登录的 `codex` CLI。首次安装大约 10–20 分钟。新安装请使用 `TG_BOT_TOKENS`；`TG_BOT_TOKEN` 只用于兼容旧的单 runtime 配置。
 
 **30 秒体验**：启动 FoxClaw 后，给你的 Telegram 机器人发一句 `List files in DEFAULT_CWD`。Codex 会在本地检查那个目录，然后把结果发回 Telegram。
 
@@ -75,7 +75,7 @@ foxclaw start
 跑 `doctor` 或 `start` 之前先把 `.env` 填好。私聊模式最小配置：
 
 ```dotenv
-TG_BOT_TOKEN=123456:telegram-token
+TG_BOT_TOKENS=123456:telegram-token
 TG_ALLOWED_USER_ID=123456789
 DEFAULT_CWD=/absolute/path/to/workspace
 DEFAULT_APPROVAL_POLICY=on-request
@@ -84,7 +84,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 配置文件默认在 `~/.foxclaw/.env`。想放别处的话设 `FOXCLAW_ENV=/path/to/.env`。
 
-`foxclaw start` 会自动检查环境并安装/重启后台服务。后续升级直接运行 `foxclaw update`，它会沿用当前的 npm/pnpm 全局安装方式，完成安装、自检和服务重启。
+`foxclaw start` 会自动检查环境并安装/重启后台服务。后续升级直接运行 `foxclaw update`，它会沿用当前的 npm/pnpm 全局安装方式，尝试同步升级 npm/pnpm 安装的 Codex CLI，再完成安装、自检和服务重启。
 
 FoxClaw 只响应 `TG_ALLOWED_USER_ID` 的消息——把机器人拉进群不代表群里所有人都能用。
 
@@ -93,7 +93,7 @@ FoxClaw 只响应 `TG_ALLOWED_USER_ID` 的消息——把机器人拉进群不
 
 **核心能力：**
 - 通过 Telegram 私聊、群组、话题控制本地 Codex
-- 可选微信/iLink 通道，复用同一套桥接核心
+- 可选微信/iLink 通道；在多 Telegram bot 模式下仍使用原默认 Codex runtime，不与隔离 bot 会话混用
 - 手机上完整管理 Codex 线程生命周期：创建、重命名、归档、fork、回滚、compact、review、diff
 - 命令、文件变更、细粒度权限审批的内联按钮——手机上一键审批
 - MCP elicitation 卡片——工具在 turn 中提出结构化问题时展示
@@ -111,6 +111,7 @@ FoxClaw 只响应 `TG_ALLOWED_USER_ID` 的消息——把机器人拉进群不
 **可靠性：**
 - SQLite 持久化：绑定、offset、审批、待处理提示、审计日志
 - 单实例进程锁，防止同一 bot token 重复 polling
+- `TG_BOT_TOKENS` 支持一台机器同时运行多个 Telegram bot；每个 bot 使用独立 Codex app-server、会话和 `/auth` 选择
 
 </details>
 
@@ -178,7 +179,7 @@ FoxClaw 最初基于 `Gan-Xing/telegram-codex-app-bridge` fork 演进而来，
 
 ## Telegram 设置
 
-1. 用 `@BotFather` 创建机器人，token 填入 `TG_BOT_TOKEN`。
+1. 用 `@BotFather` 创建一个或多个机器人，token 以逗号分隔填入 `TG_BOT_TOKENS`。
 2. 拿到你的 Telegram 数字用户 ID，填入 `TG_ALLOWED_USER_ID`。
 3. `foxclaw start` 启动。
 4. 打开和机器人的私聊，发 `/help`。
@@ -194,6 +195,15 @@ TG_ALLOWED_TOPIC_ID=42
 - 只填 `TG_ALLOWED_CHAT_ID` → 允许一个群组作为默认会话范围。
 - 两个都填 → 绑定到某个话题。
 - 配了群组后，`TG_ALLOWED_USER_ID` 的私聊依然可用。
+- 配置多个 bot 时，同一个授权群内只有 `@botname` 命令、mention 或回复该 bot 的消息会被它处理，避免多个 Codex 会话同时响应。
+
+多 bot 并行示例：
+
+```dotenv
+TG_BOT_TOKENS=123456:token_a,234567:token_b
+```
+
+FoxClaw 仍然只运行一个系统服务，但会为每个 bot 启动独立 `codex app-server` 和独立 `CODEX_HOME`。因此 A 私聊运行 turn 时，B 私聊仍可独立切换自己的 `/auth`。候选凭据由 FoxClaw 在登录或刷新验证后镜像同步，各 bot 的当前选择互不影响。每个 bot 首次私聊发送 `/help` 和 `/status`；`/auth` 会标明正在操作的 bot runtime，`/status` 会列出全部 bot 的连接、当前 auth 和活动 turn 摘要。
 
 **怎么找群组和话题 ID：**
 
@@ -229,7 +239,7 @@ CODEX_APP_SYNC_ON_OPEN=true
 CODEX_APP_SYNC_ON_TURN_COMPLETE=false
 ```
 
-FoxClaw 会把 `codex app-server` 作为 detached 子进程启动，记录其 pid 和端口。重启时如果进程还活着就直接重连，否则拉起新进程。`/auth_reload` 和认证切换会重启 app-server 以重新加载 `auth.json`。
+FoxClaw 会把 `codex app-server` 作为 detached 子进程启动，记录其 pid 和端口。使用 `TG_BOT_TOKENS` 时，每个 bot 都有自己的 app-server 与 Codex home，并在该隔离 runtime 内强制使用文件凭据存储；隔离 bot 不自动拉起 Codex Desktop，避免多个新 home 同时初始化桌面状态。重启时如果对应进程还活着就直接重连，否则拉起新进程。`/auth_reload` 和认证切换只重启发起操作的 bot runtime。
 
 一般不需要手动固定 app-server 端口。
 
@@ -274,7 +284,7 @@ WX_ALLOWED_ILINK_USER_IDS=
 foxclaw weixin-login
 ```
 
-微信运行时文件在 `~/.foxclaw/weixin`。
+微信运行时文件在 `~/.foxclaw/weixin`。启用 `TG_BOT_TOKENS` 时，微信继续连接默认 Codex runtime 与原 home，不会查看或恢复隔离 Telegram bot 的线程。
 
 ## Codex Skill
 

package/README_EN.md

@@ -40,7 +40,7 @@ FoxClaw is more than message forwarding. It provides Telegram panels for Codex w
 - Already comfortable with Git, Node, and `.env` files? Use the quick setup below.
 - Something failed? Check [Troubleshooting](./docs/troubleshooting.md).
 
-The minimum install needs only a Telegram bot token, your numeric Telegram user id, Node.js 24+, and a logged-in `codex` CLI. A first install usually takes 10–20 minutes.
+The minimum install needs one or more Telegram bot tokens, your numeric Telegram user id, Node.js 24+, and a logged-in `codex` CLI. A first install usually takes 10–20 minutes. New installs should use `TG_BOT_TOKENS`; `TG_BOT_TOKEN` exists only for legacy single-runtime compatibility.
 
 **30-second demo**: after FoxClaw is running, send `List files in DEFAULT_CWD` to your Telegram bot. FoxClaw asks local Codex to inspect that folder on your computer and sends the answer back to Telegram.
 
@@ -75,7 +75,7 @@ foxclaw start
 Fill `.env` before running `doctor` or `start`. Minimum private-chat config:
 
 ```dotenv
-TG_BOT_TOKEN=123456:telegram-token
+TG_BOT_TOKENS=123456:telegram-token
 TG_ALLOWED_USER_ID=123456789
 DEFAULT_CWD=/absolute/path/to/workspace
 DEFAULT_APPROVAL_POLICY=on-request
@@ -84,7 +84,7 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 The default config file is `~/.foxclaw/.env`. Set `FOXCLAW_ENV=/path/to/.env` if you want to keep it somewhere else.
 
-`foxclaw start` runs checks and installs or restarts the background service. For later upgrades, run `foxclaw update`; it preserves the current npm/pnpm global-install method, runs checks, and restarts the service.
+`foxclaw start` runs checks and installs or restarts the background service. For later upgrades, run `foxclaw update`; it preserves the current npm/pnpm global-install method, attempts to update an npm/pnpm-managed Codex CLI, runs checks, and restarts the service.
 
 FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a group does not make it available to every group member.
 
@@ -93,7 +93,7 @@ FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a gr
 
 **Core capabilities:**
 - Telegram private chat, group, and topic control for your local Codex
-- Optional Weixin/iLink channel sharing the same bridge core
+- Optional Weixin/iLink channel; in multi-Telegram mode it stays on the original default Codex runtime rather than sharing an isolated bot session
 - Full thread lifecycle management from mobile: create, rename, archive, fork, rollback, compact, review, diff
 - Inline approval buttons for commands, file changes, and granular permissions — one tap to approve
 - MCP elicitation cards for structured questions raised by tools during a turn
@@ -111,6 +111,7 @@ FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a gr
 **Reliability:**
 - SQLite persistence for bindings, offsets, approvals, pending input prompts, and audit logs
 - Single-instance process lock to prevent duplicate Telegram polling on the same bot token
+- `TG_BOT_TOKENS` runs multiple Telegram bots on one host with independent Codex app-servers, sessions, and `/auth` selections
 
 </details>
 
@@ -178,7 +179,7 @@ FoxClaw originally evolved from a fork of `Gan-Xing/telegram-codex-app-bridge` a
 
 ## Telegram Setup
 
-1. Create a bot with `@BotFather` and copy the token into `TG_BOT_TOKEN`.
+1. Create one or more bots with `@BotFather` and put their comma-separated tokens into `TG_BOT_TOKENS`.
 2. Get your Telegram numeric user id and place it into `TG_ALLOWED_USER_ID`.
 3. Start FoxClaw with `foxclaw start`.
 4. Open a private chat with the bot and send `/help`.
@@ -194,6 +195,15 @@ TG_ALLOWED_TOPIC_ID=42
 - Set `TG_ALLOWED_CHAT_ID` only to allow one group as the default conversation scope.
 - Set both `TG_ALLOWED_CHAT_ID` and `TG_ALLOWED_TOPIC_ID` to bind one topic as the default scope.
 - Private chat remains available for `TG_ALLOWED_USER_ID` even when a group is configured.
+- With multiple bots, a configured group handles only `@botname` commands, mentions, or replies addressed to each bot, preventing duplicate Codex responses.
+
+Parallel bot example:
+
+```dotenv
+TG_BOT_TOKENS=123456:token_a,234567:token_b
+```
+
+FoxClaw remains one system service, but starts an independent `codex app-server` and `CODEX_HOME` for each bot. While bot A is running a turn, bot B can switch its own `/auth` selection. Candidate credentials are mirrored only after validated login or refresh; current selections remain independent. Send `/help` and `/status` in a private chat with each bot after installation; `/auth` names the runtime being managed, and `/status` summarizes every bot's connection, selected auth, and active turns.
 
 **How to find group and topic IDs:**
 
@@ -229,7 +239,7 @@ CODEX_APP_SYNC_ON_OPEN=true
 CODEX_APP_SYNC_ON_TURN_COMPLETE=false
 ```
 
-FoxClaw starts `codex app-server` as a detached, bridge-managed process and records its pid and port. On restart, it reconnects to the recorded app-server if that process is still alive; otherwise it starts a new one. `/auth_reload` and auth switching restart the managed app-server so the current `auth.json` is reloaded.
+FoxClaw starts `codex app-server` as a detached, bridge-managed process and records its pid and port. With `TG_BOT_TOKENS`, each bot has its own app-server and Codex home, and its isolated runtime is forced to use file-backed credentials. Isolated Telegram runtimes do not auto-launch Codex Desktop, avoiding simultaneous desktop-state initialization for fresh homes. On restart, FoxClaw reconnects to each live recorded app-server or starts a replacement. `/auth_reload` and auth switching restart only the requesting bot runtime.
 
 No static Codex app-server port is required in normal installs.
 
@@ -274,7 +284,7 @@ Run the QR login helper once after building:
 foxclaw weixin-login
 ```
 
-Weixin runtime files default to `~/.foxclaw/weixin`.
+Weixin runtime files default to `~/.foxclaw/weixin`. When `TG_BOT_TOKENS` is enabled, Weixin continues to use the default Codex runtime and original home; it does not inspect or resume isolated Telegram bot threads.
 
 ## Codex Skill
 

package/dist/auth/mirror.d.ts

@@ -0,0 +1,38 @@
+import type { Logger } from '../logger.js';
+export interface AuthMirrorRuntime {
+    id: string;
+    label?: string;
+    authDir: string;
+    notify?: (message: string) => Promise<void>;
+}
+export interface AuthMirrorStatus {
+    candidateName: string;
+    sourceRuntimeId: string;
+    sourceLabel: string;
+    syncedAt: string;
+}
+export declare class AuthCandidateMirror {
+    private readonly canonicalDir;
+    private readonly runtimes;
+    private readonly logger;
+    private readonly statusPath;
+    private timer;
+    private readonly lastSyncedRefresh;
+    private activeOperations;
+    private lastStatus;
+    constructor(canonicalDir: string, runtimes: AuthMirrorRuntime[], logger: Logger, statusPath?: string | null);
+    initialize(): Promise<void>;
+    start(): void;
+    stop(): void;
+    isIdle(): boolean;
+    getStatus(): AuthMirrorStatus | null;
+    syncRuntimeCandidate(runtimeId: string, candidateName: string): Promise<boolean>;
+    private scan;
+    private propagateValidatedCandidate;
+    private withActivity;
+    private ensureCanonicalDefaultCandidate;
+    private collectCandidateNames;
+    private reconcileCandidateAtStartup;
+    private resolveCanonicalCurrentCandidate;
+}
+export declare function isAuthCandidateName(name: string): boolean;

package/dist/auth/mirror.js

@@ -0,0 +1,259 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const AUTH_SCAN_INTERVAL_MS = 5_000;
+export class AuthCandidateMirror {
+    canonicalDir;
+    runtimes;
+    logger;
+    statusPath;
+    timer = null;
+    lastSyncedRefresh = new Map();
+    activeOperations = 0;
+    lastStatus = null;
+    constructor(canonicalDir, runtimes, logger, statusPath = null) {
+        this.canonicalDir = canonicalDir;
+        this.runtimes = runtimes;
+        this.logger = logger;
+        this.statusPath = statusPath;
+    }
+    async initialize() {
+        this.lastStatus = await readMirrorStatus(this.statusPath);
+        await fs.mkdir(this.canonicalDir, { recursive: true, mode: 0o700 });
+        await this.ensureCanonicalDefaultCandidate();
+        const candidateNames = await this.collectCandidateNames();
+        for (const name of candidateNames) {
+            await this.reconcileCandidateAtStartup(name);
+        }
+        const canonicalCandidateNames = await listAuthCandidateNames(this.canonicalDir);
+        const defaultCandidate = await this.resolveCanonicalCurrentCandidate()
+            ?? canonicalCandidateNames.sort()[0]
+            ?? null;
+        for (const runtime of this.runtimes) {
+            await fs.mkdir(runtime.authDir, { recursive: true, mode: 0o700 });
+            for (const name of canonicalCandidateNames) {
+                const destination = path.join(runtime.authDir, name);
+                if (!(await exists(destination))) {
+                    await atomicCopy(path.join(this.canonicalDir, name), destination);
+                }
+            }
+            if (defaultCandidate && !(await exists(path.join(runtime.authDir, 'auth.json')))) {
+                await pointAuthSymlink(runtime.authDir, defaultCandidate);
+            }
+        }
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.scan().catch((error) => {
+                this.logger.warn('auth.mirror.scan_failed', { error: formatError(error) });
+            });
+        }, AUTH_SCAN_INTERVAL_MS);
+        this.timer.unref();
+    }
+    stop() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    isIdle() {
+        return this.activeOperations === 0;
+    }
+    getStatus() {
+        return this.lastStatus;
+    }
+    async syncRuntimeCandidate(runtimeId, candidateName) {
+        if (!isAuthCandidateName(candidateName))
+            return false;
+        const runtime = this.runtimes.find((entry) => entry.id === runtimeId);
+        if (!runtime)
+            return false;
+        return this.withActivity(() => this.propagateValidatedCandidate(runtime, candidateName));
+    }
+    async scan() {
+        await this.withActivity(async () => {
+            for (const runtime of this.runtimes) {
+                const names = await listAuthCandidateNames(runtime.authDir);
+                for (const name of names) {
+                    await this.propagateValidatedCandidate(runtime, name);
+                }
+            }
+        });
+    }
+    async propagateValidatedCandidate(runtime, name) {
+        const sourcePath = path.join(runtime.authDir, name);
+        const record = await readChatGptAuthRecord(sourcePath);
+        if (!record)
+            return false;
+        const canonicalPath = path.join(this.canonicalDir, name);
+        const canonical = await readChatGptAuthRecord(canonicalPath);
+        if (canonical && canonical.accountId !== record.accountId) {
+            this.logger.warn('auth.mirror.account_conflict', { runtimeId: runtime.id, name });
+            return false;
+        }
+        const previousRefresh = Math.max(canonical?.lastRefreshMs ?? 0, this.lastSyncedRefresh.get(name) ?? 0);
+        if (record.lastRefreshMs <= previousRefresh) {
+            return false;
+        }
+        await atomicWrite(canonicalPath, record.raw);
+        for (const target of this.runtimes) {
+            if (target.id !== runtime.id) {
+                await atomicWrite(path.join(target.authDir, name), record.raw);
+            }
+        }
+        this.lastSyncedRefresh.set(name, record.lastRefreshMs);
+        const sourceLabel = runtime.label ?? runtime.id;
+        this.lastStatus = {
+            candidateName: name,
+            sourceRuntimeId: runtime.id,
+            sourceLabel,
+            syncedAt: new Date().toISOString(),
+        };
+        await writeMirrorStatus(this.statusPath, this.lastStatus);
+        this.logger.info('auth.mirror.synced', { sourceRuntimeId: runtime.id, name });
+        const message = `${name} has been refreshed by ${sourceLabel} and synchronized to the other Codex homes.`;
+        await Promise.allSettled(this.runtimes.map((target) => target.notify?.(message)));
+        return true;
+    }
+    async withActivity(operation) {
+        this.activeOperations += 1;
+        try {
+            return await operation();
+        }
+        finally {
+            this.activeOperations -= 1;
+        }
+    }
+    async ensureCanonicalDefaultCandidate() {
+        const names = await listAuthCandidateNames(this.canonicalDir);
+        if (names.length > 0)
+            return;
+        const authPath = path.join(this.canonicalDir, 'auth.json');
+        if (!(await exists(authPath)))
+            return;
+        const finalPath = await resolveFinalPath(authPath);
+        if (isAuthCandidateName(path.basename(finalPath)))
+            return;
+        await atomicCopy(authPath, path.join(this.canonicalDir, 'auth.json_default'));
+    }
+    async collectCandidateNames() {
+        const all = new Set(await listAuthCandidateNames(this.canonicalDir));
+        for (const runtime of this.runtimes) {
+            for (const name of await listAuthCandidateNames(runtime.authDir)) {
+                all.add(name);
+            }
+        }
+        return [...all];
+    }
+    async reconcileCandidateAtStartup(name) {
+        const paths = [
+            path.join(this.canonicalDir, name),
+            ...this.runtimes.map((runtime) => path.join(runtime.authDir, name)),
+        ];
+        const records = (await Promise.all(paths.map(async (sourcePath) => ({
+            sourcePath,
+            record: await readChatGptAuthRecord(sourcePath),
+        })))).filter((entry) => entry.record !== null);
+        if (records.length === 0)
+            return;
+        const accountIds = new Set(records.map((entry) => entry.record.accountId));
+        if (accountIds.size !== 1) {
+            this.logger.warn('auth.mirror.startup_conflict', { name });
+            return;
+        }
+        const newest = records.reduce((current, entry) => (entry.record.lastRefreshMs > current.record.lastRefreshMs ? entry : current));
+        this.lastSyncedRefresh.set(name, newest.record.lastRefreshMs);
+        for (const destination of paths) {
+            await atomicWrite(destination, newest.record.raw);
+        }
+    }
+    async resolveCanonicalCurrentCandidate() {
+        const finalPath = await resolveFinalPath(path.join(this.canonicalDir, 'auth.json'));
+        const name = path.basename(finalPath);
+        return isAuthCandidateName(name) ? name : null;
+    }
+}
+export function isAuthCandidateName(name) {
+    return name !== 'auth.json'
+        && !name.startsWith('.auth.json.')
+        && (name.startsWith('auth.json_') || name.startsWith('auth.json.') || name.startsWith('auth.json-'));
+}
+async function listAuthCandidateNames(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    return entries
+        .filter((entry) => (entry.isFile() || entry.isSymbolicLink()) && isAuthCandidateName(entry.name))
+        .map((entry) => entry.name);
+}
+async function readChatGptAuthRecord(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const accountId = typeof parsed.tokens?.account_id === 'string' ? parsed.tokens.account_id : '';
+        const lastRefreshMs = typeof parsed.last_refresh === 'string' ? Date.parse(parsed.last_refresh) : NaN;
+        if (!accountId || !Number.isFinite(lastRefreshMs))
+            return null;
+        return { raw, accountId, lastRefreshMs };
+    }
+    catch {
+        return null;
+    }
+}
+async function atomicCopy(source, destination) {
+    await atomicWrite(destination, await fs.readFile(source, 'utf8'));
+}
+async function atomicWrite(destination, contents) {
+    await fs.mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+    const temporary = path.join(path.dirname(destination), `.auth.json.${process.pid}.${Date.now()}.tmp`);
+    await fs.writeFile(temporary, contents, { encoding: 'utf8', mode: 0o600 });
+    await fs.rename(temporary, destination);
+}
+async function pointAuthSymlink(dir, candidateName) {
+    const temporary = path.join(dir, `.auth.json.${process.pid}.${Date.now()}.link`);
+    await fs.symlink(path.join(dir, candidateName), temporary);
+    await fs.rename(temporary, path.join(dir, 'auth.json'));
+}
+async function resolveFinalPath(sourcePath) {
+    try {
+        return await fs.realpath(sourcePath);
+    }
+    catch {
+        return sourcePath;
+    }
+}
+async function exists(filePath) {
+    return fs.lstat(filePath).then(() => true).catch(() => false);
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function readMirrorStatus(statusPath) {
+    if (!statusPath)
+        return null;
+    try {
+        const parsed = JSON.parse(await fs.readFile(statusPath, 'utf8'));
+        if (typeof parsed.candidateName !== 'string'
+            || typeof parsed.sourceRuntimeId !== 'string'
+            || typeof parsed.sourceLabel !== 'string'
+            || typeof parsed.syncedAt !== 'string') {
+            return null;
+        }
+        return {
+            candidateName: parsed.candidateName,
+            sourceRuntimeId: parsed.sourceRuntimeId,
+            sourceLabel: parsed.sourceLabel,
+            syncedAt: parsed.syncedAt,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function writeMirrorStatus(statusPath, status) {
+    if (!statusPath)
+        return;
+    await fs.mkdir(path.dirname(statusPath), { recursive: true, mode: 0o700 });
+    const temporary = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(status, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await fs.rename(temporary, statusPath);
+}

package/dist/codex_app/client.d.ts

@@ -58,6 +58,7 @@ interface CodexAppServerRuntimeStatus {
 interface StopOptions {
     terminateServer?: boolean;
 }
+export declare function buildCodexAppServerArgs(port: number, configOverrides?: readonly string[]): string[];
 export declare class CodexAppClient extends EventEmitter {
     private readonly codexCliBin;
     private readonly launchCommand;
@@ -65,6 +66,8 @@ export declare class CodexAppClient extends EventEmitter {
     private readonly serverStatePath;
     private readonly serverLogPath;
     private readonly logger;
+    private readonly childEnv;
+    private readonly appServerConfigOverrides;
     private child;
     private socket;
     private requestId;
@@ -75,7 +78,7 @@ export declare class CodexAppClient extends EventEmitter {
     private port;
     private connected;
     private userAgent;
-    constructor(codexCliBin: string, launchCommand: string, autolaunch: boolean, serverStatePath: string, serverLogPath: string, logger: Logger);
+    constructor(codexCliBin: string, launchCommand: string, autolaunch: boolean, serverStatePath: string, serverLogPath: string, logger: Logger, childEnv?: NodeJS.ProcessEnv | null, appServerConfigOverrides?: readonly string[]);
     isConnected(): boolean;
     getUserAgent(): string | null;
     getServerStatus(): CodexAppServerRuntimeStatus;

package/dist/codex_app/client.js

@@ -6,6 +6,14 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { buildThreadDeepLink, openUrl } from './deeplink.js';
 const CLIENT_VERSION = readPackageVersion();
+export function buildCodexAppServerArgs(port, configOverrides = []) {
+    const args = ['app-server'];
+    for (const override of configOverrides) {
+        args.push('-c', override);
+    }
+    args.push('--listen', `ws://127.0.0.1:${port}`);
+    return args;
+}
 export class CodexAppClient extends EventEmitter {
     codexCliBin;
     launchCommand;
@@ -13,6 +21,8 @@ export class CodexAppClient extends EventEmitter {
     serverStatePath;
     serverLogPath;
     logger;
+    childEnv;
+    appServerConfigOverrides;
     child = null;
     socket = null;
     requestId = 0;
@@ -23,7 +33,7 @@ export class CodexAppClient extends EventEmitter {
     port = null;
     connected = false;
     userAgent = null;
-    constructor(codexCliBin, launchCommand, autolaunch, serverStatePath, serverLogPath, logger) {
+    constructor(codexCliBin, launchCommand, autolaunch, serverStatePath, serverLogPath, logger, childEnv = null, appServerConfigOverrides = []) {
         super();
         this.codexCliBin = codexCliBin;
         this.launchCommand = launchCommand;
@@ -31,6 +41,8 @@ export class CodexAppClient extends EventEmitter {
         this.serverStatePath = serverStatePath;
         this.serverLogPath = serverLogPath;
         this.logger = logger;
+        this.childEnv = childEnv;
+        this.appServerConfigOverrides = appServerConfigOverrides;
     }
     isConnected() {
         return this.connected;
@@ -463,16 +475,23 @@ export class CodexAppClient extends EventEmitter {
             return;
         }
         if (this.autolaunch) {
-            const launcher = spawn(this.launchCommand, { shell: true, detached: true, stdio: 'ignore' });
+            const launcher = spawn(this.launchCommand, {
+                shell: true,
+                detached: true,
+                stdio: 'ignore',
+                env: this.childEnv ? { ...process.env, ...this.childEnv } : process.env,
+            });
             launcher.unref();
         }
         this.port = await reservePort();
+        const serverArgs = buildCodexAppServerArgs(this.port, this.appServerConfigOverrides);
         const [stdoutFd, stderrFd] = this.openServerLogFiles();
         let child;
         try {
-            child = spawn(this.codexCliBin, ['app-server', '--listen', `ws://127.0.0.1:${this.port}`], {
+            child = spawn(this.codexCliBin, serverArgs, {
                 detached: true,
                 stdio: ['ignore', stdoutFd, stderrFd],
+                env: this.childEnv ? { ...process.env, ...this.childEnv } : process.env,
             });
         }
         finally {
@@ -488,7 +507,7 @@ export class CodexAppClient extends EventEmitter {
         this.writeServerState({
             pid: child.pid,
             port: this.port,
-            command: `${this.codexCliBin} app-server --listen ws://127.0.0.1:${this.port}`,
+            command: [this.codexCliBin, ...serverArgs].join(' '),
             logPath: this.serverLogPath,
             bridgePid: process.pid,
             startedAt: new Date().toISOString(),

package/dist/config.d.ts

@@ -7,12 +7,17 @@ export declare const DEFAULT_LOG_PATH: string;
 export declare const DEFAULT_LOCK_PATH: string;
 export declare const DEFAULT_CODEX_APP_SERVER_STATE_PATH: string;
 export declare const DEFAULT_CODEX_APP_SERVER_LOG_PATH: string;
+export declare const DEFAULT_CODEX_TELEGRAM_HOME: string;
 export declare const DEFAULT_ENV_PATH: string;
 export declare function resolveEnvPath(): string;
 export declare function getLoadedEnvPath(): string | null;
 export declare function loadEnv(): void;
 export interface AppConfig {
     tgBotToken: string;
+    tgBotTokens: string[];
+    tgMultiBotMode: boolean;
+    tgScopeBotId: string | null;
+    tgRequireExplicitGroupAddressing: boolean;
     tgAllowedUserId: string;
     tgAllowedChatId: string | null;
     tgAllowedTopicId: number | null;
@@ -21,6 +26,8 @@ export interface AppConfig {
     codexAppLaunchCmd: string;
     codexAppServerStatePath: string;
     codexAppServerLogPath: string;
+    codexAuthDir: string | null;
+    codexHome: string | null;
     codexAppSyncOnOpen: boolean;
     codexAppSyncOnTurnComplete: boolean;
     storePath: string;

package/dist/config.js

@@ -10,6 +10,7 @@ export const DEFAULT_LOG_PATH = path.join(APP_HOME, 'logs', 'service.log');
 export const DEFAULT_LOCK_PATH = path.join(APP_HOME, 'runtime', 'bridge.lock');
 export const DEFAULT_CODEX_APP_SERVER_STATE_PATH = path.join(APP_HOME, 'runtime', 'codex-app-server.json');
 export const DEFAULT_CODEX_APP_SERVER_LOG_PATH = path.join(APP_HOME, 'logs', 'codex-app-server.log');
+export const DEFAULT_CODEX_TELEGRAM_HOME = path.join(APP_HOME, 'codex', 'telegram');
 export const DEFAULT_ENV_PATH = path.join(APP_HOME, '.env');
 let envLoaded = false;
 let loadedEnvPath = null;
@@ -37,8 +38,22 @@ export function loadEnv() {
 }
 export function loadConfig() {
     loadEnv();
+    const configuredTokens = parseCommaSeparatedIds(process.env.TG_BOT_TOKENS);
+    const legacyToken = optional('TG_BOT_TOKEN');
+    const tgBotTokens = configuredTokens.length > 0
+        ? configuredTokens
+        : legacyToken
+            ? [legacyToken]
+            : [];
+    if (tgBotTokens.length === 0) {
+        throw new Error('TG_BOT_TOKENS or TG_BOT_TOKEN is required');
+    }
     const config = {
-        tgBotToken: required('TG_BOT_TOKEN'),
+        tgBotToken: tgBotTokens[0],
+        tgBotTokens,
+        tgMultiBotMode: configuredTokens.length > 0,
+        tgScopeBotId: null,
+        tgRequireExplicitGroupAddressing: configuredTokens.length > 1,
         tgAllowedUserId: required('TG_ALLOWED_USER_ID'),
         tgAllowedChatId: optional('TG_ALLOWED_CHAT_ID'),
         tgAllowedTopicId: nullableIntEnv('TG_ALLOWED_TOPIC_ID'),
@@ -47,6 +62,8 @@ export function loadConfig() {
         codexAppLaunchCmd: process.env.CODEX_APP_LAUNCH_CMD || 'codex app',
         codexAppServerStatePath: process.env.CODEX_APP_SERVER_STATE_PATH || DEFAULT_CODEX_APP_SERVER_STATE_PATH,
         codexAppServerLogPath: process.env.CODEX_APP_SERVER_LOG_PATH || DEFAULT_CODEX_APP_SERVER_LOG_PATH,
+        codexAuthDir: process.env.CODEX_AUTH_DIR?.trim() || null,
+        codexHome: process.env.CODEX_HOME?.trim() || null,
         codexAppSyncOnOpen: boolEnv('CODEX_APP_SYNC_ON_OPEN', true),
         codexAppSyncOnTurnComplete: boolEnv('CODEX_APP_SYNC_ON_TURN_COMPLETE', false),
         storePath: process.env.STORE_PATH || DEFAULT_STORE_PATH,