@foxden-app/foxclaw 0.4.15 → 0.4.17

package/.env.example

@@ -40,7 +40,9 @@ CODEX_CLI_BIN=/absolute/path/to/codex
 # Optional cross-node Codex auth sync.
 # Disabled by default. When enabled, FoxClaw uses Telegram Bot-to-Bot private
 # messages to move encrypted auth bundles between nodes. Enable Bot-to-Bot
-# Communication Mode for the participating bots in BotFather first.
+# Communication Mode for each node's contact bot in BotFather first.
+# In TG_BOT_TOKENS multi-bot mode, the first token is the default contact bot;
+# put the node's contact token first and list peer contact @usernames below.
 # AUTH_SYNC_ENABLED=true
 # AUTH_SYNC_KEY=<shared-key-with-at-least-32-bytes>
 # AUTH_SYNC_PEERS=@other_node_bot,@third_node_bot

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.4.17 - 2026-06-04
+
+### 中文
+- 明确跨节点 auth 同步推荐架构：每节点一个联系人 bot；多 bot 模式默认使用 `TG_BOT_TOKENS` 的第一个 token 作为联系人，同节点其他 bot 继续走本机 auth 镜像。
+- `/auth sync status` 和 `/status` 现在显示联系人 bot，避免在非联系人 bot 上执行命令时误判实际发包身份。
+- `/auth sync test` 升级为等待 peer 加密 pong 的真实握手，并显示未回应 peer；同时文档补充 BotFather MiniApp 入口、不要误进 Configure Mini App，以及 `push all` 只代表发送成功、不代表对端已导入。
+
+### English
+- Clarified the recommended cross-node auth sync topology: one contact bot per node. In multi-bot mode, the first `TG_BOT_TOKENS` entry is the default contact while other same-node bots keep using local auth mirroring.
+- `/auth sync status` and `/status` now show the contact bot so commands run from a non-contact bot no longer obscure the actual sender identity.
+- `/auth sync test` now waits for encrypted peer pong replies and reports missing peers. Documentation now covers the BotFather MiniApp entry point, avoids the Configure Mini App confusion, and explains that `push all` only proves send success, not peer import.
+
+## 0.4.16 - 2026-06-04
+
+### 中文
+- 新增独立的跨节点 auth 同步中文/英文配置指南，覆盖设计模型、`.env` 配置、`@BotFather` Bot-to-Bot Communication Mode 操作、验证步骤和故障排查。
+- 在 README、README_EN 和用户手册中加入可发现入口，让新用户能从 GitHub/npm 首页一路点到多节点 auth 同步配置说明。
+
+### English
+- Added standalone Chinese and English cross-node auth sync setup guides covering the design model, `.env` config, `@BotFather` Bot-to-Bot Communication Mode steps, verification, and troubleshooting.
+- Linked the guides from README, README_EN, and the user manuals so new users can find multi-node auth sync setup from the GitHub/npm landing page.
+
 ## 0.4.15 - 2026-06-04
 
 ### 中文

package/README.md

@@ -37,6 +37,7 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex，
 - 手头有 Codex、OpenClaw、QwenPaw、Hermes、OpenCode、Kimi CLI 之类能跑 shell 的 agent？推荐走 [Agent 辅助安装](./docs/zh/agent-assisted-install.md)。
 - 对 Node、Telegram 机器人、Codex CLI 不太熟？看 [新手安装指南](./docs/zh/install-for-beginners.md)。
 - 已经装好，想系统了解 `/help`、`/setup`、`/threads`、`/watch`、`/auth` 和账号轮转？看 [用户手册](./docs/zh/user-manual.md)。
+- 想把同一组合法 ChatGPT auth 候选同步到多台机器？看 [跨节点 auth 同步配置指南](./docs/zh/cross-node-auth-sync.md)。
 - 想了解每个版本改了什么？看 [更新日志](./CHANGELOG.md)。
 - Git、Node、`.env` 都玩得转？直接往下看快速设置。
 - 卡住了？看 [故障排查](./docs/zh/troubleshooting.md)。
@@ -211,7 +212,7 @@ TG_BOT_TOKEN=123456:token_a
 
 FoxClaw 仍然只运行一个系统服务。默认情况下，它会为每个 bot 启动独立 `codex app-server` 和独立 `CODEX_HOME`。因此 A 私聊运行 turn 时，B 私聊仍可独立切换自己的 `/auth`。候选凭据由 FoxClaw 在登录或刷新在线验证后镜像同步；切换或重载前还会从其他 Codex home 恢复同账号较新凭据。各 bot 的当前选择互不影响。每个 bot 首次私聊发送 `/help` 和 `/status`；`/auth` 会标明正在操作的 bot runtime，`/status` 会列出全部 bot 的连接、runtime 类型、当前 auth 和活动 turn 摘要。
 
-多台机器共享同一合法账号池时，可以启用可选跨节点 auth 同步：`AUTH_SYNC_ENABLED=true`、`AUTH_SYNC_KEY` 和 `AUTH_SYNC_PEERS=@peer_bot`。FoxClaw 会通过 Telegram Bot-to-Bot 私聊传输加密 auth 包；本机验证刷新后主动 push，发现本机候选失效时主动 pull peer 已持有的有效副本。跨节点恢复不会自动刷新 token，`/auth refresh all confirm` 会先申请跨节点刷新锁。
+多台机器共享同一合法账号池时，可以启用可选跨节点 auth 同步：`AUTH_SYNC_ENABLED=true`、`AUTH_SYNC_KEY` 和 `AUTH_SYNC_PEERS=@peer_contact_bot`。推荐每台机器只选一个联系人 bot；同一节点内的其他 bot 继续走本机 auth 镜像。多 bot 模式下，默认用 `TG_BOT_TOKENS` 的第一个 token 作为联系人 bot。FoxClaw 会通过 Telegram Bot-to-Bot 私聊传输加密 auth 包；本机验证刷新后主动 push，发现本机候选失效时主动 pull peer 已持有的有效副本。跨节点恢复不会自动刷新 token，`/auth refresh all confirm` 会先申请跨节点刷新锁。完整配置、`@BotFather` 操作和验证步骤见 [跨节点 auth 同步配置指南](./docs/zh/cross-node-auth-sync.md)。
 
 如果你需要一路 Telegram 与终端互通 session，把同一个 token 同时填入 `TG_BOT_TOKENS` 和 `TG_BOT_TOKEN`。这个 bot 使用默认 `CODEX_HOME`（未设置时通常是 `~/.codex`）和默认 auth，因此能看到终端 Codex 的本地线程；它不再享有隔离 runtime 的“互不影响”保证，切换 auth 会影响终端和其他默认 runtime。
 

package/README_EN.md

@@ -37,6 +37,7 @@ FoxClaw is more than message forwarding. It provides Telegram panels for Codex w
 - Already have a shell-capable agent such as Codex, OpenClaw, QwenPaw, Hermes, OpenCode, or Kimi CLI? Use the [Agent-Assisted Install](./docs/agent-assisted-install.md) first. This is the recommended path.
 - New to Node, Telegram bots, or Codex CLI? Use the [Beginner Install Guide](./docs/install-for-beginners.md).
 - Already installed and want the full command guide for `/help`, `/setup`, `/threads`, `/watch`, `/auth`, and auth rotation? Read the [User Manual](./docs/user-manual.md).
