@foxden-app/foxclaw 0.3.6 → 0.3.8

package/README.md

@@ -40,7 +40,7 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex，
 - Git、Node、`.env` 都玩得转？直接往下看快速设置。
 - 卡住了？看 [故障排查](./docs/zh/troubleshooting.md)。
 
-最低要求：一个 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`。Codex 会在本地检查那个目录，然后把结果发回 Telegram。
 

package/README_EN.md

@@ -40,7 +40,7 @@ FoxClaw is more than message forwarding. It provides Telegram panels for Codex w
 - Already comfortable with Git, Node, and `.env` files? Use the quick setup below.
 - Something failed? Check [Troubleshooting](./docs/troubleshooting.md).
 
-The minimum install needs only a Telegram bot token, your numeric Telegram user id, Node.js 24, and a logged-in `codex` CLI. A first install usually takes 10–20 minutes.
+The minimum install needs only a Telegram bot token, your numeric Telegram user id, Node.js 24+, and a logged-in `codex` CLI. A first install usually takes 10–20 minutes.
 
 **30-second demo**: after FoxClaw is running, send `List files in DEFAULT_CWD` to your Telegram bot. FoxClaw asks local Codex to inspect that folder on your computer and sends the answer back to Telegram.
 

package/dist/controller/controller.d.ts

@@ -249,6 +249,8 @@ export declare class BridgeSessionCore {
     private retryTurnAfterAuthRotation;
     private selectNextCodexAuthCandidate;
     private listCodexAuthState;
+    private readCodexAuthSwitchLabels;
+    private codexAuthSwitchParams;
     private switchCodexAuthAndRestart;
     private buildNativeCollaborationMode;
     private buildCodexUsageStatusLines;

package/dist/controller/controller.js

@@ -3693,7 +3693,8 @@ export class BridgeSessionCore {
             await this.sendMessage(scopeId, renderAuthListMessage(locale, state, parseWeixinBridgeScope(scopeId) !== null));
             return;
         }
-        await this.sendMessage(scopeId, t(locale, 'auth_switching', { value: candidate.name }));
+        const switchLabels = await this.readCodexAuthSwitchLabels(candidate);
+        await this.sendMessage(scopeId, t(locale, 'auth_switching', this.codexAuthSwitchParams(locale, switchLabels.fromLabel, switchLabels.toLabel)));
         await this.switchCodexAuthAndRestart(scopeId, locale, candidate, false);
     }
     async handleAuthToggleCommand(scopeId, locale, args, disabled) {
@@ -4190,8 +4191,10 @@ export class BridgeSessionCore {
         }
         await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_choice_recorded'));
         this.pendingAuthChoiceLists.delete(localId);
+        const switchLabels = await this.readCodexAuthSwitchLabels(candidate);
+        const switchingMessage = t(locale, 'auth_switching', this.codexAuthSwitchParams(locale, switchLabels.fromLabel, switchLabels.toLabel));
         if (record.messageId !== null) {
-            await this.editMessage(event.scopeId, record.messageId, t(locale, 'auth_switching', { value: candidate.name }), []);
+            await this.editMessage(event.scopeId, record.messageId, switchingMessage, []);
         }
         await this.switchCodexAuthAndRestart(event.scopeId, locale, candidate, false);
     }
@@ -4207,16 +4210,17 @@ export class BridgeSessionCore {
         this.authRotationInProgress = true;
         try {
             const failedTargets = rotation.retry?.failedAuthTargets ?? this.authRotationFailedTargets;
-            const candidate = await this.selectNextCodexAuthCandidate(failedTargets);
+            const selection = await this.selectNextCodexAuthCandidate(failedTargets);
             const locale = this.localeForChat(rotation.scopeId);
-            if (!candidate) {
+            if (!selection) {
                 await this.sendMessage(rotation.scopeId, t(locale, 'auth_auto_no_candidate', {
                     error: formatShortStatusError(rotation.reason),
                 }));
                 return false;
             }
+            const { candidate, fromLabel, toLabel } = selection;
             await this.sendMessage(rotation.scopeId, t(locale, 'auth_auto_switching', {
-                value: candidate.name,
+                ...this.codexAuthSwitchParams(locale, fromLabel, toLabel),
                 error: formatShortStatusError(rotation.reason),
             }));
             await this.switchCodexAuthAndRestart(rotation.scopeId, locale, candidate, true);
@@ -4290,21 +4294,35 @@ export class BridgeSessionCore {
         for (let offset = 1; offset <= state.candidates.length; offset += 1) {
             const candidate = state.candidates[(currentIndex + offset + state.candidates.length) % state.candidates.length];
             if (candidate && !candidate.disabled && !failedTargets.has(candidate.path)) {
-                return candidate;
+                return { candidate, fromLabel: state.currentLabel, toLabel: await authPathDisplayLabel(candidate.path) };
             }
         }
-        return candidates[0] ?? null;
+        const candidate = candidates[0] ?? null;
+        return candidate ? { candidate, fromLabel: state.currentLabel, toLabel: await authPathDisplayLabel(candidate.path) } : null;
     }
     async listCodexAuthState() {
         return listCodexAuthState(this.store.listDisabledCodexAuthCandidateNames());
     }
+    async readCodexAuthSwitchLabels(candidate) {
+        const state = await this.listCodexAuthState();
+        return {
+            fromLabel: state.currentLabel,
+            toLabel: await authPathDisplayLabel(candidate.path),
+        };
+    }
+    codexAuthSwitchParams(locale, fromLabel, toLabel) {
+        return {
+            from: fromLabel ?? t(locale, 'none'),
+            to: toLabel,
+        };
+    }
     async switchCodexAuthAndRestart(scopeId, locale, candidate, automatic) {
-        await switchCodexAuth(candidate.path);
+        const result = await switchCodexAuth(candidate.path);
         this.authRotationFailedTargets.delete(candidate.path);
         this.pendingTurnErrors.clear();
         this.attachedThreads.clear();
         await this.app.restart();
-        const lines = [t(locale, automatic ? 'auth_auto_done' : 'auth_switch_done', { value: candidate.name })];
+        const lines = [t(locale, automatic ? 'auth_auto_done' : 'auth_switch_done', this.codexAuthSwitchParams(locale, result.fromLabel, result.toLabel))];
         lines.push(...await this.buildCodexUsageStatusLines(locale));
         await this.sendMessage(scopeId, lines.join('\n'));
     }
@@ -6913,7 +6931,7 @@ async function listCodexAuthState(disabledNames = new Set()) {
         authDir,
         authPath,
         currentTargetPath,
-        currentLabel: currentTargetPath ? path.basename(currentTargetPath) : null,
+        currentLabel: currentTargetPath ? await authPathDisplayLabel(currentTargetPath) : null,
         candidates,
     };
 }
@@ -6946,6 +6964,27 @@ async function resolveCurrentAuthTarget(authDir, authPath) {
     }
     return authPath;
 }
+async function resolveAuthFinalTargetPath(startPath) {
+    let currentPath = startPath;
+    const seen = new Set();
+    for (let depth = 0; depth < 20; depth += 1) {
+        const absolutePath = path.resolve(currentPath);
+        if (seen.has(absolutePath)) {
+            return currentPath;
+        }
+        seen.add(absolutePath);
+        const stat = await fs.lstat(currentPath).catch(() => null);
+        if (!stat?.isSymbolicLink()) {
+            return currentPath;
+        }
+        const target = await fs.readlink(currentPath);
+        currentPath = path.resolve(path.dirname(currentPath), target);
+    }
+    return currentPath;
+}
+async function authPathDisplayLabel(authPath) {
+    return path.basename(await resolveAuthFinalTargetPath(authPath));
+}
 async function pointCodexAuthAtTarget(authDir, authPath, targetPath) {
     await fs.mkdir(authDir, { recursive: true });
     const tempLink = path.join(authDir, `.auth.json.${process.pid}.${Date.now()}.tmp`);
@@ -6965,6 +7004,10 @@ async function switchCodexAuth(targetPath) {
         throw new Error(`Auth candidate is no longer available: ${path.basename(targetPath)}`);
     }
     await pointCodexAuthAtTarget(state.authDir, state.authPath, candidate.path);
+    return {
+        fromLabel: state.currentLabel,
+        toLabel: await authPathDisplayLabel(candidate.path),
+    };
 }
 function renderAuthListMessage(locale, state, includeWeixinCopyPaste = false) {
     const lines = [

package/dist/i18n.d.ts

@@ -133,10 +133,10 @@ declare const MESSAGES: {
         readonly auth_choice_expired: "This auth list is no longer active";
         readonly auth_choice_mismatch: "Auth choice does not match this message";
         readonly auth_choice_recorded: "Auth selected";
-        readonly auth_switching: "Switching Codex auth to {value}...";
-        readonly auth_switch_done: "Codex auth switched to {value}.";
-        readonly auth_auto_switching: "Codex auth problem detected ({error}). Switching to {value}...";
-        readonly auth_auto_done: "Auto-switched Codex auth to {value}.";
+        readonly auth_switching: "Switching Codex auth: {from} -> {to}...";
+        readonly auth_switch_done: "Codex auth switched: {from} -> {to}.";
+        readonly auth_auto_switching: "Codex auth problem detected ({error}). Switching: {from} -> {to}...";
+        readonly auth_auto_done: "Auto-switched Codex auth: {from} -> {to}.";
         readonly auth_auto_retrying: "Retrying the same request with the new auth...";
         readonly auth_auto_retry_thread_missing: "Auth was switched, but the original thread is no longer available ({threadId}). Retry was stopped to avoid creating duplicate sessions.";
         readonly auth_auto_no_candidate: "Codex auth problem detected ({error}), but no unused auth candidate is available.";
@@ -683,10 +683,10 @@ declare const MESSAGES: {
         readonly auth_choice_expired: "这个 auth 列表已经不再有效";
         readonly auth_choice_mismatch: "这个 auth 选择按钮不属于当前消息";
         readonly auth_choice_recorded: "已选择 auth";
-        readonly auth_switching: "正在切换 Codex auth 到 {value}...";
-        readonly auth_switch_done: "Codex auth 已切换到 {value}。";
-        readonly auth_auto_switching: "检测到 Codex auth 问题（{error}），正在切换到 {value}...";
-        readonly auth_auto_done: "已自动切换 Codex auth 到 {value}。";
+        readonly auth_switching: "正在切换 Codex auth：{from} -> {to}...";
+        readonly auth_switch_done: "Codex auth 已切换：{from} -> {to}。";
+        readonly auth_auto_switching: "检测到 Codex auth 问题（{error}），正在切换：{from} -> {to}...";
+        readonly auth_auto_done: "已自动切换 Codex auth：{from} -> {to}。";
         readonly auth_auto_retrying: "正在用新的 auth 重试同一条请求...";
         readonly auth_auto_retry_thread_missing: "Auth 已切换，但原线程已经不可用（{threadId}）。已停止重试，避免创建重复 session。";
         readonly auth_auto_no_candidate: "检测到 Codex auth 问题（{error}），但没有可用的未失败候选 auth。";

package/dist/i18n.js

@@ -131,10 +131,10 @@ const MESSAGES = {
         auth_choice_expired: 'This auth list is no longer active',
         auth_choice_mismatch: 'Auth choice does not match this message',
         auth_choice_recorded: 'Auth selected',
-        auth_switching: 'Switching Codex auth to {value}...',
-        auth_switch_done: 'Codex auth switched to {value}.',
-        auth_auto_switching: 'Codex auth problem detected ({error}). Switching to {value}...',
-        auth_auto_done: 'Auto-switched Codex auth to {value}.',
+        auth_switching: 'Switching Codex auth: {from} -> {to}...',
+        auth_switch_done: 'Codex auth switched: {from} -> {to}.',
+        auth_auto_switching: 'Codex auth problem detected ({error}). Switching: {from} -> {to}...',
+        auth_auto_done: 'Auto-switched Codex auth: {from} -> {to}.',
         auth_auto_retrying: 'Retrying the same request with the new auth...',
         auth_auto_retry_thread_missing: 'Auth was switched, but the original thread is no longer available ({threadId}). Retry was stopped to avoid creating duplicate sessions.',
         auth_auto_no_candidate: 'Codex auth problem detected ({error}), but no unused auth candidate is available.',
@@ -681,10 +681,10 @@ const MESSAGES = {
         auth_choice_expired: '这个 auth 列表已经不再有效',
         auth_choice_mismatch: '这个 auth 选择按钮不属于当前消息',
         auth_choice_recorded: '已选择 auth',
-        auth_switching: '正在切换 Codex auth 到 {value}...',
-        auth_switch_done: 'Codex auth 已切换到 {value}。',
-        auth_auto_switching: '检测到 Codex auth 问题（{error}），正在切换到 {value}...',
-        auth_auto_done: '已自动切换 Codex auth 到 {value}。',
+        auth_switching: '正在切换 Codex auth：{from} -> {to}...',
+        auth_switch_done: 'Codex auth 已切换：{from} -> {to}。',
+        auth_auto_switching: '检测到 Codex auth 问题（{error}），正在切换：{from} -> {to}...',
+        auth_auto_done: '已自动切换 Codex auth：{from} -> {to}。',
         auth_auto_retrying: '正在用新的 auth 重试同一条请求...',
         auth_auto_retry_thread_missing: 'Auth 已切换，但原线程已经不可用（{threadId}）。已停止重试，避免创建重复 session。',
         auth_auto_no_candidate: '检测到 Codex auth 问题（{error}），但没有可用的未失败候选 auth。',

package/docs/agent-assisted-install.md

@@ -39,7 +39,7 @@ DEFAULT_CWD=<paste absolute working directory here>
 
 Tasks:
 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.
+2. Ensure Node.js 24+ is available. If not, install or activate Node 24+ by any suitable method; nvm is only one common option.
 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.
 5. Run foxclaw init, then write ~/.foxclaw/.env. Never print or commit the bot token.

package/docs/install-for-beginners.md

@@ -25,17 +25,17 @@ You need:
 
 Use private chat first. Group and topic setup can wait until the bot replies reliably.
 
-## 2. Install Node.js 24
+## 2. Install Node.js 24+
 
-FoxClaw needs Node.js 24 because it uses the built-in SQLite runtime.
+FoxClaw needs Node.js 24+ because it uses the built-in SQLite runtime. It does not require nvm; you can use nvm, fnm, asdf, mise, Volta, Homebrew, or your system package manager.
 
-If you already have Node 24, this should print `v24...`:
+If you already have Node 24+, this should print `v24...` or newer:
 
 ```bash
 node -v
 ```
 
-If not, install Node 24 with `nvm`:
+If not, nvm is a good default for first-time users. Example:
 
 ```bash
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
@@ -47,7 +47,7 @@ node -v
 npm -v
 ```
 
-If `node -v` still shows an old version, close the terminal, open a new one, and run:
+If you use nvm and `node -v` still shows an old version, close the terminal, open a new one, and run:
 
 ```bash
 nvm use 24

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 start`. |
+| `[FAIL] node >= 24` | Your current shell is using an older Node.js. | Install or activate Node.js 24+ by any method, 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`. |
@@ -26,7 +26,7 @@ journalctl --user -u foxclaw.service -f
 
 ## Node Or npm Is Missing
 
