@foxden-app/foxclaw 0.4.14 → 0.4.16

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.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
+
+### 中文
+- 更新 FoxClaw 收尾 skill：发布前固定检查设计文档、中文/英文使用手册和对外公开文档。
+- 涉及 Telegram 设置的变更，使用手册必须写清 `@BotFather` 操作步骤；npm 发布 skill 也会遵守该项目文档门槛。
+
+### English
+- Updated the FoxClaw wrap-up skill to require design docs, Chinese/English user manuals, and public-facing docs before release.
+- Telegram setup changes must document the exact `@BotFather` steps in the manuals; the npm publish skill now honors this project documentation gate too.
+
 ## 0.4.14 - 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_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_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/docs/cross-node-auth-sync.md

@@ -0,0 +1,177 @@
+# 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.
+
+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`
+
+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. 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.
+5. Find **Bot-to-Bot Communication Mode**.
+6. Enable it.
+7. Repeat for every peer bot.
+
+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.
+
+## .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
+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
+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.
+
+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.
+
+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

@@ -421,6 +421,17 @@ OpenAI does not publish a fixed ChatGPT refresh-token lifetime or an old-token r
 
 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.
 
+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.
+
 Example:
 
 ```dotenv
@@ -467,7 +478,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 +522,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,177 @@
+# 跨节点 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。
+
+不适合：
+
+- 同步来源不可信、账号来源不合法，或你无法确认每台机器的管理员。
+- 希望用 `/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`
+
+每个节点都应该先能独立使用 FoxClaw：
+
+```bash
+foxclaw doctor
+foxclaw start
+```
+
+并且你能分别在 Telegram 私聊两个 bot，执行：
+
+```text
+/status
+/auth
+```
+
+## 在 @BotFather 开启 Bot-to-Bot
+
+对参与同步的每一个 bot 都做一遍：
+
+1. 打开 Telegram，进入 `@BotFather`。
+2. 发送 `/mybots`。
+3. 选择要参与同步的 bot。
+4. 打开 BotFather 的 bot settings / Mini App 设置界面。
+5. 找到 **Bot-to-Bot Communication Mode**。
+6. 启用该开关。
+7. 对所有 peer bot 重复以上步骤。
+
+私聊跨节点同步要求双方都开启这个模式。只开一个通常不足以让两个 bot 互相私聊传输同步包。
+
+## .env 配置
+
+两台机器使用相同的 `AUTH_SYNC_KEY` 和 `AUTH_SYNC_CLUSTER_ID`，但 `AUTH_SYNC_NODE_ID` 必须不同。
+
+节点 A：
+
+```dotenv
+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
+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` 应能看到最近收到的同步事件或测试状态变化。
+
+3. 用低风险候选做第一次广播。先确认所有 bot runtime 空闲，然后在节点 A 执行：
+
+```text
+/auth sync push all
+```
+
+4. 在节点 B 执行：
+
+```text
+/auth sync status
+/auth
+```
+
+确认待导入清单被处理，或候选已经出现/更新时间变新。
+
+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

@@ -421,6 +421,17 @@ OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放
 
 跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP；需要先在 BotFather 为参与同步的 bot 开启 Bot-to-Bot Communication Mode。
 
+完整设计、安全边界、`.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 重复；私聊同步要求发送方和接收方都开启。
+
 配置示例：
 
 ```dotenv
@@ -467,7 +478,7 @@ AUTH_SYNC_NODE_ID=workstation-a
 
 切换 auth 时，如果当前 bot runtime 还有活跃 turn、待审批、待用户输入或 MCP elicitation，FoxClaw 会先拒绝切换，避免中途换号破坏正在进行的请求；另一个空闲 bot 不受影响。
 
-### 6.4 自动轮转如何工作
+### 6.5 自动轮转如何工作
 
 当 Codex 返回用量限制、未登录、认证失效或类似 auth 错误时，FoxClaw 会尝试自动轮转：
 
@@ -511,4 +522,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.14",
+  "version": "0.4.16",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",

package/skills/foxclaw/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: foxclaw
-description: Deploy, configure, validate, develop, and release FoxClaw. Use when Codex needs to clone or update the FoxClaw repo, collect Telegram values, write `.env`, enable launchd/systemd, guide first-message tests, or perform FoxClaw repo wrap-up actions such as bilingual Chinese | English commit messages, push, npm publish, and local install/service update.
+description: Deploy, configure, validate, develop, and release FoxClaw. Use when Codex needs to clone or update the FoxClaw repo, collect Telegram values, write `.env`, enable launchd/systemd, guide first-message tests, or perform FoxClaw repo wrap-up actions such as documentation gates, bilingual Chinese | English commit messages, push, npm publish, and local install/service update.
 ---
 
 # FoxClaw
@@ -184,22 +184,28 @@ When the user says development is complete, asks to "收尾", or asks to push/pu
    - `git status -sb`
    - `git diff --stat`
    - `git diff --name-status`
