@foxden-app/foxclaw 0.2.3 → 0.2.4

package/README.md

@@ -38,7 +38,7 @@ npm install -g @foxden-app/foxclaw
 foxclaw init
 $EDITOR ~/.foxclaw/.env
 foxclaw doctor
-foxclaw serve
+foxclaw start
 ```
 
 pnpm 用户可以使用：
@@ -48,10 +48,10 @@ 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
@@ -63,6 +63,8 @@ DEFAULT_SANDBOX_MODE=workspace-write
 
 默认配置文件是 `~/.foxclaw/.env`。如果你想把配置放在别处，可以设置 `FOXCLAW_ENV=/path/to/.env`。
 
+`foxclaw start` 会运行检查并安装或重启后台服务；这个命令是幂等的，升级后可以再执行一次。
+
 FoxClaw 只接受来自 `TG_ALLOWED_USER_ID` 的消息。把机器人放进群组并不会让每个群成员都能使用它。
 
 <details>
@@ -83,20 +85,25 @@ FoxClaw 只接受来自 `TG_ALLOWED_USER_ID` 的消息。把机器人放进群
 
 </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`：
@@ -118,14 +125,14 @@ FoxClaw 最初 fork 自 `Gan-Xing/telegram-codex-app-bridge`，并继续以 MIT
 ```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（如存在）：
 
 ```bash
 launchctl unload ~/Library/LaunchAgents/com.ganxing.telegram-codex-app-bridge.plist 2>/dev/null || true
-foxclaw install-launchd
+foxclaw start
 ```
 
 旧运行时目录不会被自动读取。如果你想保留现有绑定、缓存线程列表、审批和状态数据，请手动复制一次。
@@ -134,7 +141,7 @@ foxclaw install-launchd
 
 1. 使用 `@BotFather` 创建机器人，并把 token 填入 `TG_BOT_TOKEN`。
 2. 获取你的 Telegram 数字用户 ID，并填入 `TG_ALLOWED_USER_ID`。
-3. 使用 `foxclaw serve` 或服务安装器启动 FoxClaw。
+3. 使用 `foxclaw start` 启动 FoxClaw。
 4. 打开与机器人的私聊并发送 `/help`。
 
 可选的群组/话题配置：
@@ -243,7 +250,7 @@ foxclaw weixin-login
 ```bash
 foxclaw doctor
 foxclaw status
-foxclaw install-systemd
+foxclaw start
 foxclaw uninstall-systemd
 ```
 

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.4",
   "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",