+- Want to sync the same legally owned ChatGPT auth candidate pool across multiple machines? Read the [Cross-Node Auth Sync Setup Guide](./docs/cross-node-auth-sync.md).
 - Want to see what changed in each release? Read the [Changelog](./CHANGELOG.md).
 - Already comfortable with Git, Node, and `.env` files? Use the quick setup below.
 - Something failed? Check [Troubleshooting](./docs/troubleshooting.md).
@@ -211,7 +212,7 @@ TG_BOT_TOKEN=123456:token_a
 
 FoxClaw remains one system service. By default, it 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 online-validated login or refresh; before switching or reloading, FoxClaw also restores a newer same-account credential from another Codex home when available. 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, runtime type, selected auth, and active turns.
 
-When multiple machines share the same legally owned account pool, optional cross-node auth sync can be enabled with `AUTH_SYNC_ENABLED=true`, `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS=@peer_bot`. FoxClaw sends encrypted auth bundles through Telegram Bot-to-Bot private messages. A locally verified refresh is pushed to peers, and a node with a bad local candidate can pull an already-held valid peer copy. Cross-node recovery never auto-refreshes tokens; `/auth refresh all confirm` first requests a cross-node refresh lease.
+When multiple machines share the same legally owned account pool, optional cross-node auth sync can be enabled with `AUTH_SYNC_ENABLED=true`, `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS=@peer_contact_bot`. The recommended topology is one contact bot per node; other bots on the same node continue to use local auth mirroring. In multi-bot mode, the first token in `TG_BOT_TOKENS` is the default contact bot. FoxClaw sends encrypted auth bundles through Telegram Bot-to-Bot private messages. A locally verified refresh is pushed to peers, and a node with a bad local candidate can pull an already-held valid peer copy. Cross-node recovery never auto-refreshes tokens; `/auth refresh all confirm` first requests a cross-node refresh lease. For full config, `@BotFather` operations, and verification steps, read the [Cross-Node Auth Sync Setup Guide](./docs/cross-node-auth-sync.md).
 
 To keep one Telegram bot interoperable with terminal Codex sessions, put the same token in both `TG_BOT_TOKENS` and `TG_BOT_TOKEN`. That bot uses the default `CODEX_HOME` (usually `~/.codex` when unset) and default auth, so it can see local terminal sessions. It no longer has the isolated runtime guarantee: `/auth` switches also affect the terminal and other default runtimes.
 

package/dist/auth/cross_node_sync.d.ts

