@foxden-app/foxclaw 0.3.4 → 0.3.6

package/.env.example

@@ -29,6 +29,13 @@ TELEGRAM_PREVIEW_THROTTLE_MS=800
 THREAD_LIST_LIMIT=10
 CODEX_CLI_BIN=/absolute/path/to/codex
 
+# Optional: proxy for ChatGPT/Codex backend requests when FoxClaw runs as a service.
+# Put these in the same env file that `foxclaw start` installs into systemd/launchd.
+# HTTP_PROXY=http://127.0.0.1:7890
+# HTTPS_PROXY=http://127.0.0.1:7890
+# ALL_PROXY=socks5://127.0.0.1:7891
+# NO_PROXY=127.0.0.1,localhost
+
 # Weixin (iLink): run `foxclaw weixin-login` once, then enable:
 # WX_ENABLED=true
 # Comma-separated iLink user ids allowed to chat (see account JSON linkedIlinkUserId)

package/README.md

@@ -70,7 +70,7 @@ foxclaw doctor
 foxclaw start
 ```
 
-`foxclaw init` 会创建 `~/.foxclaw/.env`，并在终端里提示填写 Telegram bot token、Telegram 数字用户 ID 和默认工作目录。任何一项都可以直接回车跳过，之后再用 `$EDITOR ~/.foxclaw/.env` 手动修改。
+`foxclaw init` 会创建 `~/.foxclaw/.env`，并在终端里提示填写 Telegram bot token、Telegram 数字用户 ID 和默认工作目录。如果当前 shell 里有 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 等代理变量，也会询问是否写入 FoxClaw 配置，避免服务启动后 Codex 走不到同一条网络。任何一项都可以直接回车跳过，之后再用 `$EDITOR ~/.foxclaw/.env` 手动修改。
 
 跑 `doctor` 或 `start` 之前先把 `.env` 填好。私聊模式最小配置：
 

package/README_EN.md

@@ -70,7 +70,7 @@ foxclaw doctor
 foxclaw start
 ```
 
-`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`.
+`foxclaw init` creates `~/.foxclaw/.env` and prompts for the Telegram bot token, your numeric Telegram user id, and the default workspace. If the current shell has proxy variables such as `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY`, it also asks whether to save them into the FoxClaw config so the service uses the same network path as your working Codex CLI. 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:
 

package/dist/config.d.ts

@@ -8,6 +8,8 @@ export declare const DEFAULT_LOCK_PATH: string;
 export declare const DEFAULT_CODEX_APP_SERVER_STATE_PATH: string;
 export declare const DEFAULT_CODEX_APP_SERVER_LOG_PATH: string;
 export declare const DEFAULT_ENV_PATH: string;