-If you see `node: command not found` or `npm: command not found`, install Node.js 24 with `nvm`:
+If you see `node: command not found` or `npm: command not found`, install Node.js 24+ using your preferred tool, such as nvm, fnm, asdf, mise, Volta, Homebrew, or your system package manager. This is an nvm example:
 
 ```bash
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
@@ -38,7 +38,7 @@ node -v
 npm -v
 ```
 
-If it still fails, close the terminal, open a new one, and run:
+If you use nvm and it still fails, close the terminal, open a new one, and run:
 
 ```bash
 nvm use 24
@@ -48,7 +48,7 @@ nvm use 24
 
 If `npm install -g @openai/codex` fails with `EACCES`, `EPERM`, or `permission denied`, your global npm directory is not writable by your user.
 
-Recommended fix: use Node through `nvm`, then install again:
+Recommended fix: use a user-level Node.js 24+ install, then install again. This is an nvm example:
 
 ```bash
 nvm install 24
@@ -56,7 +56,7 @@ nvm use 24
 npm install -g @openai/codex
 ```
 
-Avoid `sudo npm install -g ...` unless you already understand how your Node installation is managed. Mixing `sudo`, system Node, and `nvm` is a common source of broken PATHs.
+Avoid `sudo npm install -g ...` unless you already understand how your Node installation is managed. Mixing `sudo`, system Node, and user-level Node managers is a common source of broken PATHs.
 
 If `codex` installs but FoxClaw still cannot find it, locate the binary:
 
@@ -211,9 +211,9 @@ foxclaw restart
 
 ## Service Starts With The Wrong Node Version
 
-The systemd installer records the absolute path of the Node process that is currently running FoxClaw. It does not rely on systemd loading `nvm.sh`. If you manage multiple Node versions with nvm, run `foxclaw start` from a Node 24 shell and the service will keep using that Node 24 path.
+The systemd installer records the absolute path of the Node process that is currently running FoxClaw. It does not rely on systemd loading `nvm.sh` or any other shell init script. Whether you use nvm, fnm, asdf, mise, Volta, Homebrew, or system Node, run `foxclaw start` from a Node 24+ shell and the service will keep using that Node 24+ path.
 
-If you installed the service from a shell using Node 22 or older, reinstall it from a Node 24 shell:
+If you installed the service from a shell using Node 22 or older, reinstall it from a Node 24+ shell. Example for nvm users:
 
 ```bash
 nvm use 24
