@foxden-app/foxclaw 0.3.1 → 0.3.3

package/README.md

@@ -26,6 +26,12 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex，
 - 🔒 代码、shell、认证、审批、运行数据全部留在本机，不暴露到公网
 - 👤 只允许一个受信任的 Telegram 用户远程操作
 
+## 功能预览
+
+![FoxClaw Telegram 功能预览](./docs/assets/telegram-preview-zh.svg)
+
+手机端不是简单转发消息，而是给 Codex 的常用工作流做了 Telegram 面板：`/setup` 调模型、推理强度、Fast tier、权限和 Agent/Plan 模式；`/auth` 管理多个 Codex 登录候选，触发限制时自动轮转；`/threads`、`/watch` 和审批按钮用于切线程、观察进度和处理权限请求。
+
 ## 从这里开始
 
 - 手头有 Codex、OpenClaw、QwenPaw、Hermes、OpenCode、Kimi CLI 之类能跑 shell 的 agent？推荐走 [Agent 辅助安装](./docs/zh/agent-assisted-install.md)。
@@ -51,7 +57,6 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex，
 ```bash
 npm install -g @foxden-app/foxclaw
 foxclaw init
-$EDITOR ~/.foxclaw/.env
 foxclaw doctor
 foxclaw start
 ```
@@ -61,11 +66,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
@@ -165,26 +171,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 设置
 
@@ -292,7 +281,7 @@ foxclaw weixin-login
 
 ## 故障排查
 
-`doctor` 报错、Telegram 没回复、服务日志看不懂、重启行为异常、迁移出问题——都看 [故障排查](./docs/zh/troubleshooting.md)。
+`doctor` 报错、Telegram 没回复、服务日志看不懂、重启行为异常——都看 [故障排查](./docs/zh/troubleshooting.md)。
 
 ## 运维命令
 

package/README_EN.md

