@foxden-app/foxclaw 0.2.3 → 0.2.5

package/README.md

@@ -2,56 +2,56 @@
 
 # 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
 foxclaw init
 $EDITOR ~/.foxclaw/.env
 foxclaw doctor
-foxclaw serve
+foxclaw start
 ```
 
-pnpm 用户可以使用：
+pnpm 用户：
 
 ```bash
 pnpm add -g @foxden-app/foxclaw
 foxclaw init
 $EDITOR ~/.foxclaw/.env
 foxclaw doctor
-foxclaw serve
+foxclaw start
 ```
 
-运行 `doctor` 或 `serve` 前先编辑 `.env`。私聊模式的最小配置：
+跑 `doctor` 或 `start` 之前先把 `.env` 填好。私聊模式最小配置：
 
 ```dotenv
 TG_BOT_TOKEN=123456:telegram-token
@@ -61,114 +61,123 @@ 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 只接受来自 `TG_ALLOWED_USER_ID` 的消息。把机器人放进群组并不会让每个群成员都能使用它。
+`foxclaw start` 会自动检查环境并安装/重启后台服务，幂等操作，升级后再跑一次就行。
+
+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>
 
-## 作为服务安装
+## 服务与调试
+
+推荐方式：
 
-Linux 用户级 systemd：
+```bash
+foxclaw start
+```
+
+Linux 上会安装/重启用户级 systemd 服务，macOS 上安装/重载 launchd。查看状态：
 
 ```bash
-foxclaw install-systemd
 systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
-macOS launchd：
+需要前台调试时：
 
 ```bash
-foxclaw install-launchd
+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
 test -e ~/.foxclaw || cp -a ~/.telegram-codex-app-bridge ~/.foxclaw
-foxclaw install-systemd
+foxclaw start
 ```
 
-如果使用 launchd 安装，先卸载旧 plist（如存在）：
+macOS launchd 用户先卸载旧 plist：
 
 ```bash
 launchctl unload ~/Library/LaunchAgents/com.ganxing.telegram-codex-app-bridge.plist 2>/dev/null || true
-foxclaw install-launchd
+foxclaw start
 ```
 
-旧运行时目录不会被自动读取。如果你想保留现有绑定、缓存线程列表、审批和状态数据，请手动复制一次。
+旧目录不会被自动读取。如果要保留已有的绑定、线程缓存、审批和状态数据，手动复制一次即可。
 
 ## Telegram 设置
 
-1. 使用 `@BotFather` 创建机器人，并把 token 填入 `TG_BOT_TOKEN`。
-2. 获取你的 Telegram 数字用户 ID，并填入 `TG_ALLOWED_USER_ID`。
-3. 使用 `foxclaw serve` 或服务安装器启动 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 生命周期
 
@@ -183,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`
@@ -208,45 +217,45 @@ 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)。
 
 ## 运维命令
 
 ```bash
 foxclaw doctor
 foxclaw status
-foxclaw install-systemd
+foxclaw start
 foxclaw uninstall-systemd
 ```
 
 ## 贡献
 