@@ -221,7 +221,7 @@ foxclaw start
 systemctl --user status foxclaw.service
 ```
 
-The status output should show a Node 24 path in `ExecStart`. `foxclaw doctor` also checks the installed service Node path and warns if it is missing or older than 24.
+The status output should show a Node 24+ path in `ExecStart`. `foxclaw doctor` also checks the installed service Node path and warns if it is missing or older than 24.
 
 ## Does It Run After Reboot?
 

package/docs/user-manual.md

@@ -16,15 +16,15 @@ Your code, shell access, Codex auth, and runtime state stay on the host machine.
 
 ## 1. Full Setup
 
-### 1.1 Install Node.js 24
+### 1.1 Install Node.js 24+
 
-FoxClaw requires Node.js 24. Check first:
+FoxClaw requires Node.js 24+ and does not require nvm. Check first:
 
 ```bash
 node -v
 ```
 
-If this is not `v24...`, install Node 24 with `nvm`:
+If this is not `v24...` or newer, install Node 24+ with nvm, fnm, asdf, mise, Volta, Homebrew, or your system package manager. This is an nvm example:
 
 ```bash
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

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

@@ -38,7 +38,7 @@ DEFAULT_CWD=<把绝对工作目录粘贴在这里>
 
 任务：
 1. 先检查机器环境。如果已经存在 FoxClaw 服务，先报告再改服务。
