@foxden-app/foxclaw 0.2.4 → 0.2.5

package/README.md

@@ -2,36 +2,36 @@
 
 # FoxClaw
 
-FoxClaw 是 Foxden agents 的本地执行爪。
+FoxClaw 是 Foxden agents 的本地执行爪——跑在你自己电脑上，让你通过 Telegram 或微信远程操控本机的 Codex。
 
-它运行在你自己的电脑上，让受信任的 Telegram 或微信聊天可以控制本机 Codex 环境。你不需要公网服务器：FoxClaw 通过本地 `codex app-server` 与 Codex 通信，把审批留在你的电脑上，并把工作会话发送回手机。
+不需要公网服务器。FoxClaw 在本地和 `codex app-server` 通信，审批在你电脑上完成，结果推送回手机。
 
 ## 从这里开始
 
-- 已经有 Codex、OpenClaw、QwenPaw、Hermes、OpenCode 或 Kimi CLI 这类能操作 shell 的 agent？优先使用 [Agent 辅助安装](./docs/agent-assisted-install.md)，这是推荐路径。
-- 不熟悉 Node、Telegram 机器人或 Codex CLI？使用 [新手安装指南](./docs/install-for-beginners.md)。
-- 已经熟悉 Git、Node 和 `.env` 文件？可以直接使用下面的快速设置。
-- 遇到问题？查看 [故障排查](./docs/troubleshooting.md)。
+- 手头有 Codex、OpenClaw、QwenPaw、Hermes、OpenCode、Kimi CLI 之类能跑 shell 的 agent？推荐走 [Agent 辅助安装](./docs/agent-assisted-install.md)。
+- 对 Node、Telegram 机器人、Codex CLI 不太熟？看 [新手安装指南](./docs/install-for-beginners.md)。
+- Git、Node、`.env` 都玩得转？直接往下看快速设置。
+- 卡住了？看 [故障排查](./docs/troubleshooting.md)。
 
-如果你希望做到这些，FoxClaw 会很适合：
+FoxClaw 适合这些场景：
 
-- 在手机上使用 Codex，同时不把自己的电脑暴露到公网
-- 将代码、shell 访问、认证、审批和运行数据都保留在自己的机器上
-- 让一个受信任的 Telegram 用户作为远程操作者
+- 在手机上用 Codex，但不想把电脑暴露到公网
+- 代码、shell、认证、审批、运行数据全部留在本机
+- 只允许一个受信任的 Telegram 用户远程操作
 
-最小安装只需要一个 Telegram bot token、你的 Telegram 数字用户 ID、Node.js 24，以及一份已经登录的 `codex` CLI。首次安装通常需要 10-20 分钟。
+最低要求：一个 Telegram bot token、你的 Telegram 数字用户 ID、Node.js 24、一份已登录的 `codex` CLI。首次安装大约 10–20 分钟。
 
-30 秒产品示例：FoxClaw 运行后，向你的 Telegram 机器人发送 `List files in DEFAULT_CWD`。FoxClaw 会让本地 Codex 检查你电脑上的那个目录，并把答案发回 Telegram。
+**30 秒体验**：启动 FoxClaw 后，给你的 Telegram 机器人发一句 `List files in DEFAULT_CWD`。Codex 会在本地检查那个目录，然后把结果发回 Telegram。
 
 ## 环境要求
 
-- macOS 或 Linux，并且有可用的 `codex` CLI
-- 主机上的 Codex 已完成认证
+- macOS 或 Linux，`codex` CLI 可用
+- Codex 已完成登录认证
 - Node.js 24+
-- 来自 `@BotFather` 的 Telegram bot token
+- 一个 `@BotFather` 创建的 Telegram bot token
 - 你的 Telegram 数字用户 ID
 
-## npm 快速设置
+## 快速设置
 
 ```bash
 npm install -g @foxden-app/foxclaw
@@ -41,7 +41,7 @@ foxclaw doctor
 foxclaw start
 ```
 
-pnpm 用户可以使用：
+pnpm 用户：
 
 ```bash
 pnpm add -g @foxden-app/foxclaw
@@ -51,7 +51,7 @@ foxclaw doctor
 foxclaw start
 ```
 
-运行 `doctor` 或 `start` 前先编辑 `.env`。私聊模式的最小配置：
+跑 `doctor` 或 `start` 之前先把 `.env` 填好。私聊模式最小配置：
 
 ```dotenv
 TG_BOT_TOKEN=123456:telegram-token
@@ -61,66 +61,68 @@ DEFAULT_APPROVAL_POLICY=on-request
 DEFAULT_SANDBOX_MODE=workspace-write
 ```
 
