@foxden-app/foxclaw 0.3.0 → 0.3.2

package/README.md

@@ -51,7 +51,6 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex，
 ```bash
 npm install -g @foxden-app/foxclaw
 foxclaw init
-$EDITOR ~/.foxclaw/.env
 foxclaw doctor
 foxclaw start
 ```
@@ -61,11 +60,12 @@ pnpm 用户：
 ```bash
 pnpm add -g @foxden-app/foxclaw
 foxclaw init
-$EDITOR ~/.foxclaw/.env
 foxclaw doctor
 foxclaw start
 ```
 
+`foxclaw init` 会创建 `~/.foxclaw/.env`，并在终端里提示填写 Telegram bot token、Telegram 数字用户 ID 和默认工作目录。任何一项都可以直接回车跳过，之后再用 `$EDITOR ~/.foxclaw/.env` 手动修改。
+
 跑 `doctor` 或 `start` 之前先把 `.env` 填好。私聊模式最小配置：
 
 ```dotenv
@@ -139,6 +139,14 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
+也可以直接用包装命令：
+
+```bash
+foxclaw status
+foxclaw restart
+foxclaw stop
+```
+
 需要前台调试时：
 
 ```bash
@@ -157,26 +165,9 @@ foxclaw serve
 
 可通过 `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 分发。
-
-升级已有安装：
-
-```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 start
-```
-
-macOS launchd 用户先卸载旧 plist：
-
-```bash
-launchctl unload ~/Library/LaunchAgents/com.ganxing.telegram-codex-app-bridge.plist 2>/dev/null || true
-foxclaw start
-```
+## 鸣谢
 
-旧目录不会被自动读取。如果要保留已有的绑定、线程缓存、审批和状态数据，手动复制一次即可。
+FoxClaw 最初基于 `Gan-Xing/telegram-codex-app-bridge` fork 演进而来，继续以 MIT License 分发。感谢原项目对 Telegram 与 Codex 本地桥接思路的探索。
 
 ## Telegram 设置
 
@@ -284,7 +275,7 @@ foxclaw weixin-login
 
 ## 故障排查
 
-`doctor` 报错、Telegram 没回复、服务日志看不懂、重启行为异常、迁移出问题——都看 [故障排查](./docs/zh/troubleshooting.md)。
+`doctor` 报错、Telegram 没回复、服务日志看不懂、重启行为异常——都看 [故障排查](./docs/zh/troubleshooting.md)。
 
 ## 运维命令
 
@@ -292,6 +283,8 @@ foxclaw weixin-login
 foxclaw doctor
 foxclaw status
 foxclaw start
+foxclaw restart
+foxclaw stop
 foxclaw uninstall-systemd
 ```
 

package/README_EN.md

@@ -51,7 +51,6 @@ The minimum install needs only a Telegram bot token, your numeric Telegram user
 ```bash
 npm install -g @foxden-app/foxclaw
 foxclaw init
-$EDITOR ~/.foxclaw/.env
 foxclaw doctor
 foxclaw start
 ```
@@ -61,12 +60,13 @@ pnpm users:
 ```bash
 pnpm add -g @foxden-app/foxclaw
 foxclaw init
-$EDITOR ~/.foxclaw/.env
 foxclaw doctor
 foxclaw start
 ```
 
-Edit `.env` before running `doctor` or `start`. Minimum private-chat config:
+`foxclaw init` creates `~/.foxclaw/.env` and prompts for the Telegram bot token, your numeric Telegram user id, and the default workspace. Press Enter on any field to skip it and edit later with `$EDITOR ~/.foxclaw/.env`.
+
+Fill `.env` before running `doctor` or `start`. Minimum private-chat config:
 
 ```dotenv
 TG_BOT_TOKEN=123456:telegram-token
@@ -139,6 +139,14 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
+You can also use the wrapper commands:
+
+```bash
+foxclaw status
+foxclaw restart
+foxclaw stop
+```
+
 For foreground debugging:
 
 ```bash
