@foxden-app/foxclaw 0.5.30 → 0.5.32

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.5.32 - 2026-06-11
+
+### 中文
+- 补齐 macOS launchd 适配检查：`doctor` 现在会检查已安装 plist 中记录的 Node 路径是否存在且为 Node 24+，并新增 `uninstall-launchd` 命令。
+- 新增 launchd plist 生成/解析的单元测试，并补充 macOS 服务状态、日志、代理和 Node 路径排障文档。
+
+### English
+- Filled macOS launchd adaptation gaps: `doctor` now checks that the Node path recorded in the installed plist exists and is Node 24+, and `uninstall-launchd` is available.
+- Added unit coverage for launchd plist generation/parsing and expanded macOS service status, log, proxy, and Node-path troubleshooting docs.
+
+## 0.5.31 - 2026-06-09
+
+### 中文
+- 修复自动 auth 轮转：目标候选切换后如果在 account/usage 验证阶段失败，会把该候选加入本次失败集合并继续轮询后续候选，而不是恢复原 auth 后停止。
+- 新增回归测试覆盖候选池中间账号验证失败时继续切到下一个可用账号并重试原请求。
+
+### English
+- Fixed automatic auth rotation so a candidate that fails account/usage validation after switching is added to the current failure set and FoxClaw keeps polling later candidates instead of stopping after restoring the previous auth.
+- Added regression coverage for continuing to the next usable account and retrying the original request when a middle candidate fails validation.
+
 ## 0.5.30 - 2026-06-09
 
 ### 中文

package/README.md

@@ -148,13 +148,20 @@ FoxClaw 的一大特色是自动多账号切换。当一个账号触发用量限
 foxclaw start
 ```
 
-Linux 上会安装/重启用户级 systemd 服务，macOS 上安装/重载 launchd。查看状态：
+Linux 上会安装/重启用户级 systemd 服务，macOS 上安装/重载 launchd。Linux 查看状态：
 
 ```bash
 systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
+macOS 查看状态和启动日志：
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
+
 也可以直接用包装命令：
 
 ```bash
@@ -319,6 +326,7 @@ foxclaw restart
 foxclaw update
 foxclaw stop
 foxclaw uninstall-systemd
+foxclaw uninstall-launchd
 ```
 
 ## 贡献

package/README_EN.md

@@ -155,6 +155,13 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
+To inspect macOS launchd state and startup logs:
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
+
 You can also use the wrapper commands:
 
 ```bash
@@ -319,6 +326,7 @@ foxclaw restart
 foxclaw update
 foxclaw stop
 foxclaw uninstall-systemd
+foxclaw uninstall-launchd
 ```
 
 ## Contributing

package/dist/controller/controller.js

@@ -5544,32 +5544,35 @@ export class BridgeSessionCore {
                     await this.sendMessage(rotation.scopeId, formatCodexAuthPoolSummary(locale, this.store.getCodexAuthPoolStats()));
                 }
             }