-默认配置文件是 `~/.foxclaw/.env`。如果你想把配置放在别处，可以设置 `FOXCLAW_ENV=/path/to/.env`。
+配置文件默认在 `~/.foxclaw/.env`。想放别处的话设 `FOXCLAW_ENV=/path/to/.env`。
 
-`foxclaw start` 会运行检查并安装或重启后台服务；这个命令是幂等的，升级后可以再执行一次。
+`foxclaw start` 会自动检查环境并安装/重启后台服务，幂等操作，升级后再跑一次就行。
 
-FoxClaw 只接受来自 `TG_ALLOWED_USER_ID` 的消息。把机器人放进群组并不会让每个群成员都能使用它。
+FoxClaw 只响应 `TG_ALLOWED_USER_ID` 的消息——把机器人拉进群不代表群里所有人都能用。
 
 <details>
-<summary>FoxClaw 运行后可以做什么</summary>
-
-- 允许一个 Telegram 用户通过私聊、群组和话题控制
-- 可选的微信/iLink 通道，复用同一套桥接核心
-- 使用 `/threads`、`/open`、`/new`、`/where` 和 `/interrupt` 进行稳定的聊天到线程绑定
-- 从手机控制线程生命周期：重命名、归档、取消归档、fork、回滚、compact、review 和 diff
-- 面向单个聊天的设置面板：模型、reasoning effort、Fast service tier、access preset、Agent/Plan 模式和 active-turn 行为
-- Codex 账户控制：`/account`、`/quota`、`/login_device`、`/login_cancel`、`/auth add <name>`，以及带保护的 `/logout confirm`
-- 当某个认证触发用量限制时，在本地 `auth.json_*` 候选之间自动切换 Codex 认证
-- 针对命令、文件变更和细粒度权限审批的内联按钮
-- 针对工具在 turn 中提出的结构化问题显示 MCP elicitation 卡片
-- Skills、MCP、hooks、plugins、apps、feature flags、config、requirements 和 provider diagnostics
-- 使用 SQLite 持久化绑定、offset、审批、待处理输入提示和审计日志
-- 单实例进程锁，避免同一个 bot token 上出现重复 Telegram polling
+<summary>FoxClaw 能做什么</summary>
+
+- 单个 Telegram 用户通过私聊、群组、话题控制
+- 可选微信/iLink 通道，复用同一套桥接核心
+- `/threads`、`/open`、`/new`、`/where`、`/interrupt`——稳定的聊天-线程绑定
+- 手机上管理线程生命周期：重命名、归档、取消归档、fork、回滚、compact、review、diff
+- 每个聊天独立的设置面板：模型、reasoning effort、Fast tier、access preset、Agent/Plan 模式、active-turn 行为
+- Codex 账户管理：`/account`、`/quota`、`/login_device`、`/login_cancel`、`/auth add <name>`、`/logout confirm`
+- 触发用量限制时自动在本地 `auth.json_*` 之间切换认证
+- 命令、文件变更、细粒度权限审批的内联按钮
+- MCP elicitation 卡片——工具在 turn 中提出结构化问题时展示
+- Skills、MCP、hooks、plugins、apps、feature flags、config、requirements、provider diagnostics
+- SQLite 持久化：绑定、offset、审批、待处理提示、审计日志
+- 单实例进程锁，防止同一 bot token 重复 polling
 
 </details>
 
 ## 服务与调试
 
-推荐使用：
+推荐方式：
 
 ```bash
 foxclaw start
 ```
 
-它会在 Linux 上安装或重启用户级 systemd 服务，在 macOS 上安装或重载 launchd。需要查看服务状态时：
+Linux 上会安装/重启用户级 systemd 服务，macOS 上安装/重载 launchd。查看状态：
 
 ```bash
 systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
-前台调试时可以直接运行：
+需要前台调试时：
 
 ```bash
 foxclaw serve
 ```
 
-默认运行时文件存储在 `~/.foxclaw`：
+运行时文件默认在 `~/.foxclaw`：
 
-- store：`~/.foxclaw/data/bridge.sqlite`
-- bridge log：`~/.foxclaw/logs/service.log`
-- status：`~/.foxclaw/runtime/status.json`
-- app-server state：`~/.foxclaw/runtime/codex-app-server.json`
-- app-server log：`~/.foxclaw/logs/codex-app-server.log`
+| 用途 | 路径 |
+|------|------|
+| 数据库 | `~/.foxclaw/data/bridge.sqlite` |
+| Bridge 日志 | `~/.foxclaw/logs/service.log` |
+| 状态 | `~/.foxclaw/runtime/status.json` |
+| App-server 状态 | `~/.foxclaw/runtime/codex-app-server.json` |
+| App-server 日志 | `~/.foxclaw/logs/codex-app-server.log` |
 
-可以用 `STORE_PATH`、`LOCK_PATH`、`CODEX_APP_SERVER_STATE_PATH` 和 `CODEX_APP_SERVER_LOG_PATH` 覆盖 store、lock 和 app-server 路径。
+可通过 `STORE_PATH`、`LOCK_PATH`、`CODEX_APP_SERVER_STATE_PATH`、`CODEX_APP_SERVER_LOG_PATH` 覆盖。
 
 ## 从 telegram-codex-app-bridge 迁移
 
-FoxClaw 最初 fork 自 `Gan-Xing/telegram-codex-app-bridge`，并继续以 MIT License 分发。
+FoxClaw 最初 fork 自 `Gan-Xing/telegram-codex-app-bridge`，继续以 MIT License 分发。
 
-升级已有本地安装时：
+升级已有安装：
 
 ```bash
 systemctl --user disable --now telegram-codex-app-bridge.service 2>/dev/null || true