@@ -157,26 +165,9 @@ Default runtime files are stored under `~/.foxclaw`:
 
 Override with `STORE_PATH`, `LOCK_PATH`, `CODEX_APP_SERVER_STATE_PATH`, and `CODEX_APP_SERVER_LOG_PATH`.
 
-## Migrating From telegram-codex-app-bridge
-
-FoxClaw was originally forked from `Gan-Xing/telegram-codex-app-bridge` and remains distributed under the MIT License.
-
-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 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 start
-```
+## Acknowledgements
 
-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.
+FoxClaw originally evolved from a fork of `Gan-Xing/telegram-codex-app-bridge` and remains distributed under the MIT License. Thanks to that project for exploring the Telegram-to-local-Codex bridge pattern.
 
 ## Telegram Setup
 
@@ -284,7 +275,7 @@ This repo ships a Codex skill at [`skills/foxclaw`](./skills/foxclaw). Use it wh
 
 ## Troubleshooting
 
-See [Troubleshooting](./docs/troubleshooting.md) for `doctor` failures, Telegram no-reply cases, service logs, reboot behavior, and migration issues.
+See [Troubleshooting](./docs/troubleshooting.md) for `doctor` failures, Telegram no-reply cases, service logs, and reboot behavior.
 
 ## Operations
 
@@ -292,6 +283,8 @@ See [Troubleshooting](./docs/troubleshooting.md) for `doctor` failures, Telegram
 foxclaw doctor
 foxclaw status
 foxclaw start
+foxclaw restart
+foxclaw stop
 foxclaw uninstall-systemd
 ```
 

