@foxden-app/foxclaw 0.4.16 → 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,18 @@
 
 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
 
 ### 中文

package/README.md

@@ -212,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` 会先申请跨节点刷新锁。完整配置、`@BotFather` 操作和验证步骤见 [跨节点 auth 同步配置指南](./docs/zh/cross-node-auth-sync.md)。
+多台机器共享同一合法账号池时，可以启用可选跨节点 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

@@ -212,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. For full config, `@BotFather` operations, and verification steps, read the [Cross-Node Auth Sync Setup Guide](./docs/cross-node-auth-sync.md).
+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

@@ -11,6 +11,7 @@ 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:
 
@@ -44,6 +45,8 @@ 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
@@ -62,16 +65,20 @@ In a private Telegram chat with each bot, verify:
 
 Repeat this for every participating bot:
 
-1. Open Telegram and enter `@BotFather`.
-2. Send `/mybots`.
-3. Select the bot that will participate in auth sync.
-4. Open the bot settings / Mini App settings interface.
+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 peer bot.
+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`.
@@ -79,6 +86,7 @@ Use the same `AUTH_SYNC_KEY` and `AUTH_SYNC_CLUSTER_ID` on all nodes, but give e
 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
@@ -89,6 +97,7 @@ 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
@@ -132,6 +141,14 @@ You should see the node id, peer list, and pending imports.
 
 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
@@ -147,6 +164,8 @@ Node A should report that it sent a test ping. Node B's `/auth sync status` shou
 
 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
@@ -174,4 +193,3 @@ With cross-node sync enabled, this command first requests a cross-node refresh l
 **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,18 +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. Open `@BotFather`.
-2. Send `/mybots`.
-3. Select the bot that will participate in sync.
-4. Open the bot settings / Mini App settings interface.
-5. Find and enable **Bot-to-Bot Communication Mode**.
-6. Repeat for every peer bot; private sync requires this mode on both sender and recipient.
+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:
 
@@ -460,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:
 

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

@@ -11,6 +11,7 @@
 - 这些 ChatGPT 账号和 auth 文件都由你合法拥有和维护。
 - 多台机器都运行 FoxClaw，并且每台机器至少有一个 Telegram bot。
 - 你希望 auth 文件在节点间自动保持较新，但不希望日常主动旋转 refresh token。
+- 默认推荐每台机器只选择一个“联系人 bot”参与跨节点同步；同一节点内其他 bot 继续使用原本的本机 auth 镜像。
 
 不适合：
 
@@ -44,6 +45,8 @@ Telegram 官方 Bot Features 文档说明：私聊 bot-to-bot 需要发送方和
 - 节点 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
@@ -62,16 +65,20 @@ foxclaw start
 
 对参与同步的每一个 bot 都做一遍：
 
-1. 打开 Telegram，进入 `@BotFather`。
-2. 发送 `/mybots`。
-3. 选择要参与同步的 bot。
-4. 打开 BotFather 的 bot settings / Mini App 设置界面。
+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. 对所有 peer bot 重复以上步骤。
+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` 必须不同。
@@ -79,6 +86,7 @@ foxclaw start
 节点 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
@@ -89,6 +97,7 @@ 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
@@ -132,6 +141,14 @@ foxclaw restart
 
 节点 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
@@ -147,6 +164,8 @@ foxclaw restart
 
 确认待导入清单被处理，或候选已经出现/更新时间变新。
 
+注意：`/auth sync push all` 的“已发送”只代表本节点把加密包发给 Telegram 成功，不代表对端已经写盘。对端只有在全局空闲、usage 验证通过、同名候选 account id 一致，并且远端 `last_refresh` 比本地更新时才会覆盖文件。如果本地已经是相同或更新版本，文件不会变化，`最近导入` 也可能保持为空。
+
 5. 只有在完全理解 refresh token 轮换风险时，才测试：
 
 ```text
@@ -174,4 +193,3 @@ foxclaw restart
 **要不要定期 `/auth refresh all confirm` 保活**
 
 不要。Codex 会按 access token 到期自动刷新。FoxClaw 的跨节点同步会同步“已经成功刷新的新 auth”，不应该把 refresh all 当作日常保活。
-

package/docs/zh/user-manual.md

@@ -419,18 +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. 打开 `@BotFather`。
-2. 发送 `/mybots`。
-3. 选择参与同步的 bot。
-4. 打开 bot settings / Mini App 设置界面。
-5. 找到并启用 **Bot-to-Bot Communication Mode**。
-6. 对所有 peer 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。
 
 配置示例：
 
@@ -460,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`。
 
 命令等价用法：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.4.16",
+  "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