@@ -128,54 +130,54 @@ test -e ~/.foxclaw || cp -a ~/.telegram-codex-app-bridge ~/.foxclaw
 foxclaw start
 ```
 
-如果使用 launchd 安装，先卸载旧 plist（如存在）：
+macOS launchd 用户先卸载旧 plist：
 
 ```bash
 launchctl unload ~/Library/LaunchAgents/com.ganxing.telegram-codex-app-bridge.plist 2>/dev/null || true
 foxclaw start
 ```
 
-旧运行时目录不会被自动读取。如果你想保留现有绑定、缓存线程列表、审批和状态数据，请手动复制一次。
+旧目录不会被自动读取。如果要保留已有的绑定、线程缓存、审批和状态数据，手动复制一次即可。
 
 ## Telegram 设置
 
-1. 使用 `@BotFather` 创建机器人，并把 token 填入 `TG_BOT_TOKEN`。
-2. 获取你的 Telegram 数字用户 ID，并填入 `TG_ALLOWED_USER_ID`。
-3. 使用 `foxclaw start` 启动 FoxClaw。
-4. 打开与机器人的私聊并发送 `/help`。
+1. 用 `@BotFather` 创建机器人，token 填入 `TG_BOT_TOKEN`。
+2. 拿到你的 Telegram 数字用户 ID，填入 `TG_ALLOWED_USER_ID`。
+3. `foxclaw start` 启动。
+4. 打开和机器人的私聊，发 `/help`。
 
-可选的群组/话题配置：
+可选——群组/话题配置：
 
 ```dotenv
 TG_ALLOWED_CHAT_ID=-1001234567890
 TG_ALLOWED_TOPIC_ID=42
 ```
 
-- 留空 `TG_ALLOWED_CHAT_ID` 表示使用私聊模式。
-- 只设置 `TG_ALLOWED_CHAT_ID` 时，允许一个群组作为默认会话范围。
-- 同时设置 `TG_ALLOWED_CHAT_ID` 和 `TG_ALLOWED_TOPIC_ID` 时，绑定一个话题作为默认范围。
-- 即使配置了群组，`TG_ALLOWED_USER_ID` 仍然可以继续使用私聊。
+- `TG_ALLOWED_CHAT_ID` 留空 → 纯私聊模式。
+- 只填 `TG_ALLOWED_CHAT_ID` → 允许一个群组作为默认会话范围。
+- 两个都填 → 绑定到某个话题。
+- 配了群组后，`TG_ALLOWED_USER_ID` 的私聊依然可用。
 
-查找群组和话题 ID：
+**怎么找群组和话题 ID：**
 
-1. 停止 FoxClaw。
-2. 在目标群组或话题中发送一条消息。
-3. 打开 `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`。
-4. 读取 `message.chat.id` 作为 `TG_ALLOWED_CHAT_ID`。
-5. 读取 `message.message_thread_id` 作为 `TG_ALLOWED_TOPIC_ID`。
+1. 先停掉 FoxClaw。
+2. 在目标群组/话题里发一条消息。
+3. 浏览器打开 `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`。
+4. 找 `message.chat.id` → 填 `TG_ALLOWED_CHAT_ID`。
+5. 找 `message.message_thread_id` → 填 `TG_ALLOWED_TOPIC_ID`。
 
-如果 FoxClaw 还在运行，它可能会在你检查前消费掉该 update。
+> 如果 FoxClaw 还在跑，它可能会先把这条 update 消费掉，所以要先停。
 
 ## Telegram 群组检查清单
 
-对于群组或超级群里的自然语言消息：
+要让机器人在群组/超级群里收到普通消息：
 
-1. 将机器人加入目标群组。
-2. 在 `@BotFather` 中禁用机器人的 `privacy mode`。
-3. 将机器人提升为该群管理员。
-4. 如果是在加入群组后才修改隐私模式，请移除并重新加入机器人。
+1. 把机器人加进目标群组。
+2. 在 `@BotFather` 里关掉 `privacy mode`。
+3. 把机器人设为群管理员。
+4. 如果是加群之后才改的隐私模式，把机器人踢出去再重新加。
 
-即使 privacy mode 阻止普通消息，`/status@botname` 这样的显式命令也可能正常工作，所以请用一条普通消息验证群组设置。
+> 注意：即使 privacy mode 挡住了普通消息，`/status@botname` 这种显式命令可能还是能用的。所以验证群组设置时，请用一条普通文本消息测试。
 
 ## Codex App-Server 生命周期
 
@@ -190,14 +192,14 @@ CODEX_APP_SYNC_ON_OPEN=true
 CODEX_APP_SYNC_ON_TURN_COMPLETE=false
 ```
 