-2. 确保 Node.js 24+ 可用；如果没有，请用 nvm 安装或切到 Node 24。
+2. 确保 Node.js 24+ 可用；如果没有，请用任意合适方式安装或切到 Node 24+，nvm 只是常见选择。
 3. 确保 Codex CLI 存在并且已经登录。如果需要登录，停下来告诉我具体要执行什么。
 4. 用 npm install -g @foxden-app/foxclaw@latest 安装或升级 FoxClaw。
 5. 运行 foxclaw init，然后写入 ~/.foxclaw/.env。不要打印或提交 bot token。

package/docs/zh/foxclaw-skill.md

@@ -5,7 +5,7 @@
 ## 适合什么时候用
 
 - 你想让 Codex 通过 SSH 帮另一台 Mac 安装 FoxClaw。
-- 你希望 agent 先检查环境，再决定如何安装 Node.js 24、Codex CLI 和 FoxClaw。
+- 你希望 agent 先检查环境，再决定如何安装 Node.js 24+、Codex CLI 和 FoxClaw。
 - 你不想手动复制每一步安装命令，但愿意提供 Telegram bot token、用户 ID 和默认工作目录。
 
 ## 基本流程

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

@@ -23,17 +23,17 @@ FoxClaw 跑在你的电脑上。手机发消息给 Telegram bot，bot 把消息
 - 一个 Codex 可以工作的目录，例如 `~/Projects` 或 `~/Desktop`
 - 第一次安装大约 10-20 分钟
 
