@foxden-app/foxclaw 0.2.6 → 0.2.7

package/docs/troubleshooting.md

@@ -1,236 +1,236 @@
-# Troubleshooting
-
-Start with these commands:
-
-```bash
-foxclaw doctor
-foxclaw status
-```
-
-If FoxClaw is installed as a Linux user service, also check:
-
-```bash
-systemctl --user status foxclaw.service
-journalctl --user -u foxclaw.service -f
-```
-
-## Doctor Failures
-
-| Symptom | Meaning | Fix |
-| --- | --- | --- |
-| `[FAIL] node >= 24` | Your current shell is using an older Node.js. | Run `nvm install 24 && nvm use 24`, then rerun `foxclaw doctor`. If the service uses old Node, reinstall it from a Node 24 shell with `foxclaw start`. |
-| `[FAIL] codex cli available` | The `codex` command is not in PATH. | Install Codex CLI or fix PATH, then confirm `codex --version` works. |
-| `[FAIL] telegram bot token configured` | `TG_BOT_TOKEN` is missing from `.env`. | Copy the token from `@BotFather` into `.env`. |
-| `[FAIL] telegram allowed user configured` | `TG_ALLOWED_USER_ID` is missing from `.env`. | Get your numeric id from `@userinfobot` and add it to `.env`. |
-| `[FAIL] default cwd exists` | `DEFAULT_CWD` points to a folder that does not exist. | Create the folder or change `DEFAULT_CWD` to an existing absolute path. |
-
-## Node Or npm Is Missing
-
-If you see `node: command not found` or `npm: command not found`, install Node.js 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
-npm -v
-```
-
-If it still fails, close the terminal, open a new one, and run:
-
-```bash
-nvm use 24
-```
-
-## npm Permission Errors
-
-If `npm install -g @openai/codex` fails with `EACCES`, `EPERM`, or `permission denied`, your global npm directory is not writable by your user.
-
-Recommended fix: use Node through `nvm`, then install again:
-
-```bash
-nvm install 24
-nvm use 24
-npm install -g @openai/codex
-```
-
-Avoid `sudo npm install -g ...` unless you already understand how your Node installation is managed. Mixing `sudo`, system Node, and `nvm` is a common source of broken PATHs.
-
-If `codex` installs but FoxClaw still cannot find it, locate the binary:
-
-```bash
-command -v codex
-```
-
-Then put the absolute path in `.env`:
-
-```dotenv
-CODEX_CLI_BIN=/absolute/path/to/codex
-```
-
-## Bot Does Not Reply
-
-Check these in order:
-
-1. Make sure FoxClaw is running:
-
-   ```bash
-   foxclaw status
-   ```
-
-2. Try private chat first. Open your bot directly and send:
-
-   ```text
-   /help
-   ```
-
-3. Confirm `TG_ALLOWED_USER_ID` is your numeric Telegram id, not your `@username`.
-
-4. Confirm the bot token in `.env` belongs to the bot you are messaging.
-
-5. Restart after changing `.env`:
-
-   ```bash
-   foxclaw start
-   ```
-
-   If running foreground mode, stop with `Ctrl+C` and run `foxclaw serve` again.
-
-## Group Messages Do Not Work
-
-Private chat is the easiest mode. For groups and topics:
-
-1. Add the bot to the group.
-2. Disable the bot's `privacy mode` in `@BotFather`.
-3. Promote the bot to administrator.
-4. Remove and re-add the bot if privacy mode was changed after it joined.
-5. Configure `TG_ALLOWED_CHAT_ID`, and optionally `TG_ALLOWED_TOPIC_ID`.
-
-Explicit commands such as `/status@botname` can work even when normal group messages are blocked by privacy mode, so verify with a plain natural-language message too.
-
-## Get Group Or Topic IDs
-
-1. Stop FoxClaw.
-2. Send a new 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.
-
-## Telegram Polling Conflict
-
-If Telegram reports conflicts or the same bot behaves strangely, two processes may be polling the same bot token.
-
-Check old and new services:
-
-```bash
-systemctl --user is-active foxclaw.service
-systemctl --user is-active telegram-codex-app-bridge.service 2>/dev/null || true
-```
-
-Stop the old service:
-
-```bash
-systemctl --user disable --now telegram-codex-app-bridge.service
-```
-
-Then restart FoxClaw:
-
-```bash
-foxclaw start
-```
-
-## Codex Or App-Server Fails
-
-FoxClaw requires local Codex auth. Check:
-
-```bash
-codex --version
-```
-
-If Codex is not logged in:
-
-```bash
-codex login
-```
-
-`codex --version` only verifies the command exists. To verify auth, run:
-
-```bash
-codex
-```
-
-Then ask:
-
-```text
-Say ready and exit.
-```
-
-If your CLI supports `codex login status`, that is also useful, but a normal successful prompt is the most reliable check.
-
-FoxClaw app-server logs are stored here by default:
-
-```bash
-tail -f ~/.foxclaw/logs/codex-app-server.log
-```
-
-Bridge logs are stored here:
-
-```bash
-tail -f ~/.foxclaw/logs/service.log
-```
-
-## Service Starts With The Wrong Node Version
-
-The systemd installer captures the `node` binary from your current PATH. If you installed the service from a shell using Node 22 or older, reinstall it from a Node 24 shell:
-
-```bash
-nvm use 24
-foxclaw start
-systemctl --user status foxclaw.service
-```
-
-The status output should show a Node 24 path in `ExecStart`.
-
-## Does It Run After Reboot?
-
-Linux user systemd:
-
-```bash
-systemctl --user is-enabled foxclaw.service
-```
-
-`enabled` means it starts with your user session. To start after reboot before login:
-
-```bash
-loginctl enable-linger "$USER"
-```
-
-macOS launchd starts FoxClaw when you log in after running:
-
-```bash
-foxclaw start
-```
-
-## Migrating From The Old Project Name
-
-If this machine still runs `telegram-codex-app-bridge`, migrate once:
-
-```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
-```
-
-If `~/.foxclaw/.env` already exists, `foxclaw init` leaves it untouched.
+# Troubleshooting
+
+Start with these commands:
+
+```bash
+foxclaw doctor
+foxclaw status
+```
+
+If FoxClaw is installed as a Linux user service, also check:
+
+```bash
+systemctl --user status foxclaw.service
+journalctl --user -u foxclaw.service -f
+```
+
+## Doctor Failures
+
+| Symptom | Meaning | Fix |
+| --- | --- | --- |
+| `[FAIL] node >= 24` | Your current shell is using an older Node.js. | Run `nvm install 24 && nvm use 24`, then rerun `foxclaw doctor`. If the service uses old Node, reinstall it from a Node 24 shell with `foxclaw start`. |
+| `[FAIL] codex cli available` | The `codex` command is not in PATH. | Install Codex CLI or fix PATH, then confirm `codex --version` works. |
+| `[FAIL] telegram bot token configured` | `TG_BOT_TOKEN` is missing from `.env`. | Copy the token from `@BotFather` into `.env`. |
+| `[FAIL] telegram allowed user configured` | `TG_ALLOWED_USER_ID` is missing from `.env`. | Get your numeric id from `@userinfobot` and add it to `.env`. |
+| `[FAIL] default cwd exists` | `DEFAULT_CWD` points to a folder that does not exist. | Create the folder or change `DEFAULT_CWD` to an existing absolute path. |
+
+## Node Or npm Is Missing
+
+If you see `node: command not found` or `npm: command not found`, install Node.js 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
+npm -v
+```
+
+If it still fails, close the terminal, open a new one, and run:
+
+```bash
+nvm use 24
+```
+
+## npm Permission Errors
+
+If `npm install -g @openai/codex` fails with `EACCES`, `EPERM`, or `permission denied`, your global npm directory is not writable by your user.
+
+Recommended fix: use Node through `nvm`, then install again:
+
+```bash
+nvm install 24
+nvm use 24
+npm install -g @openai/codex
+```
+
+Avoid `sudo npm install -g ...` unless you already understand how your Node installation is managed. Mixing `sudo`, system Node, and `nvm` is a common source of broken PATHs.
+
+If `codex` installs but FoxClaw still cannot find it, locate the binary:
+
+```bash
+command -v codex
+```
+
+Then put the absolute path in `.env`:
+
+```dotenv
+CODEX_CLI_BIN=/absolute/path/to/codex
+```
+
+## Bot Does Not Reply
+
+Check these in order:
+
+1. Make sure FoxClaw is running:
+
+   ```bash
+   foxclaw status
+   ```
+
+2. Try private chat first. Open your bot directly and send:
+
+   ```text
+   /help
+   ```
+
+3. Confirm `TG_ALLOWED_USER_ID` is your numeric Telegram id, not your `@username`.
+
+4. Confirm the bot token in `.env` belongs to the bot you are messaging.
+
+5. Restart after changing `.env`:
+
+   ```bash
+   foxclaw start
+   ```
+
+   If running foreground mode, stop with `Ctrl+C` and run `foxclaw serve` again.
+
+## Group Messages Do Not Work
+
+Private chat is the easiest mode. For groups and topics:
+
+1. Add the bot to the group.
+2. Disable the bot's `privacy mode` in `@BotFather`.
+3. Promote the bot to administrator.
+4. Remove and re-add the bot if privacy mode was changed after it joined.
+5. Configure `TG_ALLOWED_CHAT_ID`, and optionally `TG_ALLOWED_TOPIC_ID`.
+
+Explicit commands such as `/status@botname` can work even when normal group messages are blocked by privacy mode, so verify with a plain natural-language message too.
+
+## Get Group Or Topic IDs
+
+1. Stop FoxClaw.
+2. Send a new 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.
+
+## Telegram Polling Conflict
+
+If Telegram reports conflicts or the same bot behaves strangely, two processes may be polling the same bot token.
+
+Check old and new services:
+
+```bash
+systemctl --user is-active foxclaw.service
+systemctl --user is-active telegram-codex-app-bridge.service 2>/dev/null || true
+```
+
+Stop the old service:
+
+```bash
+systemctl --user disable --now telegram-codex-app-bridge.service
+```
+
+Then restart FoxClaw:
+
+```bash
+foxclaw start
+```
+
+## Codex Or App-Server Fails
+
+FoxClaw requires local Codex auth. Check:
+
+```bash
+codex --version
+```
+
+If Codex is not logged in:
+
+```bash
+codex login
+```
+
+`codex --version` only verifies the command exists. To verify auth, run:
+
+```bash
+codex
+```
+
+Then ask:
+
+```text
+Say ready and exit.
+```
+
+If your CLI supports `codex login status`, that is also useful, but a normal successful prompt is the most reliable check.
+
+FoxClaw app-server logs are stored here by default:
+
+```bash
+tail -f ~/.foxclaw/logs/codex-app-server.log
+```
+
+Bridge logs are stored here:
+
+```bash
+tail -f ~/.foxclaw/logs/service.log
+```
+
+## Service Starts With The Wrong Node Version
+
+The systemd installer captures the `node` binary from your current PATH. If you installed the service from a shell using Node 22 or older, reinstall it from a Node 24 shell:
+
+```bash
+nvm use 24
+foxclaw start
+systemctl --user status foxclaw.service
+```
+
+The status output should show a Node 24 path in `ExecStart`.
+
+## Does It Run After Reboot?
+
+Linux user systemd:
+
+```bash
+systemctl --user is-enabled foxclaw.service
+```
+
+`enabled` means it starts with your user session. To start after reboot before login:
+
+```bash
+loginctl enable-linger "$USER"
+```
+
+macOS launchd starts FoxClaw when you log in after running:
+
+```bash
+foxclaw start
+```
+
+## Migrating From The Old Project Name
+
+If this machine still runs `telegram-codex-app-bridge`, migrate once:
+
+```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
+```
+
+If `~/.foxclaw/.env` already exists, `foxclaw init` leaves it untouched.

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