@@ -3,6 +3,7 @@ import type { AuthMirrorCandidateRecord, AuthMirrorImportResult } from './mirror
 export interface AuthSyncConfig {
     enabled: boolean;
     transport: 'telegram-private';
+    transportLabel?: string | null;
     key: string | null;
     peers: string[];
     nodeId: string | null;
@@ -18,6 +19,7 @@ export interface AuthSyncStatus {
     enabled: boolean;
     nodeId: string | null;
     transport: 'telegram-private';
+    transportLabel: string | null;
     peers: string[];
     pendingImports: number;
     lastSentAt: string | null;
@@ -51,6 +53,11 @@ export interface AuthSyncLeaseResult {
     leaseId: string | null;
     reason?: string | null;
 }
+export interface AuthSyncTestResult {
+    sent: number;
+    replied: number;
+    missing: string[];
+}
 export declare class CrossNodeAuthSync {
     private readonly config;
     private readonly logger;
@@ -63,6 +70,7 @@ export declare class CrossNodeAuthSync {
     private readonly pendingImports;
     private readonly pendingPulls;
     private readonly pendingLeases;
+    private readonly pendingTests;
     private seenNonces;
     private timer;
     private activeRemoteLease;
@@ -86,9 +94,7 @@ export declare class CrossNodeAuthSync {
     }): Promise<boolean>;
     acquireRefreshLease(reason: string): Promise<AuthSyncLeaseResult>;
     releaseRefreshLease(leaseId: string | null): Promise<void>;
-    testPeers(): Promise<{
-        sent: number;
-    }>;
+    testPeers(): Promise<AuthSyncTestResult>;
     handleIncomingEnvelope(rawEnvelope: string, peer: AuthSyncPeerIdentity): Promise<boolean>;
     private handleMessage;
     private handlePullRequest;
@@ -101,10 +107,13 @@ export declare class CrossNodeAuthSync {
     private validateAndImport;
     private sendToAll;
     private sendToPeer;
+    private handleTestPong;
+    private finishPendingTest;
     private sealEnvelope;
     private openEnvelope;
     private isReady;
     private isAllowedPeer;
+    private matchConfiguredPeer;
     private expireLeases;
     private recordError;
     private writeState;

package/dist/auth/cross_node_sync.js

@@ -6,6 +6,7 @@ import { isAuthCandidateName, parseChatGptAuthMetadata } from './mirror.js';
 const ENVELOPE_MAGIC = 'foxclaw-auth-sync';
 const NONCE_RETENTION_MS = 7 * 24 * 60 * 60_000;
 const PULL_TIMEOUT_MS = 12_000;
+const TEST_TIMEOUT_MS = 8_000;
 const LEASE_TIMEOUT_MS = 8_000;
 const LEASE_TTL_MS = 60_000;
 const REMOTE_ACCESS_TOKEN_MIN_TTL_MS = 60_000;
@@ -21,6 +22,7 @@ export class CrossNodeAuthSync {
     pendingImports = [];
     pendingPulls = new Map();
     pendingLeases = new Map();
+    pendingTests = new Map();
     seenNonces = new Map();
     timer = null;
     activeRemoteLease = null;
@@ -89,6 +91,7 @@ export class CrossNodeAuthSync {
             enabled: this.config.enabled,
             nodeId: this.nodeId,
             transport: this.config.transport,
+            transportLabel: this.config.transportLabel?.trim() || null,
             peers: this.peers,
             pendingImports: this.pendingImports.length,
             lastSentAt: this.state.lastSentAt,
@@ -104,7 +107,8 @@ export class CrossNodeAuthSync {
     isIdle() {
         return this.pendingImports.length === 0
             && this.pendingPulls.size === 0
-            && this.pendingLeases.size === 0;
+            && this.pendingLeases.size === 0
+            && this.pendingTests.size === 0;
     }
     async publishCandidate(candidateName) {
         if (!this.isReady())
@@ -240,9 +244,37 @@ export class CrossNodeAuthSync {
     }
     async testPeers() {
         if (!this.isReady())
-            return { sent: 0 };
-        await this.sendToAll({ kind: 'test.ping', requestId: crypto.randomUUID() });
-        return { sent: this.peers.length };
+            return { sent: 0, replied: 0, missing: [] };
+        const requestId = crypto.randomUUID();
+        const peers = [...this.peers];
+        const resultPromise = new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.finishPendingTest(requestId);
+            }, TEST_TIMEOUT_MS);
+            timer.unref();
+            this.pendingTests.set(requestId, {
+                peers,
+                replies: new Set(),
+                resolve,
+                timer,
+                finished: false,
+            });
+        });
+        try {
+            await this.sendToAll({ kind: 'test.ping', requestId });
+        }
+        catch (error) {
+            const pending = this.pendingTests.get(requestId);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingTests.delete(requestId);
+            }
+            throw error;
+        }
+        if (peers.length === 0) {
+            this.finishPendingTest(requestId);
+        }
+        return resultPromise;
     }
     async handleIncomingEnvelope(rawEnvelope, peer) {
         if (!this.isReady() || !this.isAllowedPeer(peer)) {
@@ -285,6 +317,7 @@ export class CrossNodeAuthSync {
                 });
                 return;
             case 'test.pong':
+                this.handleTestPong(message.requestId, normalizePeerIdentity(peer));
                 this.logger.info('auth.sync.test_pong', { peer: normalizePeerIdentity(peer), nodeId: message.nodeId });
                 return;
             case 'lease.request':
@@ -462,8 +495,35 @@ export class CrossNodeAuthSync {
         const envelope = this.sealEnvelope(message);
         await this.transport.send(peer, envelope);
         this.state.lastSentAt = new Date().toISOString();
+        if (this.state.lastError?.includes('USER_BOT_TO_BOT_DISABLED')) {
+            this.state.lastError = null;
+        }
         await this.writeState();
     }
+    handleTestPong(requestId, peer) {
+        const pending = this.pendingTests.get(requestId);
+        if (!pending || pending.finished)
+            return;
+        const matchedPeer = this.matchConfiguredPeer(peer) ?? peer;
+        pending.replies.add(matchedPeer);
+        if (pending.peers.every(peerName => pending.replies.has(peerName))) {
+            this.finishPendingTest(requestId);
+        }
+    }
+    finishPendingTest(requestId) {
+        const pending = this.pendingTests.get(requestId);
+        if (!pending || pending.finished)
+            return;
+        pending.finished = true;
+        clearTimeout(pending.timer);
+        this.pendingTests.delete(requestId);
+        const missing = pending.peers.filter(peer => !pending.replies.has(peer));
+        pending.resolve({
+            sent: pending.peers.length,
+            replied: pending.replies.size,
+            missing,
+        });
+    }
     sealEnvelope(message) {
         if (!this.key || !this.nodeId) {
             throw new Error('auth sync is not initialized');
@@ -528,6 +588,10 @@ export class CrossNodeAuthSync {
         ];
         return keys.some(key => this.peerKeys.has(key));
     }
+    matchConfiguredPeer(peer) {
+        const keys = new Set(expandPeerKeys(peer));
+        return this.peers.find(configuredPeer => expandPeerKeys(configuredPeer).some(key => keys.has(key))) ?? null;
+    }
     expireLeases() {
         const now = Date.now();
         if (this.activeRemoteLease && this.activeRemoteLease.expiresAt <= now) {

package/dist/controller/controller.d.ts

@@ -23,6 +23,8 @@ export interface CoreCoordinator {
     }>;
     authSyncTest?: () => Promise<{
         sent: number;
+        replied: number;
+        missing: string[];
     }>;
     statusUpdated?: (status: RuntimeStatus) => void;
     getServiceStatus?: () => Promise<{

package/dist/controller/controller.js

@@ -430,6 +430,7 @@ export class BridgeSessionCore {
                     if (serviceStatus.authSync?.enabled) {
                         lines.push(t(locale, 'status_auth_sync', {
                             node: serviceStatus.authSync.nodeId ?? t(locale, 'unknown'),
+                            contact: serviceStatus.authSync.transportLabel ?? t(locale, 'unknown'),
                             peers: serviceStatus.authSync.peers.length,
                             pending: serviceStatus.authSync.pendingImports,
                         }));
@@ -4009,7 +4010,11 @@ export class BridgeSessionCore {
                 await this.sendMessage(scopeId, t(locale, 'auth_sync_disabled'));
                 return;
             }
-            await this.sendMessage(scopeId, t(locale, 'auth_sync_test_sent', { count: result.sent }));
+            const message = [
+                t(locale, 'auth_sync_test_sent', { sent: result.sent, replied: result.replied }),
+                ...(result.missing.length > 0 ? [t(locale, 'auth_sync_test_missing', { value: result.missing.join(', ') })] : []),
+            ].join('\n');
+            await this.sendMessage(scopeId, message);
             return;
         }
         if (action === 'push' && args[1]?.toLowerCase() === 'all') {
@@ -8117,6 +8122,7 @@ function formatAuthSyncStatus(locale, status) {
     const lines = [
         t(locale, 'auth_sync_status_title'),
         t(locale, 'auth_sync_status_node', { value: status.nodeId ?? t(locale, 'unknown') }),
+        t(locale, 'auth_sync_status_transport', { value: status.transportLabel ?? t(locale, 'unknown') }),
         t(locale, 'auth_sync_status_peers', { value: status.peers.length === 0 ? t(locale, 'none') : status.peers.join(', ') }),
         t(locale, 'auth_sync_status_pending', { value: status.pendingImports }),
         t(locale, 'auth_sync_status_sent', { value: status.lastSentAt ?? t(locale, 'none') }),

package/dist/i18n.d.ts

@@ -125,7 +125,7 @@ declare const MESSAGES: {
         readonly status_runtime_weixin: "- Weixin default runtime: connected {connected}, active turns {turns}";
         readonly status_auth_mirror_none: "Last auth mirror: none recorded";
         readonly status_auth_mirror_synced: "Last auth mirror: {candidate} from {source} at {time}";
-        readonly status_auth_sync: "Cross-node auth sync: node {node}, peers {peers}, pending imports {pending}";
+        readonly status_auth_sync: "Cross-node auth sync: node {node}, contact {contact}, peers {peers}, pending imports {pending}";
         readonly status_auth_sync_error: "Cross-node auth sync error: {value}";
         readonly status_last_update_none: "Last service update: none recorded";
         readonly status_last_update: "Last service update: {from} -> {to} at {time}";
@@ -203,11 +203,13 @@ declare const MESSAGES: {
         readonly auth_add_reverted: "Restored previous auth.";
         readonly auth_add_missing_file: "Login completed, but the new auth file was not created: {value}";
         readonly auth_sync_disabled: "Cross-node auth sync is disabled.";
-        readonly auth_sync_test_sent: "Auth sync test ping sent to {count} peer(s).";
+        readonly auth_sync_test_sent: "Auth sync test complete: sent {sent}, replies {replied}.";
+        readonly auth_sync_test_missing: "Missing replies: {value}";
         readonly auth_sync_push_blocked_active: "Cannot push auth sync while any runtime, approval, input, login, or auth mirror write is active.";
         readonly auth_sync_push_done: "Auth sync push complete: sent {sent}, skipped {skipped}.";
         readonly auth_sync_status_title: "Cross-node auth sync:";
         readonly auth_sync_status_node: "Node: {value}";
+        readonly auth_sync_status_transport: "Contact bot: {value}";
         readonly auth_sync_status_peers: "Peers: {value}";
         readonly auth_sync_status_pending: "Pending imports: {value}";
         readonly auth_sync_status_sent: "Last sent: {value}";
@@ -750,7 +752,7 @@ declare const MESSAGES: {
         readonly status_runtime_weixin: "- 微信默认运行时：连接 {connected}，进行中回复 {turns}";
         readonly status_auth_mirror_none: "最近 auth 镜像：暂无记录";
         readonly status_auth_mirror_synced: "最近 auth 镜像：{candidate} 由 {source} 于 {time} 同步";
-        readonly status_auth_sync: "跨节点 auth 同步：节点 {node}，peer {peers}，待导入 {pending}";
+        readonly status_auth_sync: "跨节点 auth 同步：节点 {node}，联系人 {contact}，peer {peers}，待导入 {pending}";
         readonly status_auth_sync_error: "跨节点 auth 同步错误：{value}";
         readonly status_last_update_none: "最近服务升级：暂无记录";
         readonly status_last_update: "最近服务升级：{from} -> {to}（{time}）";
@@ -828,11 +830,13 @@ declare const MESSAGES: {
         readonly auth_add_reverted: "已恢复之前的 auth。";
         readonly auth_add_missing_file: "登录已完成，但没有创建新的 auth 文件：{value}";
         readonly auth_sync_disabled: "跨节点 auth 同步未启用。";
-        readonly auth_sync_test_sent: "已向 {count} 个 peer 发送 auth sync 测试 ping。";
+        readonly auth_sync_test_sent: "auth sync 测试完成：已发送 {sent}，收到回应 {replied}。";
+        readonly auth_sync_test_missing: "未回应：{value}";
         readonly auth_sync_push_blocked_active: "当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能推送 auth 同步。";
         readonly auth_sync_push_done: "auth 同步推送完成：已发送 {sent}，已跳过 {skipped}。";
         readonly auth_sync_status_title: "跨节点 auth 同步：";
         readonly auth_sync_status_node: "节点：{value}";
+        readonly auth_sync_status_transport: "联系人 bot：{value}";
         readonly auth_sync_status_peers: "Peer：{value}";
         readonly auth_sync_status_pending: "待导入：{value}";
         readonly auth_sync_status_sent: "最近发送：{value}";

package/dist/i18n.js

@@ -123,7 +123,7 @@ const MESSAGES = {
         status_runtime_weixin: '- Weixin default runtime: connected {connected}, active turns {turns}',
         status_auth_mirror_none: 'Last auth mirror: none recorded',
         status_auth_mirror_synced: 'Last auth mirror: {candidate} from {source} at {time}',
-        status_auth_sync: 'Cross-node auth sync: node {node}, peers {peers}, pending imports {pending}',
+        status_auth_sync: 'Cross-node auth sync: node {node}, contact {contact}, peers {peers}, pending imports {pending}',
         status_auth_sync_error: 'Cross-node auth sync error: {value}',
         status_last_update_none: 'Last service update: none recorded',
         status_last_update: 'Last service update: {from} -> {to} at {time}',
@@ -201,11 +201,13 @@ const MESSAGES = {
         auth_add_reverted: 'Restored previous auth.',
         auth_add_missing_file: 'Login completed, but the new auth file was not created: {value}',
         auth_sync_disabled: 'Cross-node auth sync is disabled.',
-        auth_sync_test_sent: 'Auth sync test ping sent to {count} peer(s).',
+        auth_sync_test_sent: 'Auth sync test complete: sent {sent}, replies {replied}.',
+        auth_sync_test_missing: 'Missing replies: {value}',
         auth_sync_push_blocked_active: 'Cannot push auth sync while any runtime, approval, input, login, or auth mirror write is active.',
         auth_sync_push_done: 'Auth sync push complete: sent {sent}, skipped {skipped}.',
         auth_sync_status_title: 'Cross-node auth sync:',
         auth_sync_status_node: 'Node: {value}',
+        auth_sync_status_transport: 'Contact bot: {value}',
         auth_sync_status_peers: 'Peers: {value}',
         auth_sync_status_pending: 'Pending imports: {value}',
         auth_sync_status_sent: 'Last sent: {value}',
@@ -748,7 +750,7 @@ const MESSAGES = {
         status_runtime_weixin: '- 微信默认运行时：连接 {connected}，进行中回复 {turns}',
         status_auth_mirror_none: '最近 auth 镜像：暂无记录',
         status_auth_mirror_synced: '最近 auth 镜像：{candidate} 由 {source} 于 {time} 同步',
-        status_auth_sync: '跨节点 auth 同步：节点 {node}，peer {peers}，待导入 {pending}',
+        status_auth_sync: '跨节点 auth 同步：节点 {node}，联系人 {contact}，peer {peers}，待导入 {pending}',
         status_auth_sync_error: '跨节点 auth 同步错误：{value}',
         status_last_update_none: '最近服务升级：暂无记录',
         status_last_update: '最近服务升级：{from} -> {to}（{time}）',
@@ -826,11 +828,13 @@ const MESSAGES = {
         auth_add_reverted: '已恢复之前的 auth。',
         auth_add_missing_file: '登录已完成，但没有创建新的 auth 文件：{value}',
         auth_sync_disabled: '跨节点 auth 同步未启用。',
-        auth_sync_test_sent: '已向 {count} 个 peer 发送 auth sync 测试 ping。',
+        auth_sync_test_sent: 'auth sync 测试完成：已发送 {sent}，收到回应 {replied}。',
+        auth_sync_test_missing: '未回应：{value}',
         auth_sync_push_blocked_active: '当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能推送 auth 同步。',
         auth_sync_push_done: 'auth 同步推送完成：已发送 {sent}，已跳过 {skipped}。',
         auth_sync_status_title: '跨节点 auth 同步：',
         auth_sync_status_node: '节点：{value}',
+        auth_sync_status_transport: '联系人 bot：{value}',
         auth_sync_status_peers: 'Peer：{value}',
         auth_sync_status_pending: '待导入：{value}',
         auth_sync_status_sent: '最近发送：{value}',

package/dist/main.js

@@ -305,7 +305,7 @@ async function runServeCli() {
                     ?? Promise.resolve(),
                 getAuthSyncStatus: () => authSync?.getStatus() ?? null,
                 authSyncPushAll: () => authSync?.pushAll() ?? Promise.resolve({ sent: 0, skipped: 0 }),
-                authSyncTest: () => authSync?.testPeers() ?? Promise.resolve({ sent: 0 }),
+                authSyncTest: () => authSync?.testPeers() ?? Promise.resolve({ sent: 0, replied: 0, missing: [] }),
                 statusUpdated: () => writeAggregateStatus(),
                 getServiceStatus: async () => ({
                     bots: await Promise.all(runtimes.map(async (runtime) => {
@@ -352,9 +352,13 @@ async function runServeCli() {
             }
             activeTelegramAdapters = runtimes.map((runtime) => runtime.telegram);
             if (config.authSyncEnabled) {
-                authSync = new CrossNodeAuthSync(buildAuthSyncConfig(config), logger, {
+                const authSyncTransportBot = seeds[0];
+                const authSyncTransportLabel = authSyncTransportBot.bot.username
+                    ? `@${authSyncTransportBot.bot.username}`
+                    : authSyncTransportBot.id;
+                authSync = new CrossNodeAuthSync(buildAuthSyncConfig(config, authSyncTransportLabel), logger, {
                     send: async (peer, envelope) => {
-                        await seeds[0].bot.sendDocument(peer, `foxclaw-auth-sync-${Date.now()}.json`, Buffer.from(envelope, 'utf8'), 'FOXCLAW_AUTH_SYNC_V1');
+                        await authSyncTransportBot.bot.sendDocument(peer, `foxclaw-auth-sync-${Date.now()}.json`, Buffer.from(envelope, 'utf8'), 'FOXCLAW_AUTH_SYNC_V1');
                     },
                 }, {
                     readLocalCandidate: (candidateName) => mirror.readNewestCandidate(candidateName),
@@ -374,7 +378,7 @@ async function runServeCli() {
                 });
                 await authSync.initialize();
                 activeAuthSync = authSync;
-                attachTelegramAuthSync(seeds[0].bot, authSync, config, logger);
+                attachTelegramAuthSync(authSyncTransportBot.bot, authSync, config, logger);
                 authSync.start();
             }
             mirror.start();
@@ -455,7 +459,7 @@ async function runServeCli() {
                 ?? Promise.resolve(),
             getAuthSyncStatus: () => singleAuthSync?.getStatus() ?? null,
             authSyncPushAll: () => singleAuthSync?.pushAll() ?? Promise.resolve({ sent: 0, skipped: 0 }),
-            authSyncTest: () => singleAuthSync?.testPeers() ?? Promise.resolve({ sent: 0 }),
+            authSyncTest: () => singleAuthSync?.testPeers() ?? Promise.resolve({ sent: 0, replied: 0, missing: [] }),
             statusUpdated: (status) => {
                 writeRuntimeStatus(config.statusPath, {
                     ...status,
@@ -484,7 +488,7 @@ async function runServeCli() {
         }
         core = new BridgeSessionCore(config, store, logger, bot, app, outbound, selfUpdater, singleCoordinator);
         if (config.authSyncEnabled && singleMirror) {
-            singleAuthSync = new CrossNodeAuthSync(buildAuthSyncConfig(config), logger, {
+            singleAuthSync = new CrossNodeAuthSync(buildAuthSyncConfig(config, bot.username ? `@${bot.username}` : 'default'), logger, {
                 send: async (peer, envelope) => {
                     await bot.sendDocument(peer, `foxclaw-auth-sync-${Date.now()}.json`, Buffer.from(envelope, 'utf8'), 'FOXCLAW_AUTH_SYNC_V1');
                 },
@@ -566,10 +570,11 @@ async function runServeCli() {
     }
 }
 const AUTH_SYNC_TELEGRAM_CAPTION = 'FOXCLAW_AUTH_SYNC_V1';
-function buildAuthSyncConfig(config) {
+function buildAuthSyncConfig(config, transportLabel = null) {
     return {
         enabled: config.authSyncEnabled,
         transport: config.authSyncTransport,
+        transportLabel,
         key: config.authSyncKey,
         peers: config.authSyncPeers,
         nodeId: config.authSyncNodeId,

package/dist/types.d.ts

@@ -363,6 +363,7 @@ export interface RuntimeStatus {
     authSync?: {
         enabled: boolean;
         nodeId: string | null;
+        transportLabel: string | null;
         peers: string[];
         pendingImports: number;
         lastSentAt: string | null;

package/docs/cross-node-auth-sync.md

@@ -0,0 +1,195 @@
+# Cross-Node Auth Sync Setup Guide
+
+This guide is for multiple machines you control that share the same legally owned ChatGPT auth candidate pool. It extends same-host auth mirroring across machines: when Codex refreshes a token on one node, FoxClaw can send an encrypted auth bundle to peer nodes through Telegram Bot-to-Bot private messages; when one node finds a local candidate unusable, it can pull an already-held valid peer copy.
+
+The feature is disabled by default. It does not require a public IP, FRP, or reverse proxy, but it requires Telegram Bot-to-Bot Communication Mode.
+
+## Scope
+
+Use it when:
+
+- You legally own and maintain the ChatGPT accounts and auth files.
+- Multiple machines run FoxClaw, and each machine has at least one Telegram bot.
+- You want auth files to stay fresh across nodes without routinely rotating refresh tokens.
+- The recommended default is one contact bot per node for cross-node sync. Other bots on the same node continue to use local auth mirroring.
+
+Do not use it when:
+
+- The auth source is untrusted, account ownership is unclear, or you do not control every machine administrator.
+- You plan to use `/auth refresh all` as a refresh-token keepalive.
+- The same bot token is being polled by multiple machines at the same time. That breaks Telegram update delivery and FoxClaw's assumptions.
+
+## Design And Safety Model
+
+Cross-node sync combines three active paths:
+
+- **Push**: after local login, Codex automatic refresh, or `/auth refresh all confirm` succeeds and passes usage validation, FoxClaw sends the newer candidate to peers.
+- **Pull**: before auth switch or reload, FoxClaw first searches local runtimes for a newer candidate. If none exists, it asks peers for a newer same-name, same-account candidate.
+- **Lease**: before `/auth refresh all confirm` rotates refresh tokens, FoxClaw requests a cross-node refresh lease. Any busy, denying, or non-responsive peer blocks the refresh.
+
+Safety boundaries:
+
+- Telegram only carries ciphertext. Candidate contents, candidate names, account ids, and `last_refresh` are inside an AES-256-GCM payload.
+- FoxClaw only accepts sync files from bots listed in `AUTH_SYNC_PEERS`.
+- Wrong `AUTH_SYNC_KEY`, cluster, nonce, or payload validation never writes files.
+- Remote imports wait for global local idleness, then run temporary usage validation before writing a candidate.
+- A same-name candidate known to belong to a different account id is never overwritten.
+- Sync packets do not create reply chains. FoxClaw filters by packet type, nonce, and peer allowlist to avoid bot-to-bot loops.
+
+Telegram's official Bot Features documentation says private bot-to-bot messaging requires Bot-to-Bot Communication Mode on both sender and recipient, and it calls out loop-prevention requirements. See https://core.telegram.org/bots/features#bot-to-bot-communication
+
+## Before You Configure
+
+Assume two machines:
+
+- Node A: bot `@foxclaw_node_a_bot`
+- Node B: bot `@foxclaw_node_b_bot`
+
+These are the two node contact bots. `AUTH_SYNC_PEERS` only needs peer node contact bots; you do not need to list every bot running on the same machine. In multi-bot mode, FoxClaw uses the first token in `TG_BOT_TOKENS` as the local contact bot by default. If you want bot 5 to be the contact, put bot 5's token first, or enable Bot-to-Bot for every local bot as a temporary fallback.
+
+Each node should already work independently:
+
+```bash
+foxclaw doctor
+foxclaw start
+```
+
+In a private Telegram chat with each bot, verify:
+
+```text
+/status
+/auth
+```
+
+## Enable Bot-to-Bot In @BotFather
+
+Repeat this for every participating bot:
+
+1. Prefer the latest Telegram mobile client; some desktop or older clients do not show the setting.
+2. Open `https://t.me/BotFather?startapp`, or open the `@BotFather` profile and tap **Open App**.
+3. In the BotFather MiniApp, select the contact bot that will participate in auth sync.
+4. Open Settings / Bot Settings.
+5. Find **Bot-to-Bot Communication Mode**.
+6. Enable it.
+7. Repeat for every node contact bot.
+
+Do not use `/mybots` → Bot Settings → **Configure Mini App**. That configures your bot's Mini App URL, not Bot-to-Bot Communication Mode.
+
+Private cross-node sync requires this mode on both bots. Enabling it on only one side is usually not enough for two bots to exchange private sync packets.
+
+If you see `Bad Request: USER_BOT_TO_BOT_DISABLED`, first confirm that both the sender contact bot and recipient contact bot have Bot-to-Bot enabled. In multi-bot mode, the sender contact is the first token in `TG_BOT_TOKENS` by default; it may not be the bot where you typed the command.
+
+## .env Configuration
+
+Use the same `AUTH_SYNC_KEY` and `AUTH_SYNC_CLUSTER_ID` on all nodes, but give each node a different `AUTH_SYNC_NODE_ID`.
+
+Node A:
+
+```dotenv
+TG_BOT_TOKENS=<node-a-contact-token>,<node-a-other-bot-token>
+AUTH_SYNC_ENABLED=true
+AUTH_SYNC_KEY=<shared key with at least 32 bytes>
+AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
+AUTH_SYNC_NODE_ID=workstation-a
+AUTH_SYNC_PEERS=@foxclaw_node_b_bot
+```
+
+Node B:
+
+```dotenv
+TG_BOT_TOKENS=<node-b-contact-token>,<node-b-other-bot-token>
+AUTH_SYNC_ENABLED=true
+AUTH_SYNC_KEY=<shared key with at least 32 bytes>
+AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
+AUTH_SYNC_NODE_ID=workstation-b
+AUTH_SYNC_PEERS=@foxclaw_node_a_bot
+```
+
+For more peers, separate bot usernames with commas:
+
+```dotenv
+AUTH_SYNC_PEERS=@foxclaw_node_a_bot,@foxclaw_node_b_bot,@foxclaw_node_c_bot
+```
+
+Generate a shared key with a password manager or `openssl`:
+
+```bash
+openssl rand -base64 32
+```
+
+Restart FoxClaw on every node after editing config:
+
+```bash
+foxclaw restart
+```
+
+## Verification
+
+1. In each node's bot private chat, run:
+
+```text
+/auth sync status
+```
+
+You should see the node id, peer list, and pending imports.
+
+2. On node A, run:
+
+```text
+/auth sync test
+```
+
+Node A should report that it sent a test ping. Node B's `/auth sync status` should show a recent receive or test-state change.
+
+Starting in 0.4.17, `/auth sync test` waits for an encrypted pong from peers. A healthy result looks like:
+
+```text
+Auth sync test complete: sent 1, replies 1.
+```
+
+If it shows `Missing replies: @peer_bot`, Telegram delivery may have succeeded, but the peer did not receive, decrypt, pass allowlist validation, or run the same auth sync configuration.
+
+3. Use a low-risk candidate for the first broadcast. Make sure every runtime is idle, then run on node A:
+
+```text
+/auth sync push all
+```
+
+4. On node B, run:
+
+```text
+/auth sync status
+/auth
+```
+
+Confirm that pending imports were processed, or that the candidate exists or has a newer timestamp.
+
+Note: `/auth sync push all` saying “sent” only means this node successfully handed encrypted packages to Telegram. It does not prove the peer wrote files. The peer imports only when it is globally idle, usage validation succeeds, same-name candidates belong to the same account id, and the remote `last_refresh` is newer than the local copy. If the local file is already equal or newer, it will not change and `Last import` may remain empty.
+
+5. Only test refresh-token rotation after you understand the risk:
+
+```text
+/auth refresh all
+/auth refresh all confirm
+```
+
+With cross-node sync enabled, this command first requests a cross-node refresh lease. Any busy, denying, or timed-out peer blocks refresh.
+
+## Troubleshooting
+
+**`/auth sync test` does nothing**
+
+- Confirm both bots have Bot-to-Bot Communication Mode enabled in `@BotFather`.
+- Confirm `AUTH_SYNC_PEERS` contains peer `@username` values, not tokens.
+- Confirm `AUTH_SYNC_KEY` and `AUTH_SYNC_CLUSTER_ID` match exactly on both sides.
+- Confirm both nodes were restarted after config changes.
+
+**A sync packet arrived but no candidate was written**
+
+- The local node may not be globally idle. Active turns, approvals, inputs, login flows, and mirror writes make imports wait.
+- Usage validation failure rejects the write.
+- Same-name candidates from different account ids are refused.
+
+**Should I periodically run `/auth refresh all confirm` as keepalive?**
+
+No. Codex refreshes automatically when access tokens expire. Cross-node auth sync propagates auth files that have already refreshed successfully; Refresh all should remain a maintenance command, not a routine keepalive.

package/docs/user-manual.md

@@ -419,7 +419,19 @@ OpenAI does not publish a fixed ChatGPT refresh-token lifetime or an old-token r
 
 ### 6.4 Cross-Node Auth Sync
 
-Cross-node auth sync is disabled by default. It is for multiple machines you control that share the same legally owned ChatGPT auth candidate pool, so a token refreshed by Codex on one node can be copied to the others. v1 uses Telegram Bot-to-Bot private messages to carry encrypted files, so it does not require public IPs or FRP. Enable Bot-to-Bot Communication Mode for the participating bots in BotFather first.
+Cross-node auth sync is disabled by default. It is for multiple machines you control that share the same legally owned ChatGPT auth candidate pool, so a token refreshed by Codex on one node can be copied to the others. v1 uses Telegram Bot-to-Bot private messages to carry encrypted files, so it does not require public IPs or FRP. The recommended default is one contact bot per node; other bots on the same node keep using local auth mirroring. In multi-bot mode, the default contact is the first token in `TG_BOT_TOKENS`.
+
+For the full design, safety boundaries, `.env` examples, and troubleshooting, read the [Cross-Node Auth Sync Setup Guide](./cross-node-auth-sync.md).
+
+In `@BotFather`, repeat this for every participating bot:
+
+1. Use the latest Telegram mobile client to open `https://t.me/BotFather?startapp`, or open the `@BotFather` profile and tap **Open App**.
+2. In the BotFather MiniApp, select the contact bot that will participate in sync.
+3. Open Settings / Bot Settings.
+4. Find and enable **Bot-to-Bot Communication Mode**.
+5. Repeat for every node contact bot; private sync requires this mode on both sender and recipient.
+
+Do not use `/mybots` → Bot Settings → **Configure Mini App**. That configures your bot's Mini App URL, not Bot-to-Bot Communication Mode.
 
 Example:
 
@@ -449,8 +461,8 @@ Dual-active behavior:
 Commands:
 
 - `/auth sync status`: show node id, peers, recent sends/receives/imports, pending imports, and the latest error.
-- `/auth sync test`: send an encrypted ping to verify peer config, shared key, and Bot-to-Bot private messages.
-- `/auth sync push all`: manually broadcast all locally verified candidates without refreshing tokens.
+- `/auth sync test`: send an encrypted ping and wait for peer pong replies to verify peer config, shared key, and Bot-to-Bot private messages.
+- `/auth sync push all`: manually broadcast all locally verified candidates without refreshing tokens. “Sent” does not mean the peer imported files; check `/auth sync status` and `/auth` on the peer.
 
 Equivalent commands:
 
@@ -467,7 +479,7 @@ Equivalent commands:
 
 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
+### 6.5 How Auto-Rotation Works
 
 When Codex reports a usage limit, missing login, expired auth, or similar auth error, FoxClaw tries to rotate automatically:
 
@@ -511,4 +523,5 @@ auth.json_backup       # backup account, enable or disable as needed
 
 - [Beginner Install Guide](./install-for-beginners.md)
 - [Agent-Assisted Install](./agent-assisted-install.md)
+- [Cross-Node Auth Sync Setup Guide](./cross-node-auth-sync.md)
 - [Troubleshooting](./troubleshooting.md)

package/docs/zh/cross-node-auth-sync.md

@@ -0,0 +1,195 @@
+# 跨节点 auth 同步配置指南
+
+本指南面向“多台自己控制的机器使用同一组合法 ChatGPT auth 候选”的场景。它把同一节点内的 auth 镜像扩展到跨机器：某台机器上的 Codex 自动刷新出新 token 后，FoxClaw 可以通过 Telegram Bot-to-Bot 私聊把加密 auth 包同步给其他节点；某台机器发现本地候选不可用时，也可以向 peer 拉取它已经持有的有效副本。
+
+这个功能默认关闭。它不需要公网 IP、FRP 或反向代理，但需要 Telegram Bot-to-Bot Communication Mode。
+
+## 适用边界
+
+适合：
+
+- 这些 ChatGPT 账号和 auth 文件都由你合法拥有和维护。
+- 多台机器都运行 FoxClaw，并且每台机器至少有一个 Telegram bot。
+- 你希望 auth 文件在节点间自动保持较新，但不希望日常主动旋转 refresh token。
+- 默认推荐每台机器只选择一个“联系人 bot”参与跨节点同步；同一节点内其他 bot 继续使用原本的本机 auth 镜像。
+
+不适合：
+
+- 同步来源不可信、账号来源不合法，或你无法确认每台机器的管理员。
+- 希望用 `/auth refresh all` 当作 refresh token 保活工具。
+- 同一个 bot token 被多台机器同时 polling；这会破坏 Telegram update 分发和 FoxClaw 的运行假设。
+
+## 设计与安全模型
+
+跨节点同步使用“主动 push + 主动 pull + 跨节点刷新锁”三段互补：
+
+- **Push**：本节点登录、Codex 自动刷新或 `/auth refresh all confirm` 成功并通过本机 usage 验证后，把较新的候选加密发送给 peer。
+- **Pull**：本节点切换或重载 auth 前，如果本机其他 runtime 没有更新副本，会向 peer 请求同名、同账号的较新候选。
+- **Lease**：执行会旋转 refresh token 的 `/auth refresh all confirm` 前，先向 peer 申请跨节点刷新锁；任一 peer 忙碌、拒绝或无响应都会阻止刷新。
+
+安全边界：
+
+- Telegram 只承载密文。候选文件内容、候选名、account id 和 `last_refresh` 都在 AES-256-GCM payload 内。
+- 只接收 `AUTH_SYNC_PEERS` 中列出的 peer bot 发来的同步文件。
+- `AUTH_SYNC_KEY`、cluster、nonce 或 payload 校验失败时不会写盘。
+- 远端导入必须等本机全局空闲，再临时验证 usage；验证成功后才写入候选。
+- 同名候选如果已知属于不同 account id，永远拒绝覆盖。
+- 同步包不会触发自动回复链路；FoxClaw 对包类型、nonce 和 peer allowlist 做过滤，避免 bot-to-bot 循环。
+
+Telegram 官方 Bot Features 文档说明：私聊 bot-to-bot 需要发送方和接收方都启用 Bot-to-Bot Communication Mode，并提醒开发者处理 loop prevention。参考：https://core.telegram.org/bots/features#bot-to-bot-communication
+
+## 配置前准备
+
+假设有两台机器：
+
+- 节点 A：bot `@foxclaw_node_a_bot`
+- 节点 B：bot `@foxclaw_node_b_bot`
+
+这两个 bot 就是两个节点的联系人。`AUTH_SYNC_PEERS` 只需要写 peer 节点的联系人 bot，不需要把同一台机器上的所有 bot 都互相列进去。多 bot 模式下，FoxClaw 默认使用 `TG_BOT_TOKENS` 里的第一个 token 作为本节点联系人；如果你希望 5 号 bot 当联系人，就把 5 号 token 放到 `TG_BOT_TOKENS` 第一位，或者给全部 bot 都开启 Bot-to-Bot 作为临时兜底。
+
+每个节点都应该先能独立使用 FoxClaw：
+
+```bash
+foxclaw doctor
+foxclaw start
+```
+
+并且你能分别在 Telegram 私聊两个 bot，执行：
+
+```text
+/status
+/auth
+```
+
+## 在 @BotFather 开启 Bot-to-Bot
+
+对参与同步的每一个 bot 都做一遍：
+
+1. 建议使用最新版 Telegram 手机客户端；部分桌面端或旧客户端看不到这个开关。
+2. 打开 `https://t.me/BotFather?startapp`，或进入 `@BotFather` 资料页后点击 **Open App / 打开应用**。
+3. 在 BotFather MiniApp 中选择要参与同步的联系人 bot。
+4. 进入 Settings / Bot Settings。
+5. 找到 **Bot-to-Bot Communication Mode**。
+6. 启用该开关。
+7. 对所有节点的联系人 bot 重复以上步骤。
+
+不要走 `/mybots` → Bot Settings → **Configure Mini App**。那是配置你自己 bot 的 Mini App URL，不是 Bot-to-Bot Communication Mode。
+
+私聊跨节点同步要求双方都开启这个模式。只开一个通常不足以让两个 bot 互相私聊传输同步包。
+
+如果你看到 `Bad Request: USER_BOT_TO_BOT_DISABLED`，优先确认两件事：发送方联系人 bot 和接收方联系人 bot 都已经开启 Bot-to-Bot；多 bot 模式下，发送方联系人默认是 `TG_BOT_TOKENS` 的第一个 token，不一定是你当前输入命令的 bot。
+
+## .env 配置
+
+两台机器使用相同的 `AUTH_SYNC_KEY` 和 `AUTH_SYNC_CLUSTER_ID`，但 `AUTH_SYNC_NODE_ID` 必须不同。
+
+节点 A：
+
+```dotenv
+TG_BOT_TOKENS=<node-a-contact-token>,<node-a-other-bot-token>
+AUTH_SYNC_ENABLED=true
+AUTH_SYNC_KEY=<至少32字节的共享密钥>
+AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
+AUTH_SYNC_NODE_ID=workstation-a
+AUTH_SYNC_PEERS=@foxclaw_node_b_bot
+```
+
+节点 B：
+
+```dotenv
+TG_BOT_TOKENS=<node-b-contact-token>,<node-b-other-bot-token>
+AUTH_SYNC_ENABLED=true
+AUTH_SYNC_KEY=<至少32字节的共享密钥>
+AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
+AUTH_SYNC_NODE_ID=workstation-b
+AUTH_SYNC_PEERS=@foxclaw_node_a_bot
+```
+
+多节点时，`AUTH_SYNC_PEERS` 用英文逗号分隔：
+
+```dotenv
+AUTH_SYNC_PEERS=@foxclaw_node_a_bot,@foxclaw_node_b_bot,@foxclaw_node_c_bot
+```
+
+建议用密码管理器或 `openssl` 生成共享密钥：
+
+```bash
+openssl rand -base64 32
+```
+
+改完配置后重启每台机器的 FoxClaw：
+
+```bash
+foxclaw restart
+```
+
+## 验证步骤
+
+1. 在每台节点的 bot 私聊里执行：
+
+```text
+/auth sync status
+```
+
+应能看到 node id、peer 列表和 pending imports。
+
+2. 在节点 A 执行：
+
+```text
+/auth sync test
+```
+
+节点 A 应提示已向 peer 发送测试 ping。节点 B 的 `/auth sync status` 应能看到最近收到的同步事件或测试状态变化。
+
+从 0.4.17 起，`/auth sync test` 会等待 peer 返回加密 pong。正常结果应该类似：
+
+```text
+auth sync 测试完成：已发送 1，收到回应 1。
+```
+
+如果显示 `未回应：@peer_bot`，说明 Telegram 发送可能成功，但对方没有成功接收、解密、通过 allowlist，或没有运行同一组 auth sync 配置。
+
+3. 用低风险候选做第一次广播。先确认所有 bot runtime 空闲，然后在节点 A 执行：
+
+```text
+/auth sync push all
+```
+
+4. 在节点 B 执行：
+
+```text
+/auth sync status
+/auth
+```
+
+确认待导入清单被处理，或候选已经出现/更新时间变新。
+
+注意：`/auth sync push all` 的“已发送”只代表本节点把加密包发给 Telegram 成功，不代表对端已经写盘。对端只有在全局空闲、usage 验证通过、同名候选 account id 一致，并且远端 `last_refresh` 比本地更新时才会覆盖文件。如果本地已经是相同或更新版本，文件不会变化，`最近导入` 也可能保持为空。
+
+5. 只有在完全理解 refresh token 轮换风险时，才测试：
+
+```text
+/auth refresh all
+/auth refresh all confirm
+```
+
+启用跨节点同步后，这个命令会先申请跨节点刷新锁。任一 peer 忙碌、拒绝或超时都会阻止刷新。
+
+## 常见问题
+
+**`/auth sync test` 没反应**
+
+- 确认两个 bot 都已在 `@BotFather` 开启 Bot-to-Bot Communication Mode。
+- 确认 `AUTH_SYNC_PEERS` 写的是 peer 的 `@username`，不是 token。
+- 确认两边 `AUTH_SYNC_KEY` 和 `AUTH_SYNC_CLUSTER_ID` 完全一致。
+- 确认两个节点都重启过 FoxClaw。
+
+**收到同步包但没有写入候选**
+
+- 本机可能不是全局空闲；有 turn、审批、待输入、登录流程或镜像写入时会排队。
+- usage 验证失败会拒绝写盘。
+- 同名候选属于不同 account id 时会拒绝覆盖。
+
+**要不要定期 `/auth refresh all confirm` 保活**
+
+不要。Codex 会按 access token 到期自动刷新。FoxClaw 的跨节点同步会同步“已经成功刷新的新 auth”，不应该把 refresh all 当作日常保活。

package/docs/zh/user-manual.md

@@ -419,7 +419,19 @@ OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放
 
 ### 6.4 跨节点 auth 同步
 
-跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP；需要先在 BotFather 为参与同步的 bot 开启 Bot-to-Bot Communication Mode。
+跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP。推荐每台机器选择一个联系人 bot；同一节点内其他 bot 继续使用本机 auth 镜像。多 bot 模式下，默认联系人是 `TG_BOT_TOKENS` 的第一个 token。
+
+完整设计、安全边界、`.env` 示例和排查步骤见 [跨节点 auth 同步配置指南](./cross-node-auth-sync.md)。
+
+在 `@BotFather` 中对每个参与同步的 bot 执行：
+
+1. 用最新版 Telegram 手机客户端打开 `https://t.me/BotFather?startapp`，或进入 `@BotFather` 资料页点 **Open App / 打开应用**。
+2. 在 BotFather MiniApp 中选择参与同步的联系人 bot。
+3. 打开 Settings / Bot Settings。
+4. 找到并启用 **Bot-to-Bot Communication Mode**。
+5. 对所有节点的联系人 bot 重复；私聊同步要求发送方和接收方都开启。
+
+不要走 `/mybots` → Bot Settings → **Configure Mini App**；那是配置 bot 的 Mini App URL，不是 Bot-to-Bot Communication Mode。
 
 配置示例：
 
@@ -449,8 +461,8 @@ AUTH_SYNC_NODE_ID=workstation-a
 命令：
 
 - `/auth sync status`：查看 node id、peer、最近收发、最近导入、待导入和最近错误。
-- `/auth sync test`：发送加密 ping，确认 peer、共享密钥和 Bot-to-Bot 私聊可用。
-- `/auth sync push all`：手动广播当前节点已验证的全部候选，不刷新 token。
+- `/auth sync test`：发送加密 ping 并等待 peer 返回 pong，确认 peer、共享密钥和 Bot-to-Bot 私聊可用。
+- `/auth sync push all`：手动广播当前节点已验证的全部候选，不刷新 token；“已发送”不等于对端已经导入，需要在 peer 上看 `/auth sync status` 和 `/auth`。
 
 命令等价用法：
 
@@ -467,7 +479,7 @@ AUTH_SYNC_NODE_ID=workstation-a
 
 切换 auth 时，如果当前 bot runtime 还有活跃 turn、待审批、待用户输入或 MCP elicitation，FoxClaw 会先拒绝切换，避免中途换号破坏正在进行的请求；另一个空闲 bot 不受影响。
 
-### 6.4 自动轮转如何工作
+### 6.5 自动轮转如何工作
 
 当 Codex 返回用量限制、未登录、认证失效或类似 auth 错误时，FoxClaw 会尝试自动轮转：
 
@@ -511,4 +523,5 @@ auth.json_backup       # 备用账号，可按需 enable/disable
 
 - [新手安装指南](./install-for-beginners.md)
 - [Agent 辅助安装](./agent-assisted-install.md)
+- [跨节点 auth 同步配置指南](./cross-node-auth-sync.md)
 - [故障排查](./troubleshooting.md)

package/package.json

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

package/skills/foxclaw/SKILL.md

@@ -70,7 +70,7 @@ Telegram behavior:
 - `/auth` paginates large candidate inventories at 8 rows per page, supports all/enabled/attention filters and filename search, renders actual observed quota windows in text rows, uses compact two-number remaining quota labels on buttons, and omits the repeated `auth.json_` prefix from panel labels without renaming files
 - treat the `/auth` `not recently refreshed` state as a maintenance hint only: OpenAI does not publish a fixed ChatGPT refresh-token lifetime or replay grace period, and FoxClaw must not add routine bulk keepalive refreshes
 - `/auth refresh all` remains a command-only maintenance action, not a panel button; it requires explicit token-rotation risk confirmation, then force-refreshes every ChatGPT candidate through Codex `account/read refreshToken=true`, validates usage, mirrors successful candidates, and restores the original current auth while every runtime is globally idle
-- optional cross-node auth sync uses Telegram Bot-to-Bot private messages with encrypted auth bundles; configure `AUTH_SYNC_ENABLED=true`, a shared `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS`, then use `/auth sync status`, `/auth sync test`, and `/auth sync push all`; cross-node recovery pulls already-held valid peer copies and does not auto-refresh tokens
+- optional cross-node auth sync uses Telegram Bot-to-Bot private messages with encrypted auth bundles; the default topology is one contact bot per node, and in multi-bot mode the first `TG_BOT_TOKENS` entry is the contact transport; configure `AUTH_SYNC_ENABLED=true`, a shared `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS` containing peer contact bot usernames, then use `/auth sync status`, `/auth sync test`, and `/auth sync push all`; `/auth sync test` waits for encrypted peer pong replies, while push-all only proves send success and peer import must be checked on the receiver
 - when cross-node auth sync is enabled, `/auth refresh all confirm` must obtain a cross-node refresh lease before rotating refresh tokens; any busy, denying, or non-responsive peer blocks the refresh
 - if `TG_BOT_TOKEN` is also set to one exact token from `TG_BOT_TOKENS`, that bot uses the default/shared-terminal runtime instead of an isolated Telegram home
 - if Weixin is enabled alongside multiple Telegram bots, it remains on the default Codex runtime instead of borrowing a Telegram bot runtime