-## 2. 安装 Node.js 24
+## 2. 安装 Node.js 24+
 
-FoxClaw 需要 Node.js 24，因为它使用 Node 内置 SQLite 运行时。
+FoxClaw 需要 Node.js 24+，因为它使用 Node 内置 SQLite 运行时。不强依赖 nvm；你可以用 nvm、fnm、asdf、mise、Volta、Homebrew 或系统包管理器安装。
 
-如果已经安装 Node 24，这条命令会输出 `v24...`：
+如果已经安装 Node 24+，这条命令会输出 `v24...` 或更高版本：
 
 ```bash
 node -v
 ```
 
-如果不是 Node 24，推荐用 `nvm` 安装：
+如果不是 Node 24+，推荐普通用户用 `nvm` 安装，示例：
 
 ```bash
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
@@ -45,7 +45,7 @@ node -v
 npm -v
 ```
 
-如果 `node -v` 仍然显示旧版本，关闭终端，重新打开后运行：
+如果使用 nvm 后 `node -v` 仍然显示旧版本，关闭终端，重新打开后运行：
 
 ```bash
 nvm use 24

package/docs/zh/troubleshooting.md

@@ -18,7 +18,7 @@ journalctl --user -u foxclaw.service -f
 
 | 现象 | 含义 | 处理方式 |
 | --- | --- | --- |
-| `[FAIL] node >= 24` | 当前 shell 使用的是旧版 Node.js。 | 运行 `nvm install 24 && nvm use 24`，再重新执行 `foxclaw doctor`。如果服务仍用旧 Node，从 Node 24 的 shell 里重新执行 `foxclaw start`。 |
+| `[FAIL] node >= 24` | 当前 shell 使用的是旧版 Node.js。 | 先用任意方式安装或切换到 Node.js 24+，再重新执行 `foxclaw doctor`。如果服务仍用旧 Node，从 Node 24+ 的 shell 里重新执行 `foxclaw start`。 |
 | `[FAIL] codex cli available` | `codex` 命令不在 PATH 里。 | 安装 Codex CLI 或修正 PATH，再确认 `codex --version` 可用。 |
 | `[FAIL] telegram bot token configured` | `.env` 里缺少 `TG_BOT_TOKEN`。 | 从 `@BotFather` 复制 token，填入 `.env`。 |
 | `[FAIL] telegram allowed user configured` | `.env` 里缺少 `TG_ALLOWED_USER_ID`。 | 从 `@userinfobot` 获取数字 ID，填入 `.env`。 |
@@ -26,7 +26,7 @@ journalctl --user -u foxclaw.service -f
 
 ## Node 或 npm 不存在
 
-如果看到 `node: command not found` 或 `npm: command not found`，用 `nvm` 安装 Node.js 24：
+如果看到 `node: command not found` 或 `npm: command not found`，先用你习惯的方式安装 Node.js 24+，例如 nvm、fnm、asdf、mise、Volta、Homebrew 或系统包管理器。下面是 nvm 示例：
 
 ```bash
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
@@ -38,7 +38,7 @@ node -v
 npm -v
 ```
 
-如果仍然失败，关闭终端，重新打开后运行：
+如果使用 nvm 后仍然失败，关闭终端，重新打开后运行：
 
 ```bash
 nvm use 24