-FoxClaw 会把 `codex app-server` 启动为一个由 bridge 管理的 detached 进程，并记录它的 pid 和端口。重启时，如果记录的 app-server 进程仍然存活，FoxClaw 会重新连接；否则会启动一个新进程。`/auth_reload` 和认证切换会重启托管的 app-server，从而重新加载当前 `auth.json`。
+FoxClaw 会把 `codex app-server` 作为 detached 子进程启动，记录其 pid 和端口。重启时如果进程还活着就直接重连，否则拉起新进程。`/auth_reload` 和认证切换会重启 app-server 以重新加载 `auth.json`。
 
-正常安装不需要固定的 Codex app-server 端口。
+一般不需要手动固定 app-server 端口。
 
 ## 命令
 
 - `/help`
-- `/setup` 打开统一偏好设置面板
+- `/setup` — 统一设置面板
 - `/fast <on|off|toggle>`
 - `/active <steer|queue>`
 - `/status`、`/account`、`/quota`
@@ -215,35 +217,35 @@ FoxClaw 会把 `codex app-server` 启动为一个由 bridge 管理的 detached
 - `/skills [query]`、`/skill <name>`、`/skill_enable <name>`、`/skill_disable <name>`
 - `/loaded`、`/hooks`、`/plugins [query]`、`/apps [reload]`、`/features`、`/config`、`/requirements`、`/provider`
 - `/mcp`、`/mcp_reload`、`/mcp_login <server>`、`/mcp_resource <server> <uri>`
-- `/models`、`/model`、`/effort`、`/permissions`、`/access`、`/mode`、`/plan` 和 `/agent`
+- `/models`、`/model`、`/effort`、`/permissions`、`/access`、`/mode`、`/plan`、`/agent`
 - `/reveal`、`/where`、`/interrupt`
 
-普通文本会发送到当前线程；如果当前没有绑定线程，则创建一个新线程。
+直接发文本会送到当前线程；没有绑定线程时自动创建新线程。
 
 ## 微信/iLink
 
-微信支持是可选的，默认关闭：
+微信支持默认关闭，需要手动开启：
 
 ```dotenv
 WX_ENABLED=true
 WX_ALLOWED_ILINK_USER_IDS=
 ```
 
-构建后运行一次二维码登录助手：
+构建完成后跑一次二维码登录：
 
 ```bash
 foxclaw weixin-login
 ```
 
-微信运行时文件默认存储在 `~/.foxclaw/weixin`。
+微信运行时文件在 `~/.foxclaw/weixin`。
 
 ## Codex Skill
 
-本仓库内置一个 Codex skill：[`skills/foxclaw`](./skills/foxclaw)。当你想让 Codex 在本机或另一台 Mac 上通过 SSH bootstrap FoxClaw、写入 `.env`、构建、运行 doctor、安装 launchd，并指导首次消息验证时，可以使用它。
+仓库自带一个 Codex skill：[`skills/foxclaw`](./skills/foxclaw)。用它可以让 Codex 通过 SSH 在本机或远程 Mac 上 bootstrap FoxClaw——写 `.env`、构建、跑 doctor、装 launchd、引导首次消息验证，一条龙。
 
 ## 故障排查
 
-`doctor` 失败、Telegram 没有回复、服务日志、重启行为和迁移问题，请查看 [故障排查](./docs/troubleshooting.md)。
+`doctor` 报错、Telegram 没回复、服务日志看不懂、重启行为异常、迁移出问题——都看 [故障排查](./docs/troubleshooting.md)。
 
 ## 运维命令
 
@@ -256,4 +258,4 @@ foxclaw uninstall-systemd
 
 ## 贡献
 
-欢迎在 `https://github.com/foxden-app/foxclaw` 提交 issue 和 PR。
+欢迎到 [GitHub](https://github.com/foxden-app/foxclaw) 提 issue 和 PR。

package/package.json

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