-            const selection = await this.selectNextCodexAuthCandidate(failedTargets);
-            if (!selection) {
-                await this.sendMessage(rotation.scopeId, t(locale, rotation.reasonKind === 'quota_limited' ? 'auth_quota_no_candidate' : 'auth_auto_no_candidate', {
-                    error: formatShortStatusError(rotation.reason),
-                }));
-                return false;
-            }
-            const { candidate, fromLabel, toLabel } = selection;
-            const switchingKey = rotation.reasonKind === 'quota_limited'
-                ? (this.config.authAutoDeleteNeedsRepair ? 'auth_quota_switching_quiet' : 'auth_quota_switching')
-                : (this.config.authAutoDeleteNeedsRepair ? 'auth_auto_switching_quiet' : 'auth_auto_switching');
-            await this.sendMessage(rotation.scopeId, this.config.authAutoDeleteNeedsRepair
-                ? t(locale, switchingKey, { error: formatShortStatusError(rotation.reason) })
-                : t(locale, switchingKey, {
-                    ...this.codexAuthSwitchParams(locale, fromLabel, toLabel),
-                    error: formatShortStatusError(rotation.reason),
-                }));
-            const outcome = await this.switchCodexAuthAndRestart(rotation.scopeId, locale, candidate, true, true, rotation.reasonKind);
-            if (!outcome.ok) {
+            while (true) {
+                const selection = await this.selectNextCodexAuthCandidate(failedTargets);
+                if (!selection) {
+                    await this.sendMessage(rotation.scopeId, t(locale, rotation.reasonKind === 'quota_limited' ? 'auth_quota_no_candidate' : 'auth_auto_no_candidate', {
+                        error: formatShortStatusError(rotation.reason),
+                    }));
+                    return false;
+                }
+                const { candidate, fromLabel, toLabel } = selection;
+                const switchingKey = rotation.reasonKind === 'quota_limited'
+                    ? (this.config.authAutoDeleteNeedsRepair ? 'auth_quota_switching_quiet' : 'auth_quota_switching')
+                    : (this.config.authAutoDeleteNeedsRepair ? 'auth_auto_switching_quiet' : 'auth_auto_switching');
+                await this.sendMessage(rotation.scopeId, this.config.authAutoDeleteNeedsRepair
+                    ? t(locale, switchingKey, { error: formatShortStatusError(rotation.reason) })
+                    : t(locale, switchingKey, {
+                        ...this.codexAuthSwitchParams(locale, fromLabel, toLabel),
+                        error: formatShortStatusError(rotation.reason),
+                    }));
+                const outcome = await this.switchCodexAuthAndRestart(rotation.scopeId, locale, candidate, true, true, rotation.reasonKind);
+                if (!outcome.ok) {
+                    failedTargets.add(candidate.path);
+                    continue;
+                }
+                if (rotation.retry) {
+                    await this.retryTurnAfterAuthRotation(rotation.scopeId, locale, rotation.retry);
+                    return true;
+                }
                 return false;
             }
-            if (rotation.retry) {
-                await this.retryTurnAfterAuthRotation(rotation.scopeId, locale, rotation.retry);
-                return true;
-            }
-            return false;
         }
         catch (error) {
             await this.handleAsyncError('codex.auth_rotation', error, rotation.scopeId);

package/dist/launchd.d.ts

@@ -0,0 +1,18 @@
+export interface FoxclawLaunchdPlistOptions {
+    label: string;
+    nodePath: string;
+    nodeArgs: string[];
+    entryPoint: string;
+    workingDirectory: string;
+    pathValue: string;
+    home: string;
+    user: string;
+    logname: string;
+    envPath: string;
+    proxyEnv: Record<string, string>;
+    stdoutPath: string;
+    stderrPath: string;
+}
+export declare function buildFoxclawLaunchdPlistText(options: FoxclawLaunchdPlistOptions): string;
+export declare function extractNodePathFromLaunchdPlist(plistText: string): string;
+export declare function xmlEscape(value: string): string;

package/dist/launchd.js

@@ -0,0 +1,75 @@
+export function buildFoxclawLaunchdPlistText(options) {
+    const nodeArgXml = options.nodeArgs.map((arg) => `    <string>${xmlEscape(arg)}</string>`).join('\n');
+    const proxyEnvXml = buildEnvironmentVariablesXml(options.proxyEnv, 4);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(options.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(options.nodePath)}</string>
+${nodeArgXml ? `${nodeArgXml}\n` : ''}    <string>${xmlEscape(options.entryPoint)}</string>
+    <string>serve</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(options.workingDirectory)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(options.pathValue)}</string>
+    <key>HOME</key>
+    <string>${xmlEscape(options.home)}</string>
+    <key>USER</key>
+    <string>${xmlEscape(options.user)}</string>
+    <key>LOGNAME</key>
+    <string>${xmlEscape(options.logname)}</string>
+    <key>FOXCLAW_ENV</key>
+    <string>${xmlEscape(options.envPath)}</string>
+${proxyEnvXml}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(options.stdoutPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(options.stderrPath)}</string>
+</dict>
+</plist>
+`;
+}
+export function extractNodePathFromLaunchdPlist(plistText) {
+    const programArguments = plistText.match(/<key>\s*ProgramArguments\s*<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    const firstArgument = programArguments?.[1]?.match(/<string>([\s\S]*?)<\/string>/)?.[1] ?? '';
+    return firstArgument ? xmlUnescape(firstArgument.trim()) : '';
+}
+export function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function xmlUnescape(value) {
+    return value
+        .replace(/&apos;/g, "'")
+        .replace(/&quot;/g, '"')
+        .replace(/&gt;/g, '>')
+        .replace(/&lt;/g, '<')
+        .replace(/&amp;/g, '&');
+}
+function buildEnvironmentVariablesXml(values, indent) {
+    const prefix = ' '.repeat(indent);
+    const entries = [];
+    for (const [key, value] of Object.entries(values)) {
+        if (!value)
+            continue;
+        entries.push(`${prefix}<key>${xmlEscape(key)}</key>`);
+        entries.push(`${prefix}<string>${xmlEscape(value)}</string>`);
+    }
+    return entries.length > 0 ? `${entries.join('\n')}\n` : '';
+}

package/dist/main.js

@@ -11,6 +11,7 @@ import { APP_HOME, DEFAULT_CODEX_TELEGRAM_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PA
 import { createAuthRefreshNotificationAggregator, } from './auth/notifications.js';
 import { acquireProcessLock, LockHeldError } from './lock.js';
 import { readRuntimeStatus, writeRuntimeStatus } from './runtime.js';
+import { buildFoxclawLaunchdPlistText, extractNodePathFromLaunchdPlist, } from './launchd.js';
 import { buildFoxclawSystemdUnitText, buildSystemdRestartHelperArgs, cgroupContainsSystemdUnit, refreshFoxclawExecStartDropIns, removeFoxclawExecStartDropIns, } from './systemd.js';
 import { createSelfUpdateRuntime, inferPnpmHomeFromEntryPoint, performSelfUpdate, readSelfUpdateStatus, writeSelfUpdateStatus, } from './update.js';
 const rawCommand = process.argv[2];
@@ -113,6 +114,10 @@ async function main() {
         uninstallSystemd();
         return;
     }
+    if (command === 'uninstall-launchd') {
+        uninstallLaunchd();
+        return;
+    }
     if (command === 'install-launchd') {
         requireNode24(command);
         installLaunchd();
@@ -173,7 +178,7 @@ Usage:
   foxclaw start|restart|stop
   foxclaw update
   foxclaw install-systemd|uninstall-systemd
-  foxclaw install-launchd
+  foxclaw install-launchd|uninstall-launchd
   foxclaw weixin-login [account-id]
   foxclaw --version
   foxclaw --help`);