@@ -48,7 +48,7 @@ nvm use 24
 
 如果 `npm install -g @openai/codex` 或 `npm install -g @foxden-app/foxclaw` 报 `EACCES`、`EPERM`、`permission denied`，说明当前全局 npm 目录不可写。
 
-推荐处理方式是通过 `nvm` 使用用户级 Node，然后重新安装：
+推荐处理方式是使用一个用户级 Node.js 24+，然后重新安装。下面是 nvm 示例：
 
 ```bash
 nvm install 24
@@ -57,7 +57,7 @@ npm install -g @openai/codex
 npm install -g @foxden-app/foxclaw
 ```
 
-除非你很清楚本机 Node 的安装方式，否则不要直接混用 `sudo npm install -g ...`。`sudo`、系统 Node 和 `nvm` 混在一起，常见结果是 PATH 断掉或服务启动时找不到命令。
+除非你很清楚本机 Node 的安装方式，否则不要直接混用 `sudo npm install -g ...`。`sudo`、系统 Node 和用户级 Node 管理器混在一起，常见结果是 PATH 断掉或服务启动时找不到命令。
 
 如果 `codex` 已安装但 FoxClaw 找不到它，先定位二进制：
 
@@ -212,9 +212,9 @@ foxclaw restart
 
 ## 服务用了错误的 Node 版本
 
