@foxden-app/foxclaw 0.2.5 → 0.2.7

package/dist/i18n.js

@@ -146,10 +146,10 @@ const MESSAGES = {
         auth_add_cancelled: 'New auth login cancelled. Restored previous auth.',
         auth_add_reverted: 'Restored previous auth.',
         auth_add_missing_file: 'Login completed, but the new auth file was not created: {value}',
-        button_login_device: 'Login device',
-        button_auth_reload: 'Reload auth',
-        button_auth_enable: 'Enable',
-        button_auth_disable: 'Disable',
+        button_login_device: '🔑 Login',
+        button_auth_reload: '🔄 Reload auth',
+        button_auth_enable: '✅ Enable',
+        button_auth_disable: '⏸️ Disable',
         another_turn_running: 'Another turn is already running. Use /interrupt, /takeover, /queue, or wait.',
         working: 'Working...',
         usage_open: 'Usage: /open <n>',
@@ -293,16 +293,16 @@ const MESSAGES = {
         approval_decision_accept: 'allow',
         approval_decision_session: 'allow for session',
         approval_decision_deny: 'deny',
-        button_allow: 'Allow',
-        button_allow_session: 'Allow Session',
-        button_deny: 'Deny',
-        button_interrupt: 'Interrupt',
-        button_permissions: 'Access',
-        button_models: 'Models',
-        button_threads: 'Threads',
-        button_reveal: 'Reveal',
-        button_auto: 'Auto',
-        button_new_thread: 'New',
+        button_allow: '✅ Allow',
+        button_allow_session: '✅ Session',
+        button_deny: '🚫 Deny',
+        button_interrupt: '⏹️ Interrupt',
+        button_permissions: '🛡️ Access',
+        button_models: '🤖 Models',
+        button_threads: '🧵 Threads',
+        button_reveal: '↗️ Reveal',
+        button_auto: '⚙️ Auto',
+        button_new_thread: '➕ New',
         threads_no_matches: '<b>No threads matched</b>\n<code>{searchTerm}</code>',
         threads_no_recent: '<b>No recent threads.</b>',
         threads_recent_title: '<b>Recent threads</b>',
@@ -311,15 +311,15 @@ const MESSAGES = {
         threads_filter: 'Filter: <code>{searchTerm}</code>',
         threads_range: 'Showing {start}-{end}',
         threads_filter_cleared_short: 'Filter cleared',
-        button_prev_page: 'Prev',
-        button_next_page: 'Next',
-        button_clear_filter: 'Clear filter',
-        button_recent_threads: 'Recent',
-        button_archived_threads: 'Archived',
-        button_thread_rename: 'Rename',
-        button_thread_watch: 'Watch',
-        button_thread_archive: 'Archive/Delete',
-        button_thread_unarchive: 'Unarchive',
+        button_prev_page: '⬅️ Prev',
+        button_next_page: '➡️ Next',
+        button_clear_filter: '🧹 Clear',
+        button_recent_threads: '🕘 Recent',
+        button_archived_threads: '🗄️ Archived',
+        button_thread_rename: '✏️ Rename',
+        button_thread_watch: '👀 Watch',
+        button_thread_archive: '🗑️ Archive/Delete',
+        button_thread_unarchive: '♻️ Unarchive',
         threads_current: 'Current: <b>{title}</b>',
         where_no_thread_bound: 'No thread is currently bound.',
         where_send_message_or_new: 'Send a message or use /new.',
@@ -368,8 +368,8 @@ const MESSAGES = {
         active_turn_message_mode_steer: 'Steer current turn',
         active_turn_message_mode_queue: 'Queue next turn',
         button_fast_on: '⚡ Fast: on',
-        button_fast_off: 'Fast: off',
-        button_fast_unsupported: 'Fast unsupported',
+        button_fast_off: '⚪ Fast: off',
+        button_fast_unsupported: '⛔ Fast unsupported',
         access_preset_read_only: 'Read-only',
         access_preset_default: 'Default',
         access_preset_full_access: 'Full access',
@@ -504,10 +504,10 @@ const MESSAGES = {
         permission_read_paths: 'Read paths: {value}',
         permission_write_paths: 'Write paths: {value}',
         permission_entries: 'File entries: {value}',
-        button_accept: 'Accept',
-        button_decline: 'Decline',
-        button_cancel: 'Cancel',
-        button_create_dir: 'Create',
+        button_accept: '✅ Accept',
+        button_decline: '🚫 Decline',
+        button_cancel: '✖️ Cancel',
+        button_create_dir: '📁 Create',
         thread_name_updated: 'Thread renamed: {name}',
         thread_archived_notification: 'Thread archived: {threadId}',
         thread_unarchived_notification: 'Thread unarchived: {threadId}',
@@ -694,10 +694,10 @@ const MESSAGES = {
         auth_add_cancelled: '新 auth 登录已取消，已恢复之前的 auth。',
         auth_add_reverted: '已恢复之前的 auth。',
         auth_add_missing_file: '登录已完成，但没有创建新的 auth 文件：{value}',
-        button_login_device: '设备登录',
-        button_auth_reload: '重载 auth',
-        button_auth_enable: '启用',
-        button_auth_disable: '禁用',
+        button_login_device: '🔑 设备登录',
+        button_auth_reload: '🔄 重载 auth',
+        button_auth_enable: '✅ 启用',
+        button_auth_disable: '⏸️ 禁用',
         another_turn_running: '已经有一个回复在进行中。请先等待，或使用 /interrupt、/takeover、/queue。',
         working: '处理中...',
         usage_open: '用法：/open <编号>',
@@ -841,16 +841,16 @@ const MESSAGES = {
         approval_decision_accept: '允许',
         approval_decision_session: '本会话内允许',
         approval_decision_deny: '拒绝',
-        button_allow: '允许',
-        button_allow_session: '本会话允许',
-        button_deny: '拒绝',
-        button_interrupt: '中断',
-        button_permissions: '权限',
-        button_models: '模型',
-        button_threads: '线程',
-        button_reveal: '打开',
-        button_auto: '自动',
-        button_new_thread: '新建',
+        button_allow: '✅ 允许',
+        button_allow_session: '✅ 本会话',
+        button_deny: '🚫 拒绝',
+        button_interrupt: '⏹️ 中断',
+        button_permissions: '🛡️ 权限',
+        button_models: '🤖 模型',
+        button_threads: '🧵 线程',
+        button_reveal: '↗️ 打开',
+        button_auto: '⚙️ 自动',
+        button_new_thread: '➕ 新建',
         threads_no_matches: '<b>没有匹配的线程</b>\n<code>{searchTerm}</code>',
         threads_no_recent: '<b>暂无最近线程。</b>',
         threads_recent_title: '<b>最近线程</b>',
@@ -859,15 +859,15 @@ const MESSAGES = {
         threads_filter: '筛选：<code>{searchTerm}</code>',
         threads_range: '显示第 {start}-{end} 条',
         threads_filter_cleared_short: '已清除筛选',
-        button_prev_page: '上一页',
-        button_next_page: '下一页',
-        button_clear_filter: '清除筛选',
-        button_recent_threads: '最近线程',
-        button_archived_threads: '已归档',
-        button_thread_rename: '重命名',
-        button_thread_watch: '观察',
-        button_thread_archive: '归档/删除',
-        button_thread_unarchive: '取消归档',
+        button_prev_page: '⬅️ 上一页',
+        button_next_page: '➡️ 下一页',
+        button_clear_filter: '🧹 清除',
+        button_recent_threads: '🕘 最近线程',
+        button_archived_threads: '🗄️ 已归档',
+        button_thread_rename: '✏️ 重命名',
+        button_thread_watch: '👀 观察',
+        button_thread_archive: '🗑️ 归档/删除',
+        button_thread_unarchive: '♻️ 取消归档',
         threads_current: '当前：<b>{title}</b>',
         where_no_thread_bound: '当前没有绑定线程。',
         where_send_message_or_new: '直接发一条消息，或者使用 /new。',
@@ -916,8 +916,8 @@ const MESSAGES = {
         active_turn_message_mode_steer: '引导当前回复',
         active_turn_message_mode_queue: '排队到下一轮',
         button_fast_on: '⚡ Fast：开',
-        button_fast_off: 'Fast：关',
-        button_fast_unsupported: 'Fast 不支持',
+        button_fast_off: '⚪ Fast：关',
+        button_fast_unsupported: '⛔ Fast 不支持',
         access_preset_read_only: '只读',
         access_preset_default: '默认',
         access_preset_full_access: '完全访问',
@@ -1052,10 +1052,10 @@ const MESSAGES = {
         permission_read_paths: '可读路径：{value}',
         permission_write_paths: '可写路径：{value}',
         permission_entries: '文件条目：{value}',
-        button_accept: '接受',
-        button_decline: '拒绝',
-        button_cancel: '取消',
-        button_create_dir: '新建',
+        button_accept: '✅ 接受',
+        button_decline: '🚫 拒绝',
+        button_cancel: '✖️ 取消',
+        button_create_dir: '📁 新建',
         thread_name_updated: '线程已重命名：{name}',
         thread_archived_notification: '线程已归档：{threadId}',
         thread_unarchived_notification: '线程已取消归档：{threadId}',

package/docs/zh/agent-assisted-install.md

@@ -0,0 +1,83 @@
+# Agent 辅助安装
+
+如果目标电脑上已经有能执行 shell、读写文件、检查服务状态的编码 agent，优先用这条路径。它比手动一步步复制命令更快，也更容易发现本机环境里的阻塞点。
+
+适合使用 Codex、OpenClaw、QwenPaw、Hermes、OpenCode、Kimi CLI，或者任何可以在目标机器上运行命令的 agent。
+
+## 你需要准备
+
+先准备这几个值：
+
+- `TG_BOT_TOKEN`：从 `@BotFather` 拿到的 Telegram bot token
+- `TG_ALLOWED_USER_ID`：你的 Telegram 数字用户 ID
+- `DEFAULT_CWD`：希望 Codex 默认工作的目录
+
+后续再配置群组或话题时才需要：
+
+- `TG_ALLOWED_CHAT_ID`
+- `TG_ALLOWED_TOPIC_ID`
+
+第一次请先用 Telegram 私聊跑通。群组和话题模式等私聊稳定后再开。
+
+## 复制给 agent 的安装提示词
+
+把下面这段发给目标电脑上的 agent：
+
+```text
+请在这台机器上安装 FoxClaw。
+
+发布包：
+@foxden-app/foxclaw
+
+先使用 Telegram 私聊模式。除非我明确提供 TG_ALLOWED_CHAT_ID 或 TG_ALLOWED_TOPIC_ID，否则不要配置群组/话题模式。
+
+必需配置：
+TG_BOT_TOKEN=<把 token 粘贴在这里>
+TG_ALLOWED_USER_ID=<把 Telegram 数字用户 ID 粘贴在这里>
+DEFAULT_CWD=<把绝对工作目录粘贴在这里>
+
+任务：
+1. 先检查机器环境。如果已经存在 FoxClaw 或旧的 telegram-codex-app-bridge 服务，先报告再改服务。
+2. 确保 Node.js 24+ 可用；如果没有，请用 nvm 安装或切到 Node 24。
+3. 确保 Codex CLI 存在并且已经登录。如果需要登录，停下来告诉我具体要执行什么。
+4. 用 npm install -g @foxden-app/foxclaw@latest 安装或升级 FoxClaw。
+5. 运行 foxclaw init，然后写入 ~/.foxclaw/.env。不要打印或提交 bot token。
+6. 运行 foxclaw doctor。
+7. 用 foxclaw start 启动 FoxClaw。
+8. 让我在 Telegram bot 里发送 /help 和 /status。
+9. 验证最终状态：
+   - Linux 上 foxclaw.service 处于 active/enabled
+   - 如果存在旧 telegram-codex-app-bridge.service，它应当 inactive/disabled
+   - foxclaw status 可以正常输出
+10. 汇报执行过的命令、最终状态和后续看日志的命令。请隐藏 TG_BOT_TOKEN，不要打印完整 token 或完整 .env。
+```
+
+## 旧项目迁移提示词
+
+如果目标机器还在跑 `telegram-codex-app-bridge`，用这段：
+
+```text
+请把这台机器从 telegram-codex-app-bridge 迁移到 FoxClaw。
+
+新发布包：
+@foxden-app/foxclaw
+
+请执行：
+1. 修改前先检查现有安装方式、服务文件和运行目录。
+2. 如果存在 telegram-codex-app-bridge.service，停止并禁用它。
+3. 如果 ~/.foxclaw 不存在而 ~/.telegram-codex-app-bridge 存在，把旧目录复制到 ~/.foxclaw。
+4. 用 npm install -g @foxden-app/foxclaw@latest 安装或升级 FoxClaw。
+5. 如果 ~/.foxclaw/.env 不存在，运行 foxclaw init；然后检查配置是否完整。
+6. 运行 foxclaw doctor。
+7. 用 foxclaw start 安装或重启 FoxClaw 服务。
+8. 验证 foxclaw.service 正常运行，旧 telegram-codex-app-bridge.service 已停止或禁用。
+9. 汇报最终状态和阻塞点。请隐藏 TG_BOT_TOKEN，不要打印完整 token 或完整 .env。
+```
+
+## 安全注意事项
+
+- 不要把 bot token 粘贴到公开 issue、公开聊天或代码仓库。
+- 不要提交 `.env`。
+- 汇报结果时隐藏 `TG_BOT_TOKEN`。
+- 第一次安装不要把 `/`、整个 `/Users`、整个 `/home` 或完整 home 目录设为 `DEFAULT_CWD`。
+- 日常启动用 `foxclaw start`；只有排障时才用前台模式 `foxclaw serve`。

package/docs/zh/foxclaw-skill.md

@@ -0,0 +1,24 @@
+# FoxClaw Skill 中文说明
+
+仓库内置的 `skills/foxclaw` 是给 Codex 使用的安装技能。它的用途是让 Codex 在本机或远程 Mac 上自动完成 FoxClaw bootstrap，包括写 `.env`、安装依赖、构建、跑 `doctor`、安装 launchd 服务，并引导你完成第一次 Telegram 消息验证。
+
+## 适合什么时候用
+
+- 你想让 Codex 通过 SSH 帮另一台 Mac 安装 FoxClaw。
+- 你希望 agent 先检查环境，再决定如何安装 Node.js 24、Codex CLI 和 FoxClaw。
+- 你不想手动复制每一步安装命令，但愿意提供 Telegram bot token、用户 ID 和默认工作目录。
+
+## 基本流程
+
+1. 准备 `TG_BOT_TOKEN`、`TG_ALLOWED_USER_ID` 和 `DEFAULT_CWD`。
+2. 让 Codex 使用 `skills/foxclaw`。
+3. 如果是远程机器，提供 SSH 目标。
+4. 让 Codex 执行安装、写配置、跑 `foxclaw doctor`。
+5. 启动服务后，在 Telegram bot 里发送 `/help` 和 `/status` 验证。
+
+## 注意事项
+
+- 不要让 agent 把完整 bot token 打印到日志或提交到仓库。
+- 第一次请先用私聊模式跑通。
+- 不要把整个 home 目录或根目录作为首次 `DEFAULT_CWD`。
+- 只有在 `doctor` 通过、服务已启动、Telegram 首条消息验证通过后，才算安装完成。

package/docs/zh/install-for-beginners.md

@@ -0,0 +1,295 @@
+# 新手安装指南
+
+这份指南面向第一次安装 FoxClaw 的用户。你只需要能打开终端、复制命令、编辑一个配置文件，不需要提前熟悉 Node.js、Telegram bot 或 Codex CLI。
+
+FoxClaw 跑在你的电脑上。手机发消息给 Telegram bot，bot 把消息交给 FoxClaw，FoxClaw 再控制本机 Codex。整个过程不需要公网服务器。
+
+如果这台电脑上已经有 Codex、OpenClaw、QwenPaw、Hermes、OpenCode、Kimi CLI 这类能跑 shell 的 agent，优先看 [Agent 辅助安装](./agent-assisted-install.md)。
+
+开始前先记住：
+
+- 第一次先用 Telegram 私聊，不要先配群组。
+- 不要把 bot token 发给不信任的人。
+- 第一次不要把 `/`、`/Users`、`/home` 或整个 home 目录设为 `DEFAULT_CWD`。
+- 日常启动用 `foxclaw start`，前台模式只用于排障。
+
+## 1. 准备
+
+你需要：
+
+- 一台可以持续开机的 macOS 或 Linux 电脑
+- 一个 Telegram 账号
+- 一个已可使用的 Codex 账号
+- 一个 Codex 可以工作的目录，例如 `~/Projects` 或 `~/Desktop`
+- 第一次安装大约 10-20 分钟
+
+## 2. 安装 Node.js 24
+
+FoxClaw 需要 Node.js 24，因为它使用 Node 内置 SQLite 运行时。
+
+如果已经安装 Node 24，这条命令会输出 `v24...`：
+
+```bash
+node -v
+```
+
+如果不是 Node 24，推荐用 `nvm` 安装：
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+nvm install 24
+nvm use 24
+node -v
+npm -v
+```
+
+如果 `node -v` 仍然显示旧版本，关闭终端，重新打开后运行：
+
+```bash
+nvm use 24
+```
+
+## 3. 安装并登录 Codex
+
+FoxClaw 不创建 Codex 账号，它使用这台电脑上已经登录的 Codex CLI。
+
+如果还没有安装 Codex CLI：
+
+```bash
+npm install -g @openai/codex
+```
+
+如果遇到 `EACCES`、`EPERM` 或 `permission denied`，不要反复加 `sudo` 硬装，先看 [故障排查](./troubleshooting.md)。
+
+登录 Codex：
+
+```bash
+codex login
+```
+
+检查命令是否存在：
+
+```bash
+codex --version
+```
+
+`codex --version` 只能证明命令存在。要确认认证可用，直接启动 Codex 并发一个小请求：
+
+```bash
+codex
+```
+
+然后输入：
+
+```text
+Say ready and exit.
+```
+
+如果你的 CLI 支持 `codex login status`，也可以用它辅助检查；真正可靠的验证是 Codex 能正常回答一个普通请求。
+
+## 4. 创建 Telegram Bot
+
+1. 打开 Telegram。
+2. 搜索 `@BotFather`。
+3. 发送 `/newbot`。
+4. 按提示选择 bot 名称。
+5. 复制 bot token，它看起来像 `123456789:AA...`。
+
+请保存好这个 token。拿到 token 的人可以控制这个 bot。
+
+## 5. 获取 Telegram 数字用户 ID
+
+FoxClaw 只接受一个已配置用户的消息。
+
+最简单的方式：
+
+1. 打开 Telegram。
+2. 搜索 `@userinfobot`。
+3. 给它发任意消息或点击 Start。
+4. 复制数字 `Id`。
+
+请使用数字 ID，不要填 `@username`。
+
+## 6. 安装 FoxClaw
+
+用 npm 安装发布包：
+
+```bash
+npm install -g @foxden-app/foxclaw
+foxclaw init
+```
+
+这会创建默认配置文件 `~/.foxclaw/.env`。
+
+如果你用 pnpm：
+
+```bash
+pnpm add -g @foxden-app/foxclaw
+foxclaw init
+```
+
+## 7. 填写 `.env`
+
+用简单编辑器打开配置：
+
+```bash
+nano ~/.foxclaw/.env
+```
+
+第一次私聊模式只需要重点填写这些值：
+
+```dotenv
+TG_BOT_TOKEN=123456789:replace_with_your_bot_token
+TG_ALLOWED_USER_ID=123456789
+TG_ALLOWED_CHAT_ID=
+TG_ALLOWED_TOPIC_ID=
+DEFAULT_CWD=/absolute/path/to/a/folder
+DEFAULT_APPROVAL_POLICY=on-request
+DEFAULT_SANDBOX_MODE=workspace-write
+```
+
+`TG_ALLOWED_CHAT_ID=` 和 `TG_ALLOWED_TOPIC_ID=` 第一次保持为空，不要删掉这两行；留空表示私聊模式。
+
+`DEFAULT_CWD` 必须是真实存在的目录，例如：
+
+```dotenv
+DEFAULT_CWD=/Users/alice/Desktop
+DEFAULT_CWD=/home/alice/projects
+```
+
+在 `nano` 中按 `Ctrl+O`、回车、`Ctrl+X` 保存退出。
+
+## 8. 运行检查
+
+执行：
+
+```bash
+foxclaw doctor
+```
+
+理想情况下会看到：
+
+```text
+[OK] node >= 24
+[OK] codex cli available
+[OK] telegram bot token configured
+[OK] telegram allowed user configured
+[OK] default cwd exists
+```
+
+如果看到 `[FAIL]`，先看 [故障排查](./troubleshooting.md)。
+
+## 9. 启动 FoxClaw
+
+启动或重启后台服务：
+
+```bash
+foxclaw start
+```
+
+这个命令可以重复执行。它会跑检查，并按当前系统安装或重启后台服务。
+
+打开你的 Telegram bot，先发：
+
+```text
+/help
+```
+
+如果 bot 回复了，再发：
+
+```text
+/status
+```
+
+然后试一个普通请求：
+
+```text
+List the files in the current working directory.
+```
+
+还可以试：
+
+```text
+/setup
+```
+
+```text
+List files in DEFAULT_CWD.
+```
+
+```text
+Create a short README-style summary of this folder.
+```
+
+```text
+/interrupt
+```
+
+## 10. 服务命令
+
+Linux 上 `foxclaw start` 管理用户级 systemd 服务。查看状态：
+
+```bash
+systemctl --user status foxclaw.service
+journalctl --user -u foxclaw.service -f
+```
+
+如果希望重启后未登录也能启动用户服务：
+
+```bash
+loginctl enable-linger "$USER"
+```
+
+macOS 上 `foxclaw start` 管理 launchd，并在你登录后启动 FoxClaw。
+
+前台调试时，先停后台服务，再运行 `foxclaw serve`。
+
+## 11. 日常维护
+
+查看状态：
+
+```bash
+foxclaw status
+```
+
+修改 `.env` 后重启：
+
+```bash
+foxclaw start
+```
+
+停止 Linux 服务：
+
+```bash
+systemctl --user stop foxclaw.service
+```
+
+卸载 Linux 服务：
+
+```bash
+foxclaw uninstall-systemd
+```
+
+以后升级 FoxClaw：
+
+```bash
+npm install -g @foxden-app/foxclaw@latest
+foxclaw start
+```
+
+## 从旧项目名迁移
+
+如果这台机器仍在运行 `telegram-codex-app-bridge`，迁移一次即可：
+
+```bash
+systemctl --user disable --now telegram-codex-app-bridge.service 2>/dev/null || true
+test -e ~/.foxclaw || cp -a ~/.telegram-codex-app-bridge ~/.foxclaw
+npm install -g @foxden-app/foxclaw@latest
+foxclaw init
+foxclaw doctor
+foxclaw start
+```
+
+如果 `~/.foxclaw/.env` 已经存在，`foxclaw init` 不会覆盖它。