package/dist/main.js

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
+import { createInterface } from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { APP_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, loadConfig, loadEnv, } from './config.js';
@@ -13,7 +14,7 @@ const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const entryPoint = fileURLToPath(import.meta.url);
 async function main() {
     if (command === 'init') {
-        initConfig();
+        await initConfig();
         return;
     }
     if (command === 'install-systemd') {
@@ -23,7 +24,16 @@ async function main() {
     }
     if (command === 'start') {
         requireNode24(command);
-        startService();
+        startService('start');
+        return;
+    }
+    if (command === 'restart') {
+        requireNode24(command);
+        startService('restart');
+        return;
+    }
+    if (command === 'stop') {
+        stopService();
         return;
     }
     if (command === 'uninstall-systemd') {
@@ -134,22 +144,182 @@ async function runServeCli() {
         throw error;
     }
 }
-function initConfig() {
+async function initConfig() {
     const envPath = process.env.FOXCLAW_ENV?.trim() || DEFAULT_ENV_PATH;
     fs.mkdirSync(path.dirname(envPath), { recursive: true });
-    if (fs.existsSync(envPath)) {
+    const existed = fs.existsSync(envPath);
+    if (existed) {
         console.log(`Config already exists: ${envPath}`);
+    }
+    else {
+        const examplePath = path.join(packageRoot, '.env.example');
+        fs.copyFileSync(examplePath, envPath);
+        console.log(`Created ${envPath}`);
+    }
+    if (!canPromptForInit()) {
+        console.log(`Edit it manually, then run: foxclaw doctor`);
         return;
     }
-    const examplePath = path.join(packageRoot, '.env.example');
-    fs.copyFileSync(examplePath, envPath);
-    console.log(`Created ${envPath}`);
-    console.log('Edit it, then run: foxclaw doctor');
+    await configureEnvInteractively(envPath, existed);
+}
+function canPromptForInit() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY && !process.argv.includes('--no-input') && !process.argv.includes('--skip-prompts'));
+}
+async function configureEnvInteractively(envPath, existed) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        if (existed) {
+            const updateExisting = (await rl.question('Update Telegram/workspace setup fields now? [y/N]: ')).trim().toLowerCase();
+            if (updateExisting !== 'y' && updateExisting !== 'yes') {
+                console.log(`Edit it manually, then run: foxclaw doctor`);
+                return;
+            }
+        }
+        else {
+            console.log('Interactive setup. Press Enter to skip any field and edit it later.');
+        }
+        const updates = {};
+        const skipped = [];
+        const warnings = [];
+        const token = sanitizeEnvInput(await rl.question('Telegram bot token (TG_BOT_TOKEN): '));
+        if (token) {
+            updates.TG_BOT_TOKEN = token;
+            if (!/^\d+:[A-Za-z0-9_-]+$/.test(token)) {
+                warnings.push('TG_BOT_TOKEN does not look like a standard Telegram bot token.');
+            }
+        }
+        else {
+            skipped.push('TG_BOT_TOKEN');
+        }
+        const userId = sanitizeEnvInput(await rl.question('Telegram numeric user ID (TG_ALLOWED_USER_ID): '));
+        if (userId) {
+            if (/^\d+$/.test(userId)) {
+                updates.TG_ALLOWED_USER_ID = userId;
+            }
+            else {
+                skipped.push('TG_ALLOWED_USER_ID');
+                warnings.push('TG_ALLOWED_USER_ID must be numeric; use the Id from @userinfobot, not @username.');
+            }
+        }
+        else {
+            skipped.push('TG_ALLOWED_USER_ID');
+        }
+        const cwdDefault = defaultInitCwd();
+        const cwdPrompt = cwdDefault
+            ? `Default Codex workspace (DEFAULT_CWD) [${cwdDefault}]: `
+            : 'Default Codex workspace (DEFAULT_CWD): ';
+        const cwdAnswer = sanitizeEnvInput(await rl.question(cwdPrompt));
+        const cwd = cwdAnswer ? normalizeUserPath(cwdAnswer) : cwdDefault;
+        if (cwd) {
+            updates.DEFAULT_CWD = cwd;
+            warnings.push(...validateDefaultCwd(cwd));
+        }
+        else {
+            skipped.push('DEFAULT_CWD');
+        }
+        const codexBin = resolveCommand('codex');
+        if (codexBin) {
+            updates.CODEX_CLI_BIN = codexBin;
+        }
+        const updatedKeys = Object.keys(updates);
+        if (updatedKeys.length > 0) {
+            writeEnvUpdates(envPath, updates);
+            console.log(`Saved ${updatedKeys.join(', ')} to ${envPath}`);
+        }
+        else {
+            console.log('No setup fields changed.');
+        }
+        for (const warning of warnings) {
+            console.log(`[WARN] ${warning}`);
+        }
+        if (skipped.length > 0) {
+            console.log(`Skipped ${skipped.join(', ')}. Edit later: ${editorCommand(envPath)}`);
+        }
+        console.log('Next: foxclaw doctor');
+    }
+    finally {
+        rl.close();
+    }
+}
+function sanitizeEnvInput(value) {
+    return value.replace(/[\r\n]/g, '').trim();
+}
+function defaultInitCwd() {
+    const cwd = path.resolve(process.cwd());
+    if (isUnsafeDefaultCwd(cwd))
+        return null;
+    try {
+        if (fs.statSync(cwd).isDirectory())
+            return cwd;
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function normalizeUserPath(value) {
+    const expanded = value === '~' || value.startsWith('~/')
+        ? path.join(process.env.HOME || '', value.slice(2))
+        : value;
+    return path.resolve(expanded);
 }
-function startService() {
+function validateDefaultCwd(cwd) {
+    const warnings = [];
+    if (!path.isAbsolute(cwd)) {
+        warnings.push('DEFAULT_CWD should be an absolute path.');
+    }
+    if (isUnsafeDefaultCwd(cwd)) {
+        warnings.push('DEFAULT_CWD points at a very broad directory; use a project/workspace folder for the first install.');
+    }
+    try {
+        if (!fs.statSync(cwd).isDirectory()) {
+            warnings.push('DEFAULT_CWD exists but is not a directory.');
+        }
+    }
+    catch {
+        warnings.push('DEFAULT_CWD does not exist yet; create it or edit the path before starting.');
+    }
+    return warnings;
+}
+function isUnsafeDefaultCwd(cwd) {
+    const resolved = path.resolve(cwd);
+    const home = process.env.HOME ? path.resolve(process.env.HOME) : '';
+    return resolved === path.parse(resolved).root || resolved === home || resolved === '/home' || resolved === '/Users';
+}
+function writeEnvUpdates(envPath, updates) {
+    let text = fs.readFileSync(envPath, 'utf8');
+    const newline = text.includes('\r\n') ? '\r\n' : '\n';
+    for (const [key, value] of Object.entries(updates)) {
+        const line = `${key}=${formatEnvValue(value)}`;
+        const pattern = new RegExp(`^${escapeRegExp(key)}=.*$`, 'm');
+        if (pattern.test(text)) {
+            text = text.replace(pattern, line);
+        }
+        else {
+            if (text && !text.endsWith('\n') && !text.endsWith('\r\n')) {
+                text += newline;
+            }
+            text += `${line}${newline}`;
+        }
+    }
+    fs.writeFileSync(envPath, text);
+}
+function formatEnvValue(value) {
+    const cleaned = value.replace(/[\r\n]/g, '').trim();
+    if (!/[\s#"\\]/.test(cleaned))
+        return cleaned;
+    return `"${cleaned.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function editorCommand(envPath) {
+    return `${process.env.EDITOR?.trim() || '$EDITOR'} ${envPath}`;
+}
+function startService(action) {
     if (!runDoctorChecks()) {
         console.error('');
-        console.error('Fix the failed checks above, then run: foxclaw start');
+        console.error(`Fix the failed checks above, then run: foxclaw ${action}`);
         process.exit(1);
     }
     if (process.platform === 'darwin') {
@@ -158,6 +328,13 @@ function startService() {
     }
     installSystemd();
 }
+function stopService() {
+    if (process.platform === 'darwin') {
+        stopLaunchd();
+        return;
+    }
+    stopSystemd();
+}
 function runDoctorChecks() {
     const configuredCodexBin = process.env.CODEX_CLI_BIN;
     const checks = [
@@ -263,6 +440,15 @@ function uninstallSystemd() {
     spawnChecked('systemctl', ['--user', 'daemon-reload']);
     console.log(`Removed ${unitPath}`);
 }
+function stopSystemd() {
+    if (!hasCommand('systemctl')) {
+        console.error('systemctl not found');
+        process.exit(1);
+    }
+    const unitName = 'foxclaw.service';
+    spawnChecked('systemctl', ['--user', 'stop', unitName]);
+    console.log(`Stopped ${unitName}`);
+}
 function installLaunchd() {
     if (process.platform !== 'darwin') {
         console.error('launchd install is only available on macOS');
@@ -320,6 +506,19 @@ ${foxclawEnvXml}
     spawnChecked('launchctl', ['load', plist]);
     console.log(`Installed ${plist}`);
 }
+function stopLaunchd() {
+    if (process.platform !== 'darwin') {
+        console.error('launchd stop is only available on macOS');
+        process.exit(1);
+    }
+    const plist = path.join(process.env.HOME || '', 'Library', 'LaunchAgents', 'app.foxden.foxclaw.plist');
+    if (!fs.existsSync(plist)) {
+        console.error(`launchd plist not found: ${plist}`);
+        process.exit(1);
+    }
+    spawnChecked('launchctl', ['unload', plist]);
+    console.log(`Stopped ${plist}`);
+}
 function buildServicePath(nodeDir) {
     const parts = [
         path.join(process.env.HOME || '', '.local', 'bin'),
@@ -425,13 +624,18 @@ void main().catch((error) => {
     process.exit(1);
 });
 function hasCommand(commandName) {
+    return Boolean(resolveCommand(commandName));
+}
+function resolveCommand(commandName) {
     try {
         const which = process.platform === 'win32' ? 'where' : 'which';
-        const result = spawnSync(which, [commandName], { stdio: 'ignore' });
-        return result.status === 0;
+        const result = spawnSync(which, [commandName], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return null;
+        return result.stdout.split(/\r?\n/).map(line => line.trim()).find(Boolean) ?? null;
     }
     catch {
-        return false;
+        return null;
     }
 }
 function hasConfiguredCodexBin(binPath) {

package/docs/agent-assisted-install.md

@@ -38,7 +38,7 @@ TG_ALLOWED_USER_ID=<paste numeric Telegram user id here>
 DEFAULT_CWD=<paste absolute working directory here>
 
 Tasks:
-1. Inspect the machine first. If a FoxClaw or old telegram-codex-app-bridge service already exists, report it before changing services.
+1. Inspect the machine first. If a FoxClaw service already exists, report it before changing services.
 2. Ensure Node.js 24+ is available. If not, install or activate Node 24 with nvm.
 3. Ensure the Codex CLI exists and is logged in. If login is required, stop and tell me exactly what I need to do.
 4. Install or update FoxClaw with npm install -g @foxden-app/foxclaw@latest.
@@ -48,33 +48,10 @@ Tasks:
 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
    - foxclaw status works
 10. Report the commands used, the final status, and the log command I should use if something stops working. Redact TG_BOT_TOKEN and never print the full token or full .env content.
 ```
 
-## Migration Prompt For Old Installs
-
-Use this when the target computer is still running `telegram-codex-app-bridge`:
-
-```text
-Migrate this machine from telegram-codex-app-bridge to FoxClaw.
-
-New package:
-@foxden-app/foxclaw
-
-Please:
-1. Inspect the current install method, service file, and runtime directory before changing anything.
-2. Stop and disable telegram-codex-app-bridge.service if it exists.
-3. If ~/.foxclaw does not exist and ~/.telegram-codex-app-bridge exists, copy ~/.telegram-codex-app-bridge to ~/.foxclaw.
-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 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.
-```
-
 ## Safety Notes
 
 - Do not paste bot tokens into public issue trackers or public chat logs.

package/docs/install-for-beginners.md

@@ -123,7 +123,7 @@ npm install -g @foxden-app/foxclaw
 foxclaw init
 ```
 
-This creates the config file at `~/.foxclaw/.env`.
+This creates the config file at `~/.foxclaw/.env` and prompts for the Telegram bot token, your numeric Telegram user id, and the default workspace.
 
 If you prefer pnpm:
 
@@ -134,7 +134,7 @@ foxclaw init
 
 ## 7. Fill In `.env`
 
-Open `.env` in a simple editor:
+If you filled the token, user id, and workspace during `foxclaw init`, go straight to the first check. If you skipped a field or want to change anything, open `.env` in a simple editor:
 
 ```bash
 nano ~/.foxclaw/.env
@@ -259,13 +259,13 @@ foxclaw status
 Restart Linux service after changing `.env`:
 
 ```bash
-foxclaw start
+foxclaw restart
 ```
 
-Stop Linux service:
+Stop the service:
 
 ```bash
-systemctl --user stop foxclaw.service
+foxclaw stop
 ```
 
 Uninstall Linux service:

package/docs/troubleshooting.md

@@ -93,7 +93,7 @@ Check these in order:
 5. Restart after changing `.env`:
 
    ```bash
-   foxclaw start
+   foxclaw restart
    ```
 
    If running foreground mode, stop with `Ctrl+C` and run `foxclaw serve` again.
@@ -129,23 +129,17 @@ If FoxClaw is still running, it may consume the update before you inspect it.
 
 If Telegram reports conflicts or the same bot behaves strangely, two processes may be polling the same bot token.
 
-Check old and new services:
+Check the service and any extra foreground processes:
 
 ```bash
 systemctl --user is-active foxclaw.service
-systemctl --user is-active telegram-codex-app-bridge.service 2>/dev/null || true
+pgrep -af foxclaw
 ```
 
-Stop the old service:
+Stop the extra process or service, then restart FoxClaw:
 
 ```bash
-systemctl --user disable --now telegram-codex-app-bridge.service
-```
-
-Then restart FoxClaw:
-
-```bash
-foxclaw start
+foxclaw restart
 ```
 
 ## Codex Or App-Server Fails
@@ -219,18 +213,3 @@ 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/user-manual.md

@@ -100,7 +100,7 @@ Both install the same published npm package. Use one global package manager cons
 
 ### 1.6 Fill In The Config
 
-The default config file is `~/.foxclaw/.env`:
+`foxclaw init` creates the default config file at `~/.foxclaw/.env` and prompts for the Telegram bot token, your numeric Telegram user id, and the default workspace. Press Enter on any field to skip it, then edit manually if needed:
 
 ```bash
 $EDITOR ~/.foxclaw/.env
@@ -146,6 +146,7 @@ journalctl --user -u foxclaw.service -f
 On macOS, `foxclaw start` manages launchd. For foreground debugging, stop the background service and run:
 
 ```bash
+foxclaw stop
 foxclaw serve
 ```
 

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

@@ -37,7 +37,7 @@ TG_ALLOWED_USER_ID=<把 Telegram 数字用户 ID 粘贴在这里>
 DEFAULT_CWD=<把绝对工作目录粘贴在这里>
 
 任务：
-1. 先检查机器环境。如果已经存在 FoxClaw 或旧的 telegram-codex-app-bridge 服务，先报告再改服务。
+1. 先检查机器环境。如果已经存在 FoxClaw 服务，先报告再改服务。
 2. 确保 Node.js 24+ 可用；如果没有，请用 nvm 安装或切到 Node 24。
 3. 确保 Codex CLI 存在并且已经登录。如果需要登录，停下来告诉我具体要执行什么。
 4. 用 npm install -g @foxden-app/foxclaw@latest 安装或升级 FoxClaw。
@@ -47,33 +47,10 @@ DEFAULT_CWD=<把绝对工作目录粘贴在这里>
 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、公开聊天或代码仓库。

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

@@ -121,7 +121,7 @@ npm install -g @foxden-app/foxclaw
 foxclaw init
 ```
 
-这会创建默认配置文件 `~/.foxclaw/.env`。
+这会创建默认配置文件 `~/.foxclaw/.env`，并提示你填写 Telegram bot token、Telegram 数字用户 ID 和默认工作目录。
 
 如果你用 pnpm：
 
@@ -132,7 +132,7 @@ foxclaw init
 
 ## 7. 填写 `.env`
 
-用简单编辑器打开配置：
+如果刚才在 `foxclaw init` 里已经填好了 token、用户 ID 和工作目录，可以直接进入下一步检查。如果你选择了跳过，或者想改配置，用简单编辑器打开：
 
 ```bash
 nano ~/.foxclaw/.env
@@ -257,13 +257,13 @@ foxclaw status
 修改 `.env` 后重启：
 
 ```bash
-foxclaw start
+foxclaw restart
 ```
 
-停止 Linux 服务：
+停止服务：
 
 ```bash
-systemctl --user stop foxclaw.service
+foxclaw stop
 ```
 
 卸载 Linux 服务：
@@ -279,20 +279,11 @@ npm install -g @foxden-app/foxclaw@latest
 foxclaw start
 ```
 
-## 从旧项目名迁移
-
-如果这台机器仍在运行 `telegram-codex-app-bridge`，迁移一次即可：
+如果 `~/.foxclaw/.env` 已经存在，`foxclaw init` 会先询问是否更新 Telegram 和工作目录相关字段，其它配置保持不变。
 
-```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` 不会覆盖它。
+FoxClaw 最初基于 `Gan-Xing/telegram-codex-app-bridge` fork 演进而来。感谢原项目对 Telegram 与 Codex 本地桥接思路的探索。
 
 ## 下一步
 

package/docs/zh/troubleshooting.md

@@ -94,7 +94,7 @@ CODEX_CLI_BIN=/absolute/path/to/codex
 5. 修改 `.env` 后重启：
 
    ```bash
-   foxclaw start
+   foxclaw restart
    ```
 
    如果正在前台运行，先 `Ctrl+C` 停止，再重新运行 `foxclaw serve`。
@@ -130,23 +130,17 @@ CODEX_CLI_BIN=/absolute/path/to/codex
 
 如果 Telegram 报 conflict，或者同一个 bot 行为异常，通常是两个进程在轮询同一个 bot token。
 
-检查新旧服务：
+检查服务和额外的前台进程：
 
 ```bash
 systemctl --user is-active foxclaw.service
-systemctl --user is-active telegram-codex-app-bridge.service 2>/dev/null || true
+pgrep -af foxclaw
 ```
 
-停掉旧服务：
+停掉多余进程或服务后，重启 FoxClaw：
 
 ```bash
-systemctl --user disable --now telegram-codex-app-bridge.service
-```
-
-然后重启 FoxClaw：
-
-```bash
-foxclaw start
+foxclaw restart
 ```
 
 ## Codex 或 app-server 异常

package/docs/zh/user-manual.md

@@ -100,7 +100,7 @@ foxclaw init
 
 ### 1.6 填写配置
 
-默认配置文件是 `~/.foxclaw/.env`：
+`foxclaw init` 会创建默认配置文件 `~/.foxclaw/.env`，并提示填写 Telegram bot token、Telegram 数字用户 ID 和默认工作目录。任何一项都可以直接回车跳过，之后再手动编辑：
 
 ```bash
 $EDITOR ~/.foxclaw/.env
@@ -146,6 +146,7 @@ journalctl --user -u foxclaw.service -f
 macOS 上 `foxclaw start` 会管理 launchd。前台排障时，先停后台服务，再运行：
 
 ```bash
+foxclaw stop
 foxclaw serve
 ```
 

package/package.json

@@ -1,65 +1,67 @@
-{
-  "name": "@foxden-app/foxclaw",
-  "version": "0.3.0",
-  "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
-  "type": "module",
-  "main": "dist/main.js",
-  "bin": {
-    "foxclaw": "dist/main.js"
-  },
-  "files": [
-    "dist",
-    "docs",
-    "scripts",
-    "skills",
-    ".env.example",
-    "README.md",
-    "README_EN.md",
-    "LICENSE"
-  ],
-  "private": false,
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/foxden-app/foxclaw.git"
-  },
-  "homepage": "https://github.com/foxden-app/foxclaw#readme",
-  "bugs": {
-    "url": "https://github.com/foxden-app/foxclaw/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=24"
-  },
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "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",
-    "init": "node dist/main.js init",
-    "install-systemd": "node dist/main.js install-systemd",
-    "uninstall-systemd": "node dist/main.js uninstall-systemd",
-    "install-launchd": "node dist/main.js install-launchd",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "test": "node --test --import tsx \"src/**/*.test.ts\"",
-    "prepack": "npm run build"
-  },
-  "dependencies": {
-    "dotenv": "^16.6.1",
-    "qrcode-terminal": "^0.12.0"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.39.0",
-    "@types/node": "^24.12.0",
-    "eslint": "^9.39.0",
-    "tsx": "^4.19.3",
-    "typescript": "5.9.3",
-    "typescript-eslint": "^8.58.0"
-  }
-}
+{
+  "name": "@foxden-app/foxclaw",
+  "version": "0.3.2",
+  "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
+  "type": "module",
+  "main": "dist/main.js",
+  "bin": {
+    "foxclaw": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "scripts",
+    "skills",
+    ".env.example",
+    "README.md",
+    "README_EN.md",
+    "LICENSE"
+  ],
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/foxden-app/foxclaw.git"
+  },
+  "homepage": "https://github.com/foxden-app/foxclaw#readme",
+  "bugs": {
+    "url": "https://github.com/foxden-app/foxclaw/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "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",
+    "stop-service": "node dist/main.js stop",
+    "restart-service": "node dist/main.js restart",
+    "weixin-login": "node dist/main.js weixin-login",
+    "status": "node dist/main.js status",
+    "doctor": "node dist/main.js doctor",
+    "init": "node dist/main.js init",
+    "install-systemd": "node dist/main.js install-systemd",
+    "uninstall-systemd": "node dist/main.js uninstall-systemd",
+    "install-launchd": "node dist/main.js install-launchd",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "node --test --import tsx \"src/**/*.test.ts\"",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "dotenv": "^16.6.1",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.0",
+    "@types/node": "^24.12.0",
+    "eslint": "^9.39.0",
+    "tsx": "^4.19.3",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.58.0"
+  }
+}