-systemd 安装脚本会记录当时正在运行的 Node 绝对路径，不依赖 systemd 去加载 `nvm.sh`。如果你用 nvm 管多个 Node 版本，原则是：从 Node 24 的 shell 里执行 `foxclaw start`，服务之后就固定使用这个 Node 24 路径。
+systemd 安装脚本会记录当时正在运行的 Node 绝对路径，不依赖 systemd 去加载 `nvm.sh` 或其它 shell 初始化脚本。无论你用 nvm、fnm、asdf、mise、Volta、Homebrew 还是系统 Node，原则都是：从 Node 24+ 的 shell 里执行 `foxclaw start`，服务之后就固定使用这个 Node 24+ 路径。
 
-如果你从 Node 22 或更旧版本的 shell 里安装过服务，请从 Node 24 的 shell 重新安装：
+如果你从 Node 22 或更旧版本的 shell 里安装过服务，请从 Node 24+ 的 shell 重新安装。nvm 用户示例：
 
 ```bash
 nvm use 24
@@ -222,7 +222,7 @@ foxclaw start
 systemctl --user status foxclaw.service
 ```
 
-状态输出里应该能看到 Node 24 的路径。`foxclaw doctor` 也会检查已安装服务里的 Node 路径，如果发现路径不存在或版本低于 24，会提示重新运行 `foxclaw start`。
+状态输出里应该能看到 Node 24+ 的路径。`foxclaw doctor` 也会检查已安装服务里的 Node 路径，如果发现路径不存在或版本低于 24，会提示重新运行 `foxclaw start`。
 
 ## 重启后是否会自动运行
 

package/docs/zh/user-manual.md

@@ -16,15 +16,15 @@ FoxClaw 把本机 Codex 包成一个可从手机控制的服务。Telegram 或
 
 ## 1. 完整安装流程
 
-### 1.1 安装 Node.js 24
+### 1.1 安装 Node.js 24+
 
-FoxClaw 需要 Node.js 24。先检查：
+FoxClaw 需要 Node.js 24+，不强依赖 nvm。先检查：
 
 ```bash
 node -v
 ```
 
-如果不是 `v24...`，推荐用 `nvm`：
+如果不是 `v24...` 或更高版本，可以用 nvm、fnm、asdf、mise、Volta、Homebrew 或系统包管理器安装 Node 24+。下面是 nvm 示例：
 
 ```bash
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

package/package.json

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