+export declare function resolveEnvPath(): string;
+export declare function getLoadedEnvPath(): string | null;
 export declare function loadEnv(): void;
 export interface AppConfig {
     tgBotToken: string;

package/dist/config.js

@@ -12,21 +12,28 @@ export const DEFAULT_CODEX_APP_SERVER_STATE_PATH = path.join(APP_HOME, 'runtime'
 export const DEFAULT_CODEX_APP_SERVER_LOG_PATH = path.join(APP_HOME, 'logs', 'codex-app-server.log');
 export const DEFAULT_ENV_PATH = path.join(APP_HOME, '.env');
 let envLoaded = false;
-export function loadEnv() {
-    if (envLoaded)
-        return;
-    envLoaded = true;
+let loadedEnvPath = null;
+export function resolveEnvPath() {
     const explicitPath = process.env.FOXCLAW_ENV?.trim();
     if (explicitPath) {
-        dotenv.config({ path: explicitPath, override: true });
-        return;
+        return path.resolve(explicitPath);
     }
     const cwdEnvPath = path.join(process.cwd(), '.env');
     if (fs.existsSync(cwdEnvPath)) {
-        dotenv.config({ path: cwdEnvPath });
-        return;
+        return cwdEnvPath;
     }
-    dotenv.config({ path: DEFAULT_ENV_PATH });
+    return DEFAULT_ENV_PATH;
+}
+export function getLoadedEnvPath() {
+    return loadedEnvPath;
+}
+export function loadEnv() {
+    if (envLoaded)
+        return;
+    envLoaded = true;
+    const envPath = resolveEnvPath();
+    loadedEnvPath = envPath;
+    dotenv.config({ path: envPath, override: Boolean(process.env.FOXCLAW_ENV?.trim()) });
 }
 export function loadConfig() {
     loadEnv();

package/dist/controller/controller.js

@@ -7065,6 +7065,9 @@ function cloneAuthRetryContext(context) {
     };
 }
 function isCodexAuthRotationError(params) {
+    if (isChatGptBackendAccessBlocked(collectCodexErrorText(params))) {
+        return false;
+    }
     const code = stringOrNull(params?.error?.codexErrorInfo) ?? stringOrNull(params?.error?.code);
     if (code && /usageLimitExceeded|auth|unauthorized|forbidden|login/i.test(code)) {
         return true;
@@ -7073,15 +7076,77 @@ function isCodexAuthRotationError(params) {
     return /(usage limit|rate limit|not authenticated|unauthorized|forbidden|sign in|log in|login|auth)/i.test(message);
 }
 function formatCodexNotificationError(params) {
+    const collected = collectCodexErrorText(params);
+    const known = formatKnownCodexAccessError(collected);
+    if (known) {
+        return known;
+    }
     const message = stringOrNull(params?.error?.message);
     if (message) {
-        return message;
+        return clipUserFacingError(cleanUserFacingError(message));
     }
     const code = stringOrNull(params?.error?.codexErrorInfo) ?? stringOrNull(params?.error?.code);
     if (code) {
-        return code;
+        return clipUserFacingError(cleanUserFacingError(code));
+    }
+    return clipUserFacingError(cleanUserFacingError(JSON.stringify(params?.error ?? params ?? {})));
+}
+function collectCodexErrorText(params) {
+    const parts = [
+        stringOrNull(params?.error?.message),
+        stringOrNull(params?.error?.additionalDetails),
+        stringOrNull(params?.additionalDetails),
+        stringOrNull(params?.error?.codexErrorInfo),
+        stringOrNull(params?.error?.code),
+    ].filter((part) => part !== null);
+    if (parts.length > 0) {
+        return parts.join(' ');
+    }
+    try {
+        return JSON.stringify(params?.error ?? params ?? {});
+    }
+    catch {
+        return String(params?.error ?? params ?? '');
     }
-    return JSON.stringify(params?.error ?? params ?? {});
+}
+function formatKnownCodexAccessError(raw) {
+    if (!isChatGptBackendAccessBlocked(raw)) {
+        return null;
+    }
+    const ray = raw.match(/\bcf-ray:\s*([A-Za-z0-9-]+)/i)?.[1]
+        ?? raw.match(/\bRay ID:\s*([A-Za-z0-9-]+)/i)?.[1]
+        ?? null;
+    return `ChatGPT backend 403 Forbidden: service network/proxy/IP is blocked, not necessarily auth.json invalid. Check HTTP_PROXY/HTTPS_PROXY in the FoxClaw env file and restart FoxClaw${ray ? ` (cf-ray: ${ray})` : ''}.`;
+}
+function isChatGptBackendAccessBlocked(raw) {
+    const value = raw.toLowerCase();
+    const targetsChatGptBackend = value.includes('chatgpt.com/backend-api')
+        || value.includes('wss://chatgpt.com/backend-api');
+    const isForbidden = value.includes('403 forbidden')
+        || value.includes('status 403')
+        || value.includes('httpstatuscode":403')
+        || value.includes('httpstatuscode:403');
+    const looksLikeHtmlBlock = value.includes('<html')
+        || value.includes('text/html')
+        || value.includes('cf-ray')
+        || value.includes('unable to load site')
+        || value.includes('if you are using a vpn');
+    return targetsChatGptBackend && isForbidden && looksLikeHtmlBlock;
+}
+function cleanUserFacingError(raw) {
+    return raw
+        .replace(/<script\b[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<style\b[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function clipUserFacingError(raw, limit = 900) {
+    const cleaned = raw.trim();
+    if (cleaned.length <= limit) {
+        return cleaned;
+    }
+    return `${cleaned.slice(0, limit - 3)}...`;
 }
 function parseUserInputQuestions(params) {
     const rawQuestions = Array.isArray(params?.questions)
@@ -7484,7 +7549,12 @@ function formatLocalTimestamp(seconds) {
     return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
 }
 function formatShortStatusError(error) {
-    const message = formatUserError(error).replace(/\s+/g, ' ').trim();
+    const raw = formatUserError(error);
+    const known = formatKnownCodexAccessError(raw);
+    if (known) {
+        return known.length > 120 ? `${known.slice(0, 117)}...` : known;
+    }
+    const message = cleanUserFacingError(raw);
     return message.length > 120 ? `${message.slice(0, 117)}...` : message;
 }
 function isThreadNotFoundError(error) {

package/dist/main.js

@@ -5,13 +5,23 @@ 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';
+import { APP_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, getLoadedEnvPath, loadConfig, loadEnv, } from './config.js';
 import { acquireProcessLock, LockHeldError } from './lock.js';
 import { readRuntimeStatus, writeRuntimeStatus } from './runtime.js';
 const command = process.argv[2] || 'serve';
 loadEnv();
 const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const entryPoint = fileURLToPath(import.meta.url);
+const PROXY_ENV_KEYS = [
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'ALL_PROXY',
+    'NO_PROXY',
+    'http_proxy',
+    'https_proxy',
+    'all_proxy',
+    'no_proxy',
+];
 async function main() {
     if (command === 'init') {
         await initConfig();
@@ -130,6 +140,9 @@ async function runServeCli() {
                 updatedAt: new Date().toISOString(),
                 channels: { telegram: false, weixin: false },
             });
+            await app.stop({ terminateServer: true }).catch((error) => {
+                logger.warn('codex.app-server.stop_failed', { error: serializeError(error) });
+            });
             store?.close();
             processLock.release();
             process.exit(0);
@@ -157,6 +170,7 @@ async function initConfig() {
         console.log(`Created ${envPath}`);
     }
     if (!canPromptForInit()) {
+        printProxyEnvHint(envPath);
         console.log(`Edit it manually, then run: foxclaw doctor`);
         return;
     }
@@ -171,6 +185,7 @@ async function configureEnvInteractively(envPath, existed) {
         if (existed) {
             const updateExisting = (await rl.question('Update Telegram/workspace setup fields now? [y/N]: ')).trim().toLowerCase();
             if (updateExisting !== 'y' && updateExisting !== 'yes') {
+                await maybeSaveProxyEnvFromShell(rl, envPath);
                 console.log(`Edit it manually, then run: foxclaw doctor`);
                 return;
             }
@@ -181,6 +196,7 @@ async function configureEnvInteractively(envPath, existed) {
         const updates = {};
         const skipped = [];
         const warnings = [];
+        Object.assign(updates, await maybeSaveProxyEnvFromShell(rl, envPath));
         const token = sanitizeEnvInput(await rl.question('Telegram bot token (TG_BOT_TOKEN): '));
         if (token) {
             updates.TG_BOT_TOKEN = token;
@@ -304,6 +320,64 @@ function writeEnvUpdates(envPath, updates) {
     }
     fs.writeFileSync(envPath, text);
 }
+async function maybeSaveProxyEnvFromShell(rl, envPath) {
+    const proxyUpdates = detectMissingProxyEnv(envPath);
+    const keys = Object.keys(proxyUpdates);
+    if (keys.length === 0) {
+        return {};
+    }
+    console.log(`Detected proxy env in this shell: ${keys.join(', ')}`);
+    const answer = (await rl.question('Save these proxy settings to FoxClaw .env for service use? [Y/n]: ')).trim().toLowerCase();
+    if (answer === 'n' || answer === 'no') {
+        console.log(`Skipped proxy env. Add it to ${envPath} if ChatGPT access needs a proxy.`);
+        return {};
+    }
+    writeEnvUpdates(envPath, proxyUpdates);
+    console.log(`Saved ${keys.join(', ')} to ${envPath}`);
+    return proxyUpdates;
+}
+function printProxyEnvHint(envPath) {
+    const proxyUpdates = detectMissingProxyEnv(envPath);
+    const keys = Object.keys(proxyUpdates);
+    if (keys.length === 0) {
+        return;
+    }
+    console.log(`[WARN] Proxy env detected in this shell but missing from ${envPath}: ${keys.join(', ')}`);
+    console.log(`[WARN] Add those proxy variables to ${envPath} if ChatGPT/Codex needs a proxy.`);
+}
+function detectMissingProxyEnv(envPath) {
+    const existing = readEnvFileKeys(envPath);
+    const existingCanonical = new Set(Array.from(existing, canonicalProxyEnvKey));
+    const updates = {};
+    for (const key of PROXY_ENV_KEYS) {
+        const value = process.env[key]?.trim();
+        if (!value || existing.has(key) || existingCanonical.has(canonicalProxyEnvKey(key))) {
+            continue;
+        }
+        updates[key] = value;
+    }
+    return updates;
+}
+function canonicalProxyEnvKey(key) {
+    return key.toUpperCase();
+}
+function readEnvFileKeys(envPath) {
+    const keys = new Set();
+    let text = '';
+    try {
+        text = fs.readFileSync(envPath, 'utf8');
+    }
+    catch {
+        return keys;
+    }
+    for (const line of text.split(/\r?\n/)) {
+        const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (match?.[1]) {
+            keys.add(match[1]);
+        }
+    }
+    return keys;
+}
 function formatEnvValue(value) {
     const cleaned = value.replace(/[\r\n]/g, '').trim();
     if (!/[\s#"\\]/.test(cleaned))
@@ -373,8 +447,52 @@ function runDoctorChecks() {
         console.log(`[FAIL] default cwd missing: ${cwd}`);
         passed = false;
     }
+    warnIfProxyEnvMissingFromLoadedEnv();
+    warnIfInstalledServiceNodeLooksWrong();
     return passed;
 }
+function warnIfProxyEnvMissingFromLoadedEnv() {
+    const envPath = serviceEnvPath();
+    const proxyUpdates = detectMissingProxyEnv(envPath);
+    const keys = Object.keys(proxyUpdates);
+    if (keys.length === 0) {
+        return;
+    }
+    console.log(`[WARN] proxy env is present in this shell but missing from ${envPath}: ${keys.join(', ')}`);
+    console.log(`[WARN] systemd/launchd services do not inherit your shell; add those variables to the FoxClaw env file if Codex needs a proxy.`);
+}
+function warnIfInstalledServiceNodeLooksWrong() {
+    if (process.platform !== 'linux') {
+        return;
+    }
+    const unitPath = path.join(process.env.XDG_CONFIG_HOME || path.join(process.env.HOME || '', '.config'), 'systemd', 'user', 'foxclaw.service');
+    let text = '';
+    try {
+        text = fs.readFileSync(unitPath, 'utf8');
+    }
+    catch {
+        return;
+    }
+    const execStart = text.match(/^ExecStart=(.+)$/m)?.[1]?.trim();
+    const nodePath = execStart ? systemdUnescape(execStart.split(/\s+/)[0] ?? '') : '';
+    if (!nodePath) {
+        return;
+    }
+    if (!fs.existsSync(nodePath)) {
+        console.log(`[WARN] installed service node is missing: ${nodePath}`);
+        console.log('[WARN] Run foxclaw start from a Node 24 shell to refresh the service unit.');
+        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] service node >= 24: ${nodePath}`);
+        return;
+    }
+    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 installSystemd() {
     if (!hasCommand('systemctl')) {
         console.error('systemctl not found (need systemd)');
@@ -383,16 +501,14 @@ function installSystemd() {
     const unitName = 'foxclaw.service';
     const userSystemdDir = path.join(process.env.XDG_CONFIG_HOME || path.join(process.env.HOME || '', '.config'), 'systemd', 'user');
     const unitPath = path.join(userSystemdDir, unitName);
-    const configDir = path.dirname(process.env.FOXCLAW_ENV?.trim() || DEFAULT_ENV_PATH);
+    const envPath = serviceEnvPath();
+    const configDir = path.dirname(envPath);
     const nodeBin = process.execPath;
     const nodeDir = path.dirname(nodeBin);
     const pathValue = buildServicePath(nodeDir);
     fs.mkdirSync(userSystemdDir, { recursive: true });
     fs.mkdirSync(configDir, { recursive: true });
     fs.mkdirSync(path.join(APP_HOME, 'logs'), { recursive: true });
-    const foxclawEnvLine = process.env.FOXCLAW_ENV?.trim()
-        ? `Environment=FOXCLAW_ENV=${systemdEscape(process.env.FOXCLAW_ENV.trim())}\n`
-        : '';
     fs.writeFileSync(unitPath, `[Unit]
 Description=FoxClaw local Codex execution bridge
 Documentation=https://github.com/foxden-app/foxclaw
@@ -408,7 +524,8 @@ Environment=HOME=${systemdEscape(process.env.HOME || '')}
 Environment=USER=${systemdEscape(process.env.USER || '')}
 Environment=LOGNAME=${systemdEscape(process.env.LOGNAME || process.env.USER || '')}
 Environment=PATH=${systemdEscape(pathValue)}
-${foxclawEnvLine}ExecStart=${systemdEscape(nodeBin)} ${systemdEscape(entryPoint)} serve
+Environment=FOXCLAW_ENV=${systemdEscape(envPath)}
+ExecStart=${systemdEscape(nodeBin)} ${systemdEscape(entryPoint)} serve
 Restart=always
 RestartSec=10
 TimeoutStopSec=45
@@ -456,15 +573,11 @@ function installLaunchd() {
     }
     const home = process.env.HOME || '';
     const plist = path.join(home, 'Library', 'LaunchAgents', 'app.foxden.foxclaw.plist');
-    const configDir = path.dirname(process.env.FOXCLAW_ENV?.trim() || DEFAULT_ENV_PATH);
+    const envPath = serviceEnvPath();
+    const configDir = path.dirname(envPath);
     fs.mkdirSync(path.dirname(plist), { recursive: true });
     fs.mkdirSync(configDir, { recursive: true });
     fs.mkdirSync(path.join(APP_HOME, 'logs'), { recursive: true });
-    const foxclawEnvXml = process.env.FOXCLAW_ENV?.trim()
-        ? `    <key>FOXCLAW_ENV</key>
-    <string>${xmlEscape(process.env.FOXCLAW_ENV.trim())}</string>
-`
-        : '';
     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">
@@ -489,7 +602,8 @@ function installLaunchd() {
     <string>${xmlEscape(process.env.USER || '')}</string>
     <key>LOGNAME</key>
     <string>${xmlEscape(process.env.LOGNAME || process.env.USER || '')}</string>
-${foxclawEnvXml}
+    <key>FOXCLAW_ENV</key>
+    <string>${xmlEscape(envPath)}</string>
   </dict>
   <key>RunAtLoad</key>
   <true/>
@@ -532,6 +646,9 @@ function buildServicePath(nodeDir) {
     ];
     return parts.filter((part, index) => part && parts.indexOf(part) === index).join(':');
 }
+function serviceEnvPath() {
+    return path.resolve(process.env.FOXCLAW_ENV?.trim() || getLoadedEnvPath() || DEFAULT_ENV_PATH);
+}
 function spawnChecked(commandName, args) {
     const result = spawnSync(commandName, args, { stdio: 'inherit' });
     if (result.status !== 0) {
@@ -541,6 +658,9 @@ function spawnChecked(commandName, args) {
 function systemdEscape(value) {
     return value.replace(/\\/g, '\\\\').replace(/ /g, '\\x20');
 }
+function systemdUnescape(value) {
+    return value.replace(/\\x20/g, ' ').replace(/\\\\/g, '\\');
+}
 function xmlEscape(value) {
     return value
         .replace(/&/g, '&amp;')

package/docs/troubleshooting.md

@@ -182,9 +182,38 @@ Bridge logs are stored here:
 tail -f ~/.foxclaw/logs/service.log
 ```
 
+## ChatGPT Backend 403 Or Unable To Load Site
+
+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:
+
+```bash
+systemctl --user cat foxclaw.service
+```
+
+`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:
+
+```dotenv
+HTTP_PROXY=http://127.0.0.1:20171
+HTTPS_PROXY=http://127.0.0.1:20171
+ALL_PROXY=socks5://127.0.0.1:20170
+NO_PROXY=127.0.0.1,localhost
+```
+
+Restart FoxClaw after editing. The restart also restarts the managed Codex app-server so the new proxy environment takes effect:
+
+```bash
+foxclaw restart
+```
+
 ## Service Starts With The Wrong Node Version
 
-The systemd installer captures the `node` binary from your current PATH. If you installed the service from a shell using Node 22 or older, reinstall it from a Node 24 shell:
+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.
+
+If you installed the service from a shell using Node 22 or older, reinstall it from a Node 24 shell:
 
 ```bash
 nvm use 24
@@ -192,7 +221,7 @@ foxclaw start
 systemctl --user status foxclaw.service
 ```
 
-The status output should show a Node 24 path in `ExecStart`.
+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

@@ -100,7 +100,7 @@ Both install the same published npm package. Use one global package manager cons
 
 ### 1.6 Fill In The Config
 
-`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:
+`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. If the current shell has proxy variables such as `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY`, it also asks whether to save them into the FoxClaw config so the service-side Codex app-server uses the same network. Press Enter on any field to skip it, then edit manually if needed:
 
 ```bash
 $EDITOR ~/.foxclaw/.env

package/docs/zh/troubleshooting.md

@@ -183,9 +183,38 @@ Bridge 日志默认在：
 tail -f ~/.foxclaw/logs/service.log
 ```
 
+## ChatGPT 后端 403 或 Unable to load site
+
+如果 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：
+
+```bash
+systemctl --user cat foxclaw.service
+```
+
+`foxclaw init` 会检测当前 shell 里的代理环境变量，并询问是否保存到 FoxClaw `.env`。如果你跳过了这一步，`foxclaw doctor` 会在发现“shell 有代理，但 FoxClaw env 没有代理”时给出 `[WARN]`。
+
+确认 `Environment=FOXCLAW_ENV=...` 指向的文件里有你的代理配置，例如：
+
+```dotenv
+HTTP_PROXY=http://127.0.0.1:20171
+HTTPS_PROXY=http://127.0.0.1:20171
+ALL_PROXY=socks5://127.0.0.1:20170
+NO_PROXY=127.0.0.1,localhost
+```
+
+改完后重启 FoxClaw。重启会同时重启托管的 Codex app-server，让新代理生效：
+
+```bash
+foxclaw restart
+```
+
 ## 服务用了错误的 Node 版本
 
-systemd 安装脚本会记录当时 PATH 里的 `node`。如果你从 Node 22 或更旧版本的 shell 里安装过服务，请从 Node 24 的 shell 重新安装：
+systemd 安装脚本会记录当时正在运行的 Node 绝对路径，不依赖 systemd 去加载 `nvm.sh`。如果你用 nvm 管多个 Node 版本，原则是：从 Node 24 的 shell 里执行 `foxclaw start`，服务之后就固定使用这个 Node 24 路径。
+
+如果你从 Node 22 或更旧版本的 shell 里安装过服务，请从 Node 24 的 shell 重新安装：
 
 ```bash
 nvm use 24
@@ -193,7 +222,7 @@ foxclaw start
 systemctl --user status foxclaw.service
 ```
 
-状态输出里应该能看到 Node 24 的路径。
+状态输出里应该能看到 Node 24 的路径。`foxclaw doctor` 也会检查已安装服务里的 Node 路径，如果发现路径不存在或版本低于 24，会提示重新运行 `foxclaw start`。
 
 ## 重启后是否会自动运行
 

package/docs/zh/user-manual.md

@@ -100,7 +100,7 @@ foxclaw init
 
 ### 1.6 填写配置
 
-`foxclaw init` 会创建默认配置文件 `~/.foxclaw/.env`，并提示填写 Telegram bot token、Telegram 数字用户 ID 和默认工作目录。任何一项都可以直接回车跳过，之后再手动编辑：
+`foxclaw init` 会创建默认配置文件 `~/.foxclaw/.env`，并提示填写 Telegram bot token、Telegram 数字用户 ID 和默认工作目录。如果当前 shell 里有 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 等代理变量，它也会询问是否写入 FoxClaw 配置，让服务里的 Codex app-server 使用同样的网络。任何一项都可以直接回车跳过，之后再手动编辑：
 
 ```bash
 $EDITOR ~/.foxclaw/.env

package/package.json

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