@@ -26,6 +26,12 @@ No public server required. FoxClaw runs on your own computer, talks to `codex ap
 - 🔒 Code, shell, auth, approvals, and runtime data stay on your machine — nothing exposed to the public internet
 - 👤 Only one trusted Telegram user can operate the bot
 
+## Feature Preview
+
+![FoxClaw Telegram feature preview](./docs/assets/telegram-preview-en.svg)
+
+FoxClaw is more than message forwarding. It provides Telegram panels for Codex workflows: `/setup` adjusts model, reasoning, Fast tier, access, and Agent/Plan mode; `/auth` manages multiple Codex auth candidates and rotates them on usage limits; `/threads`, `/watch`, and approval buttons handle thread switching, progress monitoring, and permission requests.
+
 ## Start Here
 
 - Already have a shell-capable agent such as Codex, OpenClaw, QwenPaw, Hermes, OpenCode, or Kimi CLI? Use the [Agent-Assisted Install](./docs/agent-assisted-install.md) first. This is the recommended path.
@@ -51,7 +57,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 +66,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
@@ -165,26 +171,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
 
@@ -292,7 +281,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
 

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') {
@@ -143,17 +144,177 @@ 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 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()) {
@@ -463,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/assets/telegram-preview-en.svg

@@ -0,0 +1,95 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="760" viewBox="0 0 1280 760" role="img" aria-labelledby="title desc">
+  <title id="title">FoxClaw Telegram feature preview</title>
+  <desc id="desc">Telegram-style preview of FoxClaw setup and auth management panels.</desc>
+  <defs>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="18" stdDeviation="18" flood-color="#152033" flood-opacity="0.16"/>
+    </filter>
+    <style>
+      .label { font: 600 24px Arial, sans-serif; fill: #111827; }
+      .body { font: 500 18px Arial, sans-serif; fill: #243244; }
+      .muted { font: 500 15px Arial, sans-serif; fill: #607086; }
+      .small { font: 600 14px Arial, sans-serif; fill: #42526a; }
+      .button { font: 700 15px Arial, sans-serif; fill: #1f6fb2; }
+      .top { font: 700 18px Arial, sans-serif; fill: #fff; }
+      .mono { font: 600 16px ui-monospace, SFMono-Regular, Menlo, monospace; fill: #334155; }
+    </style>
+  </defs>
+  <rect width="1280" height="760" rx="0" fill="#f3f7fb"/>
+  <circle cx="112" cy="102" r="58" fill="#d7edf9"/>
+  <circle cx="1185" cy="660" r="74" fill="#e5f4ec"/>
+  <text x="80" y="86" class="label">A mobile control panel for Codex</text>
+  <text x="80" y="118" class="body">Send tasks, inspect progress, approve actions, switch threads, and rotate auth accounts from Telegram.</text>
+
+  <g filter="url(#shadow)" transform="translate(96 164)">
+    <rect x="0" y="0" width="520" height="492" rx="36" fill="#17212b"/>
+    <rect x="18" y="18" width="484" height="456" rx="28" fill="#dcebf5"/>
+    <rect x="18" y="18" width="484" height="58" rx="28" fill="#229ed9"/>
+    <text x="48" y="55" class="top">FoxClaw Bot · /setup</text>
+    <rect x="44" y="104" width="432" height="236" rx="18" fill="#ffffff"/>
+    <text x="70" y="142" class="label">Setup · current thread</text>
+    <text x="70" y="176" class="body">Model: GPT-5.5</text>
+    <text x="70" y="206" class="body">Reasoning: High</text>
+    <text x="70" y="236" class="body">Mode: 📝 Plan</text>
+    <text x="70" y="266" class="body">Access: Workspace write</text>
+    <text x="70" y="296" class="body">Fast tier: ⚡ enabled</text>
+    <text x="70" y="326" class="muted">Each chat/thread can keep its own settings.</text>
+    <g transform="translate(44 360)">
+      <rect x="0" y="0" width="100" height="42" rx="12" fill="#e9f5ff"/>
+      <text x="25" y="27" class="button">⚡ Fast</text>
+      <rect x="112" y="0" width="96" height="42" rx="12" fill="#e9f5ff"/>
+      <text x="137" y="27" class="button">🔒 Read</text>
+      <rect x="220" y="0" width="96" height="42" rx="12" fill="#e9f5ff"/>
+      <text x="238" y="27" class="button">✍️ Work</text>
+      <rect x="328" y="0" width="104" height="42" rx="12" fill="#e9f5ff"/>
+      <text x="350" y="27" class="button">🛠️ Full</text>
+      <rect x="0" y="54" width="132" height="42" rx="12" fill="#eaf8ef"/>
+      <text x="34" y="81" class="button">📝 Plan</text>
+      <rect x="144" y="54" width="132" height="42" rx="12" fill="#eef2ff"/>
+      <text x="177" y="81" class="button">Agent</text>
+    </g>
+  </g>
+
+  <g filter="url(#shadow)" transform="translate(664 164)">
+    <rect x="0" y="0" width="520" height="492" rx="36" fill="#17212b"/>
+    <rect x="18" y="18" width="484" height="456" rx="28" fill="#dcebf5"/>
+    <rect x="18" y="18" width="484" height="58" rx="28" fill="#229ed9"/>
+    <text x="48" y="55" class="top">FoxClaw Bot · /auth</text>
+    <rect x="44" y="104" width="432" height="258" rx="18" fill="#ffffff"/>
+    <text x="70" y="142" class="label">Auth · account rotation</text>
+    <text x="70" y="176" class="body">Current: personal · GPT-5.5</text>
+    <text x="70" y="206" class="body">Auto-switches and retries on usage limits.</text>
+    <g transform="translate(70 232)">
+      <rect x="0" y="0" width="376" height="34" rx="10" fill="#f7fafc"/>
+      <text x="14" y="23" class="mono">✅ 1 personal</text>
+      <text x="256" y="23" class="small">32% used</text>
+      <rect x="0" y="44" width="376" height="34" rx="10" fill="#f7fafc"/>
+      <text x="14" y="67" class="mono">✅ 2 team</text>
+      <text x="280" y="67" class="small">ready</text>
+      <rect x="0" y="88" width="376" height="34" rx="10" fill="#f7fafc"/>
+      <text x="14" y="111" class="mono">⏸️ 3 trial</text>
+      <text x="256" y="111" class="small">disabled</text>
+    </g>
+    <g transform="translate(44 386)">
+      <rect x="0" y="0" width="120" height="42" rx="12" fill="#e9f5ff"/>
+      <text x="31" y="27" class="button">✅ enable</text>
+      <rect x="132" y="0" width="120" height="42" rx="12" fill="#fff4e6"/>
+      <text x="167" y="27" class="button">⏸️ pause</text>
+      <rect x="264" y="0" width="168" height="42" rx="12" fill="#eaf8ef"/>
+      <text x="309" y="27" class="button">add auth</text>
+    </g>
+  </g>
+
+  <g transform="translate(138 686)">
+    <rect x="0" y="-30" width="138" height="46" rx="23" fill="#ffffff"/>
+    <text x="25" y="0" class="small">send tasks</text>
+    <rect x="160" y="-30" width="150" height="46" rx="23" fill="#ffffff"/>
+    <text x="186" y="0" class="small">watch progress</text>
+    <rect x="332" y="-30" width="150" height="46" rx="23" fill="#ffffff"/>
+    <text x="359" y="0" class="small">tap approvals</text>
+    <rect x="504" y="-30" width="150" height="46" rx="23" fill="#ffffff"/>
+    <text x="533" y="0" class="small">switch threads</text>
+    <rect x="676" y="-30" width="176" height="46" rx="23" fill="#ffffff"/>
+    <text x="703" y="0" class="small">rotate accounts</text>
+  </g>
+</svg>

package/docs/assets/telegram-preview-zh.svg

@@ -0,0 +1,95 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="760" viewBox="0 0 1280 760" role="img" aria-labelledby="title desc">
+  <title id="title">FoxClaw Telegram 功能预览</title>
+  <desc id="desc">Telegram 风格的 FoxClaw setup 和 auth 管理面板示意图。</desc>
+  <defs>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="18" stdDeviation="18" flood-color="#152033" flood-opacity="0.16"/>
+    </filter>
+    <style>
+      .label { font: 600 24px Arial, "Noto Sans CJK SC", sans-serif; fill: #111827; }
+      .body { font: 500 18px Arial, "Noto Sans CJK SC", sans-serif; fill: #243244; }
+      .muted { font: 500 15px Arial, "Noto Sans CJK SC", sans-serif; fill: #607086; }
+      .small { font: 600 14px Arial, "Noto Sans CJK SC", sans-serif; fill: #42526a; }
+      .button { font: 700 15px Arial, "Noto Sans CJK SC", sans-serif; fill: #1f6fb2; }
+      .top { font: 700 18px Arial, "Noto Sans CJK SC", sans-serif; fill: #fff; }
+      .mono { font: 600 16px ui-monospace, SFMono-Regular, Menlo, monospace; fill: #334155; }
+    </style>
+  </defs>
+  <rect width="1280" height="760" rx="0" fill="#f3f7fb"/>
+  <circle cx="112" cy="102" r="58" fill="#d7edf9"/>
+  <circle cx="1185" cy="660" r="74" fill="#e5f4ec"/>
+  <text x="80" y="86" class="label">手机上的 Codex 控制台</text>
+  <text x="80" y="118" class="body">发任务、看进度、点审批、切线程、轮转账号，都在 Telegram 面板里完成。</text>
+
+  <g filter="url(#shadow)" transform="translate(96 164)">
+    <rect x="0" y="0" width="520" height="492" rx="36" fill="#17212b"/>
+    <rect x="18" y="18" width="484" height="456" rx="28" fill="#dcebf5"/>
+    <rect x="18" y="18" width="484" height="58" rx="28" fill="#229ed9"/>
+    <text x="48" y="55" class="top">FoxClaw Bot · /setup</text>
+    <rect x="44" y="104" width="432" height="236" rx="18" fill="#ffffff"/>
+    <text x="70" y="142" class="label">Setup · 当前线程</text>
+    <text x="70" y="176" class="body">模型：GPT-5.5</text>
+    <text x="70" y="206" class="body">推理强度：High</text>
+    <text x="70" y="236" class="body">模式：📝 Plan</text>
+    <text x="70" y="266" class="body">权限：Workspace write</text>
+    <text x="70" y="296" class="body">Fast tier：⚡ 开启</text>
+    <text x="70" y="326" class="muted">每个聊天/线程都可以独立配置。</text>
+    <g transform="translate(44 360)">
+      <rect x="0" y="0" width="100" height="42" rx="12" fill="#e9f5ff"/>
+      <text x="25" y="27" class="button">⚡ Fast</text>
+      <rect x="112" y="0" width="96" height="42" rx="12" fill="#e9f5ff"/>
+      <text x="135" y="27" class="button">🔒 只读</text>
+      <rect x="220" y="0" width="96" height="42" rx="12" fill="#e9f5ff"/>
+      <text x="239" y="27" class="button">✍️ 默认</text>
+      <rect x="328" y="0" width="104" height="42" rx="12" fill="#e9f5ff"/>
+      <text x="345" y="27" class="button">🛠️ 完全</text>
+      <rect x="0" y="54" width="132" height="42" rx="12" fill="#eaf8ef"/>
+      <text x="34" y="81" class="button">📝 Plan</text>
+      <rect x="144" y="54" width="132" height="42" rx="12" fill="#eef2ff"/>
+      <text x="177" y="81" class="button">Agent</text>
+    </g>
+  </g>
+
+  <g filter="url(#shadow)" transform="translate(664 164)">
+    <rect x="0" y="0" width="520" height="492" rx="36" fill="#17212b"/>
+    <rect x="18" y="18" width="484" height="456" rx="28" fill="#dcebf5"/>
+    <rect x="18" y="18" width="484" height="58" rx="28" fill="#229ed9"/>
+    <text x="48" y="55" class="top">FoxClaw Bot · /auth</text>
+    <rect x="44" y="104" width="432" height="258" rx="18" fill="#ffffff"/>
+    <text x="70" y="142" class="label">Auth · 多账号轮转</text>
+    <text x="70" y="176" class="body">当前：personal · GPT-5.5</text>
+    <text x="70" y="206" class="body">限制触发时自动切换并重试。</text>
+    <g transform="translate(70 232)">
+      <rect x="0" y="0" width="376" height="34" rx="10" fill="#f7fafc"/>
+      <text x="14" y="23" class="mono">✅ 1 personal</text>
+      <text x="256" y="23" class="small">32% used</text>
+      <rect x="0" y="44" width="376" height="34" rx="10" fill="#f7fafc"/>
+      <text x="14" y="67" class="mono">✅ 2 team</text>
+      <text x="280" y="67" class="small">ready</text>
+      <rect x="0" y="88" width="376" height="34" rx="10" fill="#f7fafc"/>
+      <text x="14" y="111" class="mono">⏸️ 3 trial</text>
+      <text x="256" y="111" class="small">disabled</text>
+    </g>
+    <g transform="translate(44 386)">
+      <rect x="0" y="0" width="120" height="42" rx="12" fill="#e9f5ff"/>
+      <text x="31" y="27" class="button">✅ 启用</text>
+      <rect x="132" y="0" width="120" height="42" rx="12" fill="#fff4e6"/>
+      <text x="163" y="27" class="button">⏸️ 暂停</text>
+      <rect x="264" y="0" width="168" height="42" rx="12" fill="#eaf8ef"/>
+      <text x="307" y="27" class="button">添加账号</text>
+    </g>
+  </g>
+
+  <g transform="translate(158 686)">
+    <rect x="0" y="-30" width="138" height="46" rx="23" fill="#ffffff"/>
+    <text x="25" y="0" class="small">发任务</text>
+    <rect x="160" y="-30" width="138" height="46" rx="23" fill="#ffffff"/>
+    <text x="185" y="0" class="small">看进度</text>
+    <rect x="320" y="-30" width="138" height="46" rx="23" fill="#ffffff"/>
+    <text x="345" y="0" class="small">点审批</text>
+    <rect x="480" y="-30" width="138" height="46" rx="23" fill="#ffffff"/>
+    <text x="505" y="0" class="small">切线程</text>
+    <rect x="640" y="-30" width="168" height="46" rx="23" fill="#ffffff"/>
+    <text x="675" y="0" class="small">多账号轮转</text>
+  </g>
+</svg>

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

package/docs/troubleshooting.md

@@ -129,20 +129,14 @@ 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:
-
-```bash
-systemctl --user disable --now telegram-codex-app-bridge.service
-```
-
-Then restart FoxClaw:
+Stop the extra process or service, then restart FoxClaw:
 
 ```bash
 foxclaw restart
@@ -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

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
@@ -279,20 +279,11 @@ npm install -g @foxden-app/foxclaw@latest
 foxclaw start
 ```
 
-## 从旧项目名迁移
+如果 `~/.foxclaw/.env` 已经存在，`foxclaw init` 会先询问是否更新 Telegram 和工作目录相关字段，其它配置保持不变。
 
-如果这台机器仍在运行 `telegram-codex-app-bridge`，迁移一次即可：
+## 鸣谢
 
-```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

@@ -130,20 +130,14 @@ 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
 ```
 
-停掉旧服务：
-
-```bash
-systemctl --user disable --now telegram-codex-app-bridge.service
-```
-
-然后重启 FoxClaw：
+停掉多余进程或服务后，重启 FoxClaw：
 
 ```bash
 foxclaw restart

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",