-欢迎在 `https://github.com/foxden-app/foxclaw` 提交 issue 和 PR。
+欢迎到 [GitHub](https://github.com/foxden-app/foxclaw) 提 issue 和 PR。

package/README_EN.md

@@ -38,7 +38,7 @@ npm install -g @foxden-app/foxclaw
 foxclaw init
 $EDITOR ~/.foxclaw/.env
 foxclaw doctor
-foxclaw serve
+foxclaw start
 ```
 
 pnpm users can use:
@@ -48,10 +48,10 @@ pnpm add -g @foxden-app/foxclaw
 foxclaw init
 $EDITOR ~/.foxclaw/.env
 foxclaw doctor
-foxclaw serve
+foxclaw start
 ```
 
-Edit `.env` before running `doctor` or `serve`. Minimum private-chat config:
+Edit `.env` before running `doctor` or `start`. Minimum private-chat config:
 
 ```dotenv
 TG_BOT_TOKEN=123456:telegram-token
@@ -63,6 +63,8 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 The default config file is `~/.foxclaw/.env`. Set `FOXCLAW_ENV=/path/to/.env` if you want to keep it somewhere else.
 
+`foxclaw start` runs checks and installs or restarts the background service. It is idempotent, so run it again after upgrading.
+
 FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a group does not make it available to every group member.
 
 <details>
@@ -83,20 +85,25 @@ FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a gr
 
 </details>
 
-## Installing As A Service
+## Service And Debugging
+
+Recommended:
 
-Linux user systemd:
+```bash
+foxclaw start
+```
+
+It installs or restarts the Linux user systemd service, or loads/reloads launchd on macOS. To inspect Linux service state:
 
 ```bash
-foxclaw install-systemd
 systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
-macOS launchd:
+For foreground debugging:
 
 ```bash
-foxclaw install-launchd
+foxclaw serve
 ```
 
 Default runtime files are stored under `~/.foxclaw`:
@@ -118,14 +125,14 @@ When upgrading an existing local install:
 ```bash
 systemctl --user disable --now telegram-codex-app-bridge.service 2>/dev/null || true
 test -e ~/.foxclaw || cp -a ~/.telegram-codex-app-bridge ~/.foxclaw
-foxclaw install-systemd
+foxclaw start
 ```
 
 For launchd installs, unload the old plist if present:
 
 ```bash
 launchctl unload ~/Library/LaunchAgents/com.ganxing.telegram-codex-app-bridge.plist 2>/dev/null || true
-foxclaw install-launchd
+foxclaw start
 ```
 
 The old runtime directory is not read automatically. Copy it once if you want to keep existing bindings, cached thread lists, approvals, and status data.
@@ -134,7 +141,7 @@ The old runtime directory is not read automatically. Copy it once if you want to
 
 1. Create a bot with `@BotFather` and copy the token into `TG_BOT_TOKEN`.
 2. Get your Telegram numeric user id and place it into `TG_ALLOWED_USER_ID`.
-3. Start FoxClaw with `foxclaw serve` or the service installer.
+3. Start FoxClaw with `foxclaw start`.
 4. Open a private chat with the bot and send `/help`.
 
 Optional group/topic config:
@@ -243,7 +250,7 @@ See [Troubleshooting](./docs/troubleshooting.md) for `doctor` failures, Telegram
 ```bash
 foxclaw doctor
 foxclaw status
-foxclaw install-systemd
+foxclaw start
 foxclaw uninstall-systemd
 ```
 

package/dist/config.js

@@ -18,7 +18,7 @@ export function loadEnv() {
     envLoaded = true;
     const explicitPath = process.env.FOXCLAW_ENV?.trim();
     if (explicitPath) {
-        dotenv.config({ path: explicitPath });
+        dotenv.config({ path: explicitPath, override: true });
         return;
     }
     const cwdEnvPath = path.join(process.cwd(), '.env');

package/dist/main.js

@@ -21,6 +21,11 @@ async function main() {
         installSystemd();
         return;
     }
+    if (command === 'start') {
+        requireNode24(command);
+        startService();
+        return;
+    }
     if (command === 'uninstall-systemd') {
         uninstallSystemd();
         return;
@@ -40,43 +45,7 @@ async function main() {
         return;
     }
     if (command === 'doctor') {
-        const configuredCodexBin = process.env.CODEX_CLI_BIN;
-        const checks = [
-            ['node >= 24', Number(process.versions.node.split('.')[0]) >= 24],
-            ['codex cli available', hasConfiguredCodexBin(configuredCodexBin) || hasCommand('codex')],
-            ['telegram bot token configured', Boolean(process.env.TG_BOT_TOKEN)],
-            ['telegram allowed user configured', Boolean(process.env.TG_ALLOWED_USER_ID)],
-        ];
-        if (process.env.WX_ENABLED === 'true' || process.env.WX_ENABLED === '1') {
-            const accountsDir = process.env.WEIXIN_ACCOUNTS_DIR || path.join(APP_HOME, 'weixin', 'accounts');
-            let hasAccounts = false;
-            try {
-                if (fs.existsSync(accountsDir)) {
-                    hasAccounts = fs.readdirSync(accountsDir).some((n) => n.endsWith('.json'));
-                }
-            }
-            catch {
-                hasAccounts = false;
-            }
-            checks.push(['WX_ENABLED: Weixin account JSON present', hasAccounts]);
-            checks.push(['WX_ALLOWED_ILINK_USER_IDS set (recommended)', Boolean(process.env.WX_ALLOWED_ILINK_USER_IDS?.trim())]);
-        }
-        let failed = false;
-        for (const [name, ok] of checks) {
-            console.log(`${ok ? '[OK]' : '[FAIL]'} ${name}`);
-            if (!ok)
-                failed = true;
-        }
-        try {
-            const cwd = process.env.DEFAULT_CWD || process.cwd();
-            fs.accessSync(cwd);
-            console.log(`[OK] default cwd exists: ${cwd}`);
-        }
-        catch {
-            const cwd = process.env.DEFAULT_CWD || process.cwd();
-            console.log(`[FAIL] default cwd missing: ${cwd}`);
-            failed = true;
-        }
+        const failed = !runDoctorChecks();
         process.exit(failed ? 1 : 0);
     }
     if (command === 'weixin-login') {
@@ -177,6 +146,58 @@ function initConfig() {
     console.log(`Created ${envPath}`);
     console.log('Edit it, then run: foxclaw doctor');
 }
+function startService() {
+    if (!runDoctorChecks()) {
+        console.error('');
+        console.error('Fix the failed checks above, then run: foxclaw start');
+        process.exit(1);
+    }
+    if (process.platform === 'darwin') {
+        installLaunchd();
+        return;
+    }
+    installSystemd();
+}
+function runDoctorChecks() {
+    const configuredCodexBin = process.env.CODEX_CLI_BIN;
+    const checks = [
+        ['node >= 24', Number(process.versions.node.split('.')[0]) >= 24],
+        ['codex cli available', hasConfiguredCodexBin(configuredCodexBin) || hasCommand('codex')],
+        ['telegram bot token configured', Boolean(process.env.TG_BOT_TOKEN)],
+        ['telegram allowed user configured', Boolean(process.env.TG_ALLOWED_USER_ID)],
+    ];
+    if (process.env.WX_ENABLED === 'true' || process.env.WX_ENABLED === '1') {
+        const accountsDir = process.env.WEIXIN_ACCOUNTS_DIR || path.join(APP_HOME, 'weixin', 'accounts');
+        let hasAccounts = false;
+        try {
+            if (fs.existsSync(accountsDir)) {
+                hasAccounts = fs.readdirSync(accountsDir).some((n) => n.endsWith('.json'));
+            }
+        }
+        catch {
+            hasAccounts = false;
+        }
+        checks.push(['WX_ENABLED: Weixin account JSON present', hasAccounts]);
+        checks.push(['WX_ALLOWED_ILINK_USER_IDS set (recommended)', Boolean(process.env.WX_ALLOWED_ILINK_USER_IDS?.trim())]);
+    }
+    let passed = true;
+    for (const [name, ok] of checks) {
+        console.log(`${ok ? '[OK]' : '[FAIL]'} ${name}`);
+        if (!ok)
+            passed = false;
+    }
+    try {
+        const cwd = process.env.DEFAULT_CWD || process.cwd();
+        fs.accessSync(cwd);
+        console.log(`[OK] default cwd exists: ${cwd}`);
+    }
+    catch {
+        const cwd = process.env.DEFAULT_CWD || process.cwd();
+        console.log(`[FAIL] default cwd missing: ${cwd}`);
+        passed = false;
+    }
+    return passed;
+}
 function installSystemd() {
     if (!hasCommand('systemctl')) {
         console.error('systemctl not found (need systemd)');

package/docs/agent-assisted-install.md

@@ -44,10 +44,8 @@ Tasks:
 4. Install or update FoxClaw with npm install -g @foxden-app/foxclaw@latest.
 5. Run foxclaw init, then write ~/.foxclaw/.env. Never print or commit the bot token.
 6. Run foxclaw doctor.
-7. Start FoxClaw in the foreground with foxclaw serve and ask me to send /help and /status to the Telegram bot.
-8. Only after the foreground test works, install the background service:
-   - Linux: foxclaw install-systemd
-   - macOS: foxclaw install-launchd
+7. Start FoxClaw with foxclaw start.
+8. Ask me to send /help and /status to the Telegram bot.
 9. Verify the final state:
    - foxclaw.service is active/enabled on Linux
    - old telegram-codex-app-bridge.service is inactive/disabled if present
@@ -72,7 +70,7 @@ Please:
 4. Install or update FoxClaw with npm install -g @foxden-app/foxclaw@latest.
 5. Run foxclaw init if ~/.foxclaw/.env does not exist, then verify ~/.foxclaw/.env.
 6. Run foxclaw doctor.
-7. Install and start foxclaw.service with foxclaw install-systemd.
+7. Install or restart the FoxClaw service with foxclaw start.
 8. Verify foxclaw.service is active and telegram-codex-app-bridge.service is inactive/disabled.
 9. Report final status and any blockers. Redact TG_BOT_TOKEN and never print the full token or full .env content.
 ```
@@ -83,4 +81,4 @@ Please:
 - Do not commit `.env`.
 - When reporting results, redact `TG_BOT_TOKEN`.
 - Do not use `/` or your whole home directory as `DEFAULT_CWD` for a first install.
-- Do not install the background service before the foreground Telegram test works.
+- Use `foxclaw start` for normal service startup. Use foreground `foxclaw serve` only when troubleshooting.

package/docs/install-for-beginners.md

@@ -11,7 +11,7 @@ Before you start:
 - Do not configure a Telegram group first. Use private chat first.
 - Do not send your bot token to anyone you do not trust.
 - Do not use `/`, `/Users`, `/home`, or your whole home directory as `DEFAULT_CWD` for the first install.
-- Do not install the background service until foreground mode replies to `/help` and `/status`.
+- Use `foxclaw start` for normal startup. Use foreground mode only when troubleshooting.
 
 ## 1. Prepare
 
@@ -183,15 +183,15 @@ You want to see:
 
 If you see `[FAIL]`, stop and check [Troubleshooting](./troubleshooting.md).
 
-## 9. Start In The Foreground First
+## 9. Start FoxClaw
 
-Run FoxClaw directly before installing it as a background service:
+Start or restart the background service:
 
 ```bash
-foxclaw serve
+foxclaw start
 ```
 
-Leave this terminal open.
+This command is safe to run again. It runs the same checks as `doctor`, then installs or restarts the service for your platform.
 
 Now open your Telegram bot and send:
 
@@ -229,16 +229,11 @@ Create a short README-style summary of this folder.
 /interrupt
 ```
 
-Stop the foreground process with `Ctrl+C` after the bot works.
+## 10. Service Commands
 
-## 10. Install As A Background Service
-
-Only do this after foreground mode works.
-
-On Linux with systemd:
+On Linux, `foxclaw start` manages a user-level systemd service. Check it with:
 
 ```bash
-foxclaw install-systemd
 systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
@@ -249,13 +244,9 @@ The service starts again when your user session starts. If you need it to start
 loginctl enable-linger "$USER"
 ```
 
-On macOS:
-
-```bash
-foxclaw install-launchd
-```
+On macOS, `foxclaw start` manages launchd and starts FoxClaw when you log in.
 
-launchd starts FoxClaw when you log in.
+For foreground debugging, stop the service first and then run `foxclaw serve`.
 
 ## 11. Day-To-Day Commands
 
@@ -268,7 +259,7 @@ foxclaw status
 Restart Linux service after changing `.env`:
 
 ```bash
-systemctl --user restart foxclaw.service
+foxclaw start
 ```
 
 Stop Linux service:
@@ -287,5 +278,5 @@ Update FoxClaw later:
 
 ```bash
 npm install -g @foxden-app/foxclaw@latest
-systemctl --user restart foxclaw.service
+foxclaw start
 ```

package/docs/troubleshooting.md

@@ -18,7 +18,7 @@ journalctl --user -u foxclaw.service -f
 
 | 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 install-systemd`. |
+| `[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`. |
@@ -93,7 +93,7 @@ Check these in order:
 5. Restart after changing `.env`:
 
    ```bash
-   systemctl --user restart foxclaw.service
+   foxclaw start
    ```
 
    If running foreground mode, stop with `Ctrl+C` and run `foxclaw serve` again.
@@ -145,7 +145,7 @@ systemctl --user disable --now telegram-codex-app-bridge.service
 Then restart FoxClaw:
 
 ```bash
-systemctl --user restart foxclaw.service
+foxclaw start
 ```
 
 ## Codex Or App-Server Fails
@@ -194,7 +194,7 @@ The systemd installer captures the `node` binary from your current PATH. If you
 
 ```bash
 nvm use 24
-foxclaw install-systemd
+foxclaw start
 systemctl --user status foxclaw.service
 ```
 
@@ -217,7 +217,7 @@ loginctl enable-linger "$USER"
 macOS launchd starts FoxClaw when you log in after running:
 
 ```bash
-foxclaw install-launchd
+foxclaw start
 ```
 
 ## Migrating From The Old Project Name
@@ -230,7 +230,7 @@ test -e ~/.foxclaw || cp -a ~/.telegram-codex-app-bridge ~/.foxclaw
 npm install -g @foxden-app/foxclaw@latest
 foxclaw init
 foxclaw doctor
-foxclaw install-systemd
+foxclaw start
 ```
 
 If `~/.foxclaw/.env` already exists, `foxclaw init` leaves it untouched.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",
@@ -37,6 +37,7 @@
     "build": "npm run clean && tsc -p tsconfig.build.json",
     "dev": "tsx src/main.ts serve",
     "serve": "node dist/main.js serve",
+    "start-service": "node dist/main.js start",
     "weixin-login": "node dist/main.js weixin-login",
     "status": "node dist/main.js status",
     "doctor": "node dist/main.js doctor",