@@ -1344,6 +1349,7 @@ function runDoctorChecks() {
     warnIfProxyEnvMissingFromLoadedEnv();
     warnIfProxyConfigNeedsAttention();
     warnIfInstalledServiceNodeLooksWrong();
+    warnIfInstalledLaunchdNodeLooksWrong();
     warnIfSystemdUserLingerDisabled();
     return passed;
 }
@@ -1373,7 +1379,12 @@ function warnIfProxyConfigNeedsAttention() {
         return;
     }
     console.log('[WARN] Only ALL_PROXY/all_proxy is configured. Node service proxying works best with HTTP_PROXY/HTTPS_PROXY.');
-    console.log('[WARN] For SOCKS-only hosts, set FOXCLAW_PROXYCHAINS_CONF=/absolute/path/to/proxychains.conf and run foxclaw restart.');
+    if (process.platform === 'linux') {
+        console.log('[WARN] For SOCKS-only hosts, set FOXCLAW_PROXYCHAINS_CONF=/absolute/path/to/proxychains.conf and run foxclaw restart.');
+    }
+    else {
+        console.log('[WARN] On macOS launchd, prefer HTTP_PROXY/HTTPS_PROXY; FOXCLAW_PROXYCHAINS_CONF is Linux-only.');
+    }
 }
 function warnIfProxyEnvMissingFromLoadedEnv() {
     const envPath = serviceEnvPath();
@@ -1417,6 +1428,37 @@ function warnIfInstalledServiceNodeLooksWrong() {
     console.log(`[WARN] installed service node is older than 24: ${nodePath}${version ? ` (${version})` : ''}`);
     console.log('[WARN] Run foxclaw start from a Node 24 shell to refresh the service unit.');
 }
+function warnIfInstalledLaunchdNodeLooksWrong() {
+    if (process.platform !== 'darwin') {
+        return;
+    }
+    const plistPath = launchdPlistPath();
+    let text = '';
+    try {
+        text = fs.readFileSync(plistPath, 'utf8');
+    }
+    catch {
+        return;
+    }
+    const nodePath = extractNodePathFromLaunchdPlist(text);
+    if (!nodePath) {
+        return;
+    }
+    if (!fs.existsSync(nodePath)) {
+        console.log(`[WARN] installed launchd node is missing: ${nodePath}`);
+        console.log('[WARN] Run foxclaw start from a Node 24 shell to refresh the launchd plist.');
+        return;
+    }
+    const result = spawnSync(nodePath, ['-p', 'process.versions.node'], { encoding: 'utf8' });
+    const version = result.status === 0 ? result.stdout.trim() : '';
+    const major = Number.parseInt(version.split('.')[0] ?? '', 10);
+    if (Number.isFinite(major) && major >= 24) {
+        console.log(`[OK] launchd node >= 24: ${nodePath}`);
+        return;
+    }
+    console.log(`[WARN] installed launchd node is older than 24: ${nodePath}${version ? ` (${version})` : ''}`);
+    console.log('[WARN] Run foxclaw start from a Node 24 shell to refresh the launchd plist.');
+}
 function warnIfSystemdUserLingerDisabled() {
     if (process.platform !== 'linux' || !hasCommand('loginctl')) {
         return;
@@ -1588,54 +1630,28 @@ function installLaunchd() {
         process.exit(1);
     }
     const home = process.env.HOME || '';
-    const plist = path.join(home, 'Library', 'LaunchAgents', 'app.foxden.foxclaw.plist');
+    const plist = launchdPlistPath();
     const envPath = serviceEnvPath();
     const configDir = path.dirname(envPath);
     const nodeProxyArgs = hasStandardNodeProxyEnv() ? ['--use-env-proxy'] : [];
-    const nodeProxyArgXml = nodeProxyArgs.map((arg) => `    <string>${xmlEscape(arg)}</string>`).join('\n');
-    const proxyEnvXml = buildLaunchdProxyEnvironmentXml();
     fs.mkdirSync(path.dirname(plist), { recursive: true });
     fs.mkdirSync(configDir, { recursive: true });
     fs.mkdirSync(path.join(APP_HOME, 'logs'), { recursive: true });
-    fs.writeFileSync(plist, `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>app.foxden.foxclaw</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>${xmlEscape(process.execPath)}</string>
-${nodeProxyArgXml ? `${nodeProxyArgXml}\n` : ''}    <string>${xmlEscape(entryPoint)}</string>
-    <string>serve</string>
-  </array>
-  <key>WorkingDirectory</key>
-  <string>${xmlEscape(configDir)}</string>
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>PATH</key>
-    <string>${xmlEscape(process.env.PATH || '')}</string>
-    <key>HOME</key>
-    <string>${xmlEscape(home)}</string>
-    <key>USER</key>
-    <string>${xmlEscape(process.env.USER || '')}</string>
-    <key>LOGNAME</key>
-    <string>${xmlEscape(process.env.LOGNAME || process.env.USER || '')}</string>
-    <key>FOXCLAW_ENV</key>
-    <string>${xmlEscape(envPath)}</string>
-${proxyEnvXml}
-  </dict>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <true/>
-  <key>StandardOutPath</key>
-  <string>${xmlEscape(path.join(APP_HOME, 'logs', 'launchd.out.log'))}</string>
-  <key>StandardErrorPath</key>
-  <string>${xmlEscape(path.join(APP_HOME, 'logs', 'launchd.err.log'))}</string>
-</dict>
-</plist>
-`);
+    fs.writeFileSync(plist, buildFoxclawLaunchdPlistText({
+        label: 'app.foxden.foxclaw',
+        nodePath: process.execPath,
+        nodeArgs: nodeProxyArgs,
+        entryPoint,
+        workingDirectory: configDir,
+        pathValue: process.env.PATH || '',
+        home,
+        user: process.env.USER || '',
+        logname: process.env.LOGNAME || process.env.USER || '',
+        envPath,
+        proxyEnv: launchdProxyEnvironment(),
+        stdoutPath: path.join(APP_HOME, 'logs', 'launchd.out.log'),
+        stderrPath: path.join(APP_HOME, 'logs', 'launchd.err.log'),
+    }));
     spawnSync('launchctl', ['unload', plist], { stdio: 'ignore' });
     spawnChecked('launchctl', ['load', plist]);
     console.log(`Installed ${plist}`);
@@ -1648,7 +1664,7 @@ function stopLaunchd() {
         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');
+    const plist = launchdPlistPath();
     if (!fs.existsSync(plist)) {
         console.error(`launchd plist not found: ${plist}`);
         process.exit(1);
@@ -1656,6 +1672,19 @@ function stopLaunchd() {
     spawnChecked('launchctl', ['unload', plist]);
     console.log(`Stopped ${plist}`);
 }
+function uninstallLaunchd() {
+    if (process.platform !== 'darwin') {
+        console.error('launchd uninstall is only available on macOS');
+        process.exit(1);
+    }
+    const plist = launchdPlistPath();
+    spawnSync('launchctl', ['unload', plist], { stdio: 'ignore' });
+    fs.rmSync(plist, { force: true });
+    console.log(`Removed ${plist}`);
+}
+function launchdPlistPath() {
+    return path.join(process.env.HOME || '', 'Library', 'LaunchAgents', 'app.foxden.foxclaw.plist');
+}
 function buildServicePath(nodeDir) {
     const pnpmPath = resolveCommand('pnpm');
     const inferredPnpmHome = inferPnpmHomeFromEntryPoint(entryPoint) || '';
@@ -1716,16 +1745,15 @@ function hasStandardNodeProxyEnv() {
 function proxyEnvValue(key) {
     return process.env[key]?.trim() || '';
 }
-function buildLaunchdProxyEnvironmentXml() {
-    const entries = [];
+function launchdProxyEnvironment() {
+    const entries = {};
     for (const key of PROXY_ENV_KEYS) {
         const value = proxyEnvValue(key);
         if (!value)
             continue;
-        entries.push(`    <key>${xmlEscape(key)}</key>`);
-        entries.push(`    <string>${xmlEscape(value)}</string>`);
+        entries[key] = value;
     }
-    return entries.length > 0 ? `${entries.join('\n')}\n` : '';
+    return entries;
 }
 function spawnChecked(commandName, args) {
     const result = spawnSync(commandName, args, { stdio: 'inherit' });
@@ -1739,14 +1767,6 @@ function systemdEscape(value) {
 function systemdUnescape(value) {
     return value.replace(/\\x20/g, ' ').replace(/\\\\/g, '\\');
 }
-function xmlEscape(value) {
-    return value
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&apos;');
-}
 async function runWeixinLoginCli() {
     const [{ attachIlinkRuntimeFromBridgeLogger }, { startWeixinLoginWithQr, waitForWeixinLogin }, { accountFilePath, saveWeixinAccount }, { Logger },] = await Promise.all([
         import('./channels/weixin/ilink/runtime_attach.js'),

package/docs/agent-assisted-install.md

@@ -48,6 +48,7 @@ Tasks:
 8. Ask me to send /help, /status, and /auth privately to each configured Telegram bot; confirm /auth names that bot runtime.
 9. Verify the final state:
    - foxclaw.service is active/enabled on Linux
+   - the app.foxden.foxclaw launchd job is loaded on macOS, with no startup errors in ~/.foxclaw/logs/launchd.err.log
    - 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_TOKENS and never print the full token or full .env content.
 11. If multiple bots are enabled, confirm foxclaw status lists independent app-servers; group-chat tests must mention or reply to the intended bot.

package/docs/install-for-beginners.md

@@ -263,7 +263,12 @@ If install reports that linger could not be enabled automatically, run:
 sudo loginctl enable-linger "$USER"
 ```
 
-On macOS, `foxclaw start` manages launchd and starts FoxClaw when you log in.
+On macOS, `foxclaw start` manages launchd and starts FoxClaw when you log in. Check state and startup logs with:
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
 
 For foreground debugging, stop the service first and then run `foxclaw serve`.
 
@@ -275,7 +280,7 @@ Check current status:
 foxclaw status
 ```
 
-Restart Linux service after changing `.env`:
+Restart after changing `.env`:
 
 ```bash
 foxclaw restart
@@ -293,6 +298,12 @@ Uninstall Linux service:
 foxclaw uninstall-systemd
 ```
 
+Uninstall macOS launchd service:
+
+```bash
+foxclaw uninstall-launchd
+```
+
 Update FoxClaw later:
 
 ```bash

package/docs/troubleshooting.md

@@ -14,6 +14,13 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
+If FoxClaw is installed as a macOS launchd service, check:
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
+
 ## Doctor Failures
 
 | Symptom | Meaning | Fix |
@@ -136,6 +143,13 @@ systemctl --user is-active foxclaw.service
 pgrep -af foxclaw
 ```
 
+On macOS, use:
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+pgrep -af foxclaw
+```
+
 Stop the extra process or service, then restart FoxClaw:
 
 ```bash
@@ -200,12 +214,18 @@ When multiple bots share a group, unaddressed messages intentionally do not trig
 
 If Telegram shows `ChatGPT backend 403 Forbidden`, or the app-server log contains `Unable to load site`, `cf-ray`, or `chatgpt.com/backend-api`, the auth file is not necessarily broken. The service process is usually reaching ChatGPT with the wrong network/proxy/IP.
 
-A common cause is that your shell or project `.env` has proxy variables, while the systemd/launchd service reads a different env file. Check the env file installed into the service:
+A common cause is that your shell or project `.env` has proxy variables, while the systemd/launchd service reads a different env file. On Linux, check the env file installed into the service:
 
 ```bash
 systemctl --user cat foxclaw.service
 ```
 
+On macOS, inspect `FOXCLAW_ENV` in the launchd plist:
+
+```bash
+plutil -p ~/Library/LaunchAgents/app.foxden.foxclaw.plist | grep FOXCLAW_ENV -A1
+```
+
 `foxclaw init` detects proxy environment variables in the current shell and asks whether to save them into the FoxClaw `.env`. If you skipped that step, `foxclaw doctor` warns when it sees proxy variables in the shell but not in the FoxClaw env file.
 
 Make sure the file referenced by `Environment=FOXCLAW_ENV=...` contains your proxy variables, for example:
@@ -243,6 +263,8 @@ FoxClaw writes proxychains into the main service and removes stale FoxClaw `Exec
 
 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.
 
+macOS launchd follows the same rule: the plist records the absolute Node path that ran `foxclaw start` and does not rely on login-shell initialization.
+
 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
@@ -251,7 +273,15 @@ 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.
+On macOS:
+
+```bash
+nvm use 24
+foxclaw start
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+```
+
+The status output should show a Node 24+ path. `foxclaw doctor` also checks the installed systemd/launchd service Node path and warns if it is missing or older than 24.
 
 ## Does It Run After Reboot?
 

package/docs/user-manual.md

@@ -145,7 +145,14 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
-On macOS, `foxclaw start` manages launchd. For foreground debugging, stop the background service and run:
+On macOS, `foxclaw start` manages launchd. Check launchd state and startup logs with:
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
+
+For foreground debugging, stop the background service and run:
 
 ```bash
 foxclaw stop

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

@@ -47,6 +47,7 @@ DEFAULT_CWD=<把绝对工作目录粘贴在这里>
 8. 让我在每个已配置的 Telegram bot 私聊里发送 /help、/status 和 /auth；确认 /auth 显示对应 bot runtime。
 9. 验证最终状态：
    - Linux 上 foxclaw.service 处于 active/enabled
+   - macOS 上 app.foxden.foxclaw launchd job 已加载，并且 ~/.foxclaw/logs/launchd.err.log 没有启动错误
    - foxclaw status 可以正常输出
 10. 汇报执行过的命令、最终状态和后续看日志的命令。请隐藏 TG_BOT_TOKENS，不要打印完整 token 或完整 .env。
 11. 如果启用了多个 bot，确认 foxclaw status 列出独立 app-server；群聊测试必须点名或回复目标 bot。

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

@@ -261,7 +261,12 @@ journalctl --user -u foxclaw.service -f
 sudo loginctl enable-linger "$USER"
 ```
 
-macOS 上 `foxclaw start` 管理 launchd，并在你登录后启动 FoxClaw。
+macOS 上 `foxclaw start` 管理 launchd，并在你登录后启动 FoxClaw。查看状态和启动日志：
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
 
 前台调试时，先停后台服务，再运行 `foxclaw serve`。
 
@@ -291,6 +296,12 @@ foxclaw stop
 foxclaw uninstall-systemd
 ```
 
+卸载 macOS launchd 服务：
+
+```bash
+foxclaw uninstall-launchd
+```
+
 以后升级 FoxClaw：
 
 ```bash

package/docs/zh/troubleshooting.md

@@ -14,6 +14,13 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
+如果 FoxClaw 是 macOS launchd 服务，再看：
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
+
 ## Doctor 检查失败
 
 | 现象 | 含义 | 处理方式 |
@@ -137,6 +144,13 @@ systemctl --user is-active foxclaw.service
 pgrep -af foxclaw
 ```
 
+macOS 上用：
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+pgrep -af foxclaw
+```
+
 停掉多余进程或服务后，重启 FoxClaw：
 
 ```bash
@@ -201,12 +215,18 @@ tail -f ~/.foxclaw/logs/codex-app-server-bot<id>.log
 
 如果 Telegram 里看到 `ChatGPT backend 403 Forbidden`，或者 app-server 日志里出现 `Unable to load site`、`cf-ray`、`chatgpt.com/backend-api`，通常不是 `auth.json` 文件坏了，而是服务进程访问 ChatGPT 后端时没有走正确网络。
 
-常见原因是：你在 shell 里配置了代理，或者项目 `.env` 里有代理，但 systemd/launchd 服务实际读的是另一个 env 文件。先看服务用的是哪个 env：
+常见原因是：你在 shell 里配置了代理，或者项目 `.env` 里有代理，但 systemd/launchd 服务实际读的是另一个 env 文件。Linux 先看服务用的是哪个 env：
 
 ```bash
 systemctl --user cat foxclaw.service
 ```
 
+macOS 看 launchd plist 里的 `FOXCLAW_ENV`：
+
+```bash
+plutil -p ~/Library/LaunchAgents/app.foxden.foxclaw.plist | grep FOXCLAW_ENV -A1
+```
+
 `foxclaw init` 会检测当前 shell 里的代理环境变量，并询问是否保存到 FoxClaw `.env`。如果你跳过了这一步，`foxclaw doctor` 会在发现“shell 有代理，但 FoxClaw env 没有代理”时给出 `[WARN]`。
 
 确认 `Environment=FOXCLAW_ENV=...` 指向的文件里有你的代理配置，例如：
@@ -244,6 +264,8 @@ FoxClaw 会把 proxychains 写进主 service，并清理旧的 FoxClaw `ExecStar
 
 systemd 安装脚本会记录当时正在运行的 Node 绝对路径，不依赖 systemd 去加载 `nvm.sh` 或其它 shell 初始化脚本。无论你用 nvm、fnm、asdf、mise、Volta、Homebrew 还是系统 Node，原则都是：从 Node 24+ 的 shell 里执行 `foxclaw start`，服务之后就固定使用这个 Node 24+ 路径。
 
+macOS launchd 也是同样原则：plist 会记录执行 `foxclaw start` 时的 Node 绝对路径，不依赖登录 shell 初始化脚本。
+
 如果你从 Node 22 或更旧版本的 shell 里安装过服务，请从 Node 24+ 的 shell 重新安装。nvm 用户示例：
 
 ```bash
@@ -252,7 +274,15 @@ foxclaw start
 systemctl --user status foxclaw.service
 ```
 
-状态输出里应该能看到 Node 24+ 的路径。`foxclaw doctor` 也会检查已安装服务里的 Node 路径，如果发现路径不存在或版本低于 24，会提示重新运行 `foxclaw start`。
+macOS 用户示例：
+
+```bash
+nvm use 24
+foxclaw start
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+```
+
+状态输出里应该能看到 Node 24+ 的路径。`foxclaw doctor` 也会检查已安装 systemd/launchd 服务里的 Node 路径，如果发现路径不存在或版本低于 24，会提示重新运行 `foxclaw start`。
 
 ## 重启后是否会自动运行
 

package/docs/zh/user-manual.md

@@ -145,7 +145,14 @@ systemctl --user status foxclaw.service
 journalctl --user -u foxclaw.service -f
 ```
 
-macOS 上 `foxclaw start` 会管理 launchd。前台排障时，先停后台服务，再运行：
+macOS 上 `foxclaw start` 会管理 launchd。查看 launchd 状态和启动日志：
+
+```bash
+launchctl print "gui/$(id -u)/app.foxden.foxclaw"
+tail -f ~/.foxclaw/logs/launchd.err.log ~/.foxclaw/logs/service.log
+```
+
+前台排障时，先停后台服务，再运行：
 
 ```bash
 foxclaw stop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.5.30",
+  "version": "0.5.32",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",
@@ -48,6 +48,7 @@
     "install-systemd": "node dist/main.js install-systemd",
     "uninstall-systemd": "node dist/main.js uninstall-systemd",
     "install-launchd": "node dist/main.js install-launchd",
+    "uninstall-launchd": "node dist/main.js uninstall-launchd",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "test": "node --test --import tsx $(find src -name '*.test.ts' -print)",

package/skills/foxclaw/SKILL.md

@@ -144,8 +144,8 @@ Use `--no-start` by default when preparing a second Mac before a unique bot toke
 
 After either bootstrap path:
 
-1. Run `node dist/main.js doctor` in the installed bridge repo.
-2. If launchd was installed, run `node dist/main.js status`.
+1. Run `node dist/main.js doctor` in the installed bridge repo.
+2. If launchd was installed, run `node dist/main.js status`, `launchctl print "gui/$(id -u)/app.foxden.foxclaw"`, and inspect `~/.foxclaw/logs/launchd.err.log` if either status check fails.
 3. Check `codex login status`. If authentication is missing, stop and tell the user exactly how to log in.
 4. If the bridge is expected to answer in a Telegram group, confirm:
    - `privacy mode` is disabled