@foxden-app/foxclaw 0.2.6 → 0.3.0

package/docs/user-manual.md

@@ -0,0 +1,460 @@
+# FoxClaw User Manual
+
+FoxClaw wraps your local Codex into a phone-controllable service. Telegram or Weixin provides the chat surface, FoxClaw handles auth, thread binding, approvals, setup panels, and account switching, and your local `codex app-server` performs the actual coding work.
+
+Typical flow:
+
+```text
+Telegram/Weixin on your phone
+  -> FoxClaw bot
+  -> local FoxClaw service
+  -> codex app-server
+  -> DEFAULT_CWD or the current thread cwd
+```
+
+Your code, shell access, Codex auth, and runtime state stay on the host machine. For a first install, use Telegram private chat before configuring groups, topics, or Weixin.
+
+## 1. Full Setup
+
+### 1.1 Install Node.js 24
+
+FoxClaw requires Node.js 24. Check first:
+
+```bash
+node -v
+```
+
+If this is not `v24...`, install Node 24 with `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
+```
+
+### 1.2 Install And Log In To Codex
+
+FoxClaw does not create a Codex account. It uses the Codex CLI already logged in on this machine.
+
+```bash
+npm install -g @openai/codex
+codex login
+codex --version
+```
+
+`codex --version` only proves the command exists. To verify auth, start Codex and run a tiny request:
+
+```bash
+codex
+```
+
+Then type:
+
+```text
+Say ready and exit.
+```
+
+If Codex answers normally, FoxClaw has a working execution backend.
+
+### 1.3 Create A Telegram Bot
+
+1. Open Telegram.
+2. Search for `@BotFather`.
+3. Send `/newbot`.
+4. Follow the prompts to choose a bot name and username.
+5. Copy the bot token. It looks like `123456789:AA...`.
+
+Keep this token private. Anyone with the token can control the bot.
+
+### 1.4 Get Your Numeric Telegram User ID
+
+FoxClaw only responds to the user configured in `TG_ALLOWED_USER_ID`.
+
+1. Open Telegram.
+2. Search for `@userinfobot`.
+3. Send any message or press Start.
+4. Copy the numeric `Id`.
+
+Use the number, not your `@username`.
+
+### 1.5 Install FoxClaw
+
+If you use pnpm for global packages:
+
+```bash
+pnpm add -g @foxden-app/foxclaw
+foxclaw init
+```
+
+If you use npm:
+
+```bash
+npm install -g @foxden-app/foxclaw
+foxclaw init
+```
+
+Both install the same published npm package. Use one global package manager consistently on a machine to avoid multiple versions in PATH.
+
+### 1.6 Fill In The Config
+
+The default config file is `~/.foxclaw/.env`:
+
+```bash
+$EDITOR ~/.foxclaw/.env
+```
+
+Minimum private-chat config:
+
+```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/workspace
+DEFAULT_APPROVAL_POLICY=on-request
+DEFAULT_SANDBOX_MODE=workspace-write
+```
+
+Fields:
+
+- `TG_BOT_TOKEN`: the token from `@BotFather`.
+- `TG_ALLOWED_USER_ID`: your numeric Telegram user id.
+- `TG_ALLOWED_CHAT_ID`: leave empty for the first private-chat setup.
+- `TG_ALLOWED_TOPIC_ID`: leave empty unless binding a Telegram topic.
+- `DEFAULT_CWD`: the default directory where Codex works; it must exist.
+- `DEFAULT_APPROVAL_POLICY`: `on-request` is a good first value.
+- `DEFAULT_SANDBOX_MODE`: `workspace-write` is a good first value.
+
+### 1.7 Check And Start
+
+```bash
+foxclaw doctor
+foxclaw start
+foxclaw status
+```
+
+Linux service logs:
+
+```bash
+systemctl --user status foxclaw.service
+journalctl --user -u foxclaw.service -f
+```
+
+On macOS, `foxclaw start` manages launchd. For foreground debugging, stop the background service and run:
+
+```bash
+foxclaw serve
+```
+
+### 1.8 First Telegram Test
+
+Open a private chat with your bot and send:
+
+```text
+/help
+```
+
+```text
+/status
+```
+
+```text
+/setup
+```
+
+Then send a normal request:
+
+```text
+List files in DEFAULT_CWD.
+```
+
+If Codex replies, the basic path is working.
+
+## 2. Groups And Topics
+
+Private chat is the safest first mode. Configure a group or topic only after private chat works.
+
+```dotenv
+TG_ALLOWED_CHAT_ID=-1001234567890
+TG_ALLOWED_TOPIC_ID=42
+```
+
+- Leave `TG_ALLOWED_CHAT_ID` empty for private chat only.
+- Set only `TG_ALLOWED_CHAT_ID` to allow one group as the default conversation scope.
+- Set both values to bind one topic.
+- Private chat still works for `TG_ALLOWED_USER_ID` when a group is configured.
+
+Find group or topic IDs:
+
+1. Stop FoxClaw.
+2. Send a message in the target group or topic.
+3. Open:
+
+   ```text
+   https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
+   ```
+
+4. Use `message.chat.id` as `TG_ALLOWED_CHAT_ID`.
+5. Use `message.message_thread_id` as `TG_ALLOWED_TOPIC_ID`.
+
+If FoxClaw is still running, it may consume the update before you inspect it.
+
+For group messages:
+
+- Add the bot to the group.
+- Disable privacy mode in `@BotFather`.
+- Promote the bot to administrator.
+- Test with a plain natural-language message, not only `/status@botname`.
+
+## 3. Commands
+
+### 3.1 `/help`
+
+`/help` returns the available command list. The top entries are pinned:
+
+```text
+/help
+/setup
+/status
+/threads [query]
+/auth
+```
+
+Later commands are sorted by recent usage. Plain text, photos, and files continue the currently bound thread; if no thread is bound, FoxClaw creates one.
+
+### 3.2 `/status`, `/account`, `/quota`
+
+- `/status`: FoxClaw, app-server, current thread binding, model, access, and Codex usage summary.
+- `/account`: current Codex account.
+- `/quota`: Codex usage and quota window.
+
+### 3.3 `/config`, `/requirements`, `/provider`
+
+- `/config`: reads the Codex config summary for the bound thread cwd or `DEFAULT_CWD`, including `model`, `approval_policy`, `sandbox_mode`, and `service_tier`.
+- `/requirements`: shows app-server constraints such as allowed approval, sandbox, and web search modes.
+- `/provider`: shows the current Codex provider summary.
+
+These are useful when the phone-side model, permission, or provider behavior does not match what you expected.
+
+## 4. The `/setup` Panel
+
+`/setup` is one of the main mobile panels. Settings are scoped to the chat, so private chat, group, and topic can use different settings.
+
+It controls:
+
+- Model: server default, or a model returned by app-server.
+- Reasoning effort: for example `low`, `medium`, `high`, or `xhigh`, depending on model support.
+- Fast tier: available when supported by the selected model.
+- Access: `read-only`, `default`, or `full-access`.
+- Mode: `Agent` or `Plan`.
+- Active turn behavior: steer the current turn, or queue the message for the next turn.
+
+Telegram renders the HTML and buttons. This text block approximates the real panel:
+
+```text
+Session preferences
+Current: gpt-5.5 · high · fast=off · default · Agent · Steer current turn
+Focus: Model
+
+Model: gpt-5.5
+Effort: high
+Fast: off
+Access: Default (on-request / workspace-write)
+Mode: Agent
+Active turn: Steer current turn
+
+[Auto]           [gpt-5.5]
+[low] [medium] [high]
+[⚡ Fast on]     [Fast off]
+[👁️ Read-only]  [🛡️ Default]  [🔓 Full access]
+[Agent]          [📝 Plan]
+[Steer current turn] [Queue next turn]
+```
+
+Command aliases:
+
+- `/model <model|default>`: switch model.
+- `/effort <effort|default>`: switch reasoning effort.
+- `/permissions [read-only|default|full-access]`: switch access preset.
+- `/mode [default|plan]`: switch Agent/Plan.
+- `/active <steer|queue>`: control how new messages behave during an active turn.
+
+## 5. Threads And Watch
+
+FoxClaw chats are bound to Codex threads. Once you open a thread from your phone, normal messages continue that thread.
+
+Common commands:
+
+- `/threads [query]`: list recent threads, optionally filtered by keyword.
+- `/threads archived [query]`: list archived threads.
+- `/open <n>`: open item n from the latest `/threads` list and bind this chat.
+- `/new [cwd]`: create a new thread in a cwd, or in the default cwd.
+- `/where`: show the current thread, cwd, and settings.
+- `/rename <name>`: rename the current thread.
+- `/archive`: archive the current thread.
+- `/interrupt`: interrupt the current running turn.
+
+Threads panel approximation:
+
+```text
+Recent threads
+Tap a button below to open or manage a thread.
+Showing 1-5
+Current: fix auth rotation
+~/Projects/foxclaw | 3 minutes ago | idle
+
+[🧵 1. fix auth rotation]
+[✏️] [👀] [🗑️] [➕]
+
+[🧵 2. polish README copy]
+[✏️] [👀] [🗑️] [➕]
+
+[➕ New]
+[➡️ Next]
+[🗄️ Archived]
+```
+
+### `/watch`
+
+`/watch` observes a thread even if the task was started elsewhere. A common workflow is starting a long Codex CLI task at your desk, then watching it from your phone.
+
+Usage:
+
+- `/watch`: watch the currently bound thread.
+- `/watch <n>`: watch item n from the latest `/threads` list.
+- `/unwatch`: stop watching.
+
+Watch mode mirrors live turn progress and approval requests. The watching chat is read-only for normal prompts during the observed turn. Send `/unwatch` before starting a new prompt from that chat, or wait for the turn to finish.
+
+## 6. Codex Login And Auth Rotation
+
+This is a key FoxClaw feature. Codex auth is usually stored at `~/.codex/auth.json`. FoxClaw stores multiple accounts as candidate files and switches which candidate the active `auth.json` points to.
+
+### 6.1 File Format
+
+Candidate files live in the Codex auth directory, usually `~/.codex/`. If `CODEX_AUTH_DIR` is set, FoxClaw uses that directory.
+
+Recommended layout:
+
+```text
+~/.codex/
+  auth.json -> /home/alice/.codex/auth.json_personal
+  auth.json_personal
+  auth.json_team
+  auth.json_plus_trial
+```
+
+FoxClaw recognizes candidate names in these forms:
+
+- `auth.json_<name>`
+- `auth.json.<name>`
+- `auth.json-<name>`
+
+`auth.json` is what Codex currently uses. When switching accounts, FoxClaw points `auth.json` at one candidate. Candidate contents are Codex-generated JSON; FoxClaw treats those private fields as opaque and you should not hand-write them.
+
+If you already have a working `auth.json`, you can save it as a candidate:
+
+```bash
+cp -L ~/.codex/auth.json ~/.codex/auth.json_personal
+```
+
+The safer path is adding candidates from the phone with `/auth add <name>`.
+
+### 6.2 Login Commands
+
+- `/login_device`: starts ChatGPT device login for the current `auth.json`. FoxClaw sends a login URL, short code, login id, and cancel command.
+- `/login_cancel [id]`: cancels an in-progress device login.
+- `/logout confirm`: logs out the current Codex account.
+- `/auth add <name>`: adds a candidate account. For example, `/auth add work` creates `auth.json_work` and starts device login.
+
+`/auth add <name>` flow:
+
+1. FoxClaw prepares `auth.json_<name>`.
+2. It temporarily points `auth.json` at that candidate.
+3. It restarts app-server so Codex writes into the new candidate.
+4. It sends the login URL and short code.
+5. You complete login in the browser.
+6. The candidate appears in `/auth`.
+
+If the login is cancelled or fails, FoxClaw tries to restore the previous auth target and remove the unfinished candidate.
+
+### 6.3 The `/auth` Panel
+
+`/auth` lists candidate accounts, the current account, and the auth directory. It also provides buttons for switching, disabling, login, and reload.
+
+Approximation:
+
+```text
+Codex auth
+Current: auth.json_personal
+Auth dir: /home/alice/.codex
+Candidates: 2
+1. auth.json_personal * [enabled]
+2. auth.json_team [enabled]
+
+[✅ auth.json_personal] [✅]
+[🔐 auth.json_team]     [✅]
+[🛡️ Access]             [🔑 Login]
+[🔄 Reload auth]
+```
+
+The right-side `✅` / `⏸️` button shows the current state. Tapping it toggles enabled/disabled, and the refreshed list shows the new state.
+
+Equivalent commands:
+
+- `/auth` or `/auth list`: show candidates.
+- `/auth use <n>`: switch to candidate n and restart app-server.
+- `/auth enable <n>`: let candidate n participate in auto-rotation.
+- `/auth disable <n>`: skip candidate n during auto-rotation.
+- `/auth reload` or `/auth_reload`: restart app-server and reload the current `auth.json`.
+
+If active turns, pending approvals, pending user inputs, or MCP elicitations exist, FoxClaw refuses manual auth switching to avoid changing accounts mid-request.
+
+### 6.4 How Auto-Rotation Works
+
+When Codex reports a usage limit, missing login, expired auth, or similar auth error, FoxClaw tries to rotate automatically:
+
+1. Record the failed candidate.
+2. Select the next enabled candidate that has not already failed in this retry cycle.
+3. Point `auth.json` at that candidate.
+4. Restart `codex app-server` so the new auth is loaded.
+5. Retry the failed request with the new account.
+
+Disabled candidates are skipped. If no candidate is available, FoxClaw reports the error back to the phone and stops retrying.
+
+Example account layout:
+
+```text
+auth.json_personal     # primary account
+auth.json_team         # Team or work account
+auth.json_plus_trial   # trial account
+auth.json_backup       # backup account, enable or disable as needed
+```
+
+## 7. Daily Workflow
+
+1. Enter the project directory on your computer and make sure Codex works.
+2. From your phone, send `/new /home/alice/Projects/app`, or use `/threads` to open an existing thread.
+3. Use `/setup` to choose model, effort, access, and Agent/Plan mode.
+4. Send a task, for example: `Fix the failing test and run the related test suite.`
+5. Step away from the computer and watch progress on your phone.
+6. Approve or deny command and file-change requests from Telegram.
+7. To observe a task started from Codex CLI, use `/threads`, then tap `👀` or send `/watch <n>`.
+8. When quota is hit, let `/auth` candidates auto-rotate, or switch manually with `/auth use <n>`.
+
+## 8. Safety
+
+- Do not share `TG_BOT_TOKEN`, `~/.codex/auth.json*`, or `.env`.
+- Do not use `/`, `/home`, `/Users`, or your whole home directory as the first `DEFAULT_CWD`.
+- When unsure, use `/permissions read-only` or select `Read-only` in `/setup`.
+- Group mode still only accepts `TG_ALLOWED_USER_ID`, but use trusted groups.
+- Multi-account files are Codex login credentials. Treat backups and sync tools accordingly.
+
+## 9. More Reading
+
+- [Beginner Install Guide](./install-for-beginners.md)
+- [Agent-Assisted Install](./agent-assisted-install.md)
+- [Troubleshooting](./troubleshooting.md)

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 首条消息验证通过后，才算安装完成。