-2. Run the relevant verification with Node 24+. If the system `node` is older, prepend the known Node 24 bin path or use the repo's documented Node 24 shell.
+2. Apply the documentation gate before validation and release for user-visible behavior, setup, config, command, auth, Telegram, or release-flow changes:
+   - Update the design documentation for architecture, protocol, storage, locking, security, config, or rollout decisions. If there is no dedicated design file yet, create or extend the most appropriate `docs/` file instead of leaving the design only in chat.
+   - Update the user manual in Chinese and English for new commands, panels, environment variables, safety constraints, verification steps, and operator workflows.
+   - If Telegram-side setup is involved, include the exact `@BotFather` operation path in the manual, such as privacy mode, Bot-to-Bot Communication Mode, admin requirements, group/topic setup, or token creation as applicable.
+   - Update external-facing public docs: `README.md`, `README_EN.md`, `CHANGELOG.md`, and release-note wording with a clear user value statement suitable for GitHub/npm readers.
+   - For purely internal or test-only changes where one of these document classes truly does not apply, state that explicitly in the wrap-up summary.
+3. Run the relevant verification with Node 24+. If the system `node` is older, prepend the known Node 24 bin path or use the repo's documented Node 24 shell.
    - Code changes: `npm run typecheck`, `npm run lint`, `npm test`
    - Package/release changes: also run `npm pack --dry-run`
    - Skill-only changes: validate the skill folder, then run `npm pack --dry-run`
-3. Build before any local service restart:
+4. Build before any local service restart:
    - `npm run build`
-4. Commit intentionally:
+5. Commit intentionally:
    - Stage only the changed files that belong to the task.
    - For this repo, prefer a bilingual one-line subject in the form `中文 | English`.
    - Put Chinese first, keep the English half semantically equivalent, and keep both halves concise.
    - For release commits, use the same format, for example `发布 0.4.0：支持多机器人隔离 | Release 0.4.0: support multi-bot isolation`.
    - Update `CHANGELOG.md` for any published version, using bilingual Chinese and English notes.
    - Never stage unrelated local changes.
-5. Push the current branch after a successful commit:
+6. Push the current branch after a successful commit:
    - `git push origin <branch>`
-6. Refresh the local install when requested:
+7. Refresh the local install when requested:
    - If the user has a pnpm global FoxClaw install, prefer `pnpm add -g <repo-path>` so the global `foxclaw` points at the local repo.
    - Rebuild before restarting because local linked installs run `dist/main.js`.
    - Refresh systemd with the existing service env path, for example `FOXCLAW_ENV=<existing-env> <node24> dist/main.js install-systemd`. Do not run `install-systemd` from the repo without `FOXCLAW_ENV`, because it may rewrite the service to use the repo `.env`.
@@ -208,7 +214,7 @@ When the user says development is complete, asks to "收尾", or asks to push/pu
    - Verify the running service reports the expected FoxClaw version in `status`.
    - If `doctor` fails only because `DEFAULT_CWD` is missing, report that separately; do not treat it as evidence that the service update failed.
    - `/update` now attempts to update globally npm/pnpm-managed Codex CLI installations, reports FoxClaw and Codex CLI version changes, and refuses to restart while any configured Telegram runtime, enabled Weixin default runtime, or auth mirror write is busy.
-7. Publish to npm when requested:
+8. Publish to npm when requested:
    - Prefer GitHub Actions trusted publishing via `.github/workflows/publish.yml`: bump and commit the package version, push `main`, then push a matching `v<version>` tag. The tag version must match `package.json`.
    - Ensure the matching changelog section exists before pushing the version tag; the publish workflow uses it to create or update the GitHub Release.
    - Treat `workflow_dispatch` only as a retry path from an existing matching release tag; do not manually run publishing from `main`.

package/skills/foxclaw/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "FoxClaw"
   short_description: "Install, validate, update, and release FoxClaw bridges"
-  default_prompt: "Use $foxclaw to clone or update FoxClaw, configure Telegram values, validate service health, or finish repo changes with commit, push, npm publish, and local install refresh."
+  default_prompt: "Use $foxclaw to clone or update FoxClaw, configure Telegram values, validate service health, or finish repo changes with required docs, commit, push, npm publish, and local install refresh."

package/skills/npm-publish/SKILL.md

@@ -9,6 +9,8 @@ Use this skill to publish an npm package from a repo. Prefer CI trusted publishi
 
 If the user asks to release, publish, "收尾", "push publish", or otherwise finish a completed package change, proceed through verification, commit, push, publish, and post-publish verification without asking for a second confirmation. Pause only for real blockers: missing credentials, failed checks, unrelated changes that would be staged, merge conflicts, an already-published target version that needs a version choice, or npm/GitHub web-auth that requires the user to click/confirm an external page.
 
+Before publishing, honor any project-specific release documentation gate. For FoxClaw releases, verify design documentation, Chinese and English user manuals, `@BotFather` operation steps when Telegram setup changes, and external-facing README/CHANGELOG/release wording are updated or explicitly marked not applicable.
+
 ## Release Checklist
 
 1. Sync first when the user asks for it: