@foxden-app/foxclaw 0.3.3 → 0.3.5

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/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,7 +5,7 @@ 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';
@@ -130,6 +130,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);
@@ -383,16 +386,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 +409,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 +458,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 +487,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 +531,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) {

package/docs/troubleshooting.md

@@ -182,6 +182,31 @@ 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
+```
+
+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:

package/docs/zh/troubleshooting.md

@@ -183,6 +183,31 @@ 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
+```
+
+确认 `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 重新安装：

package/package.json

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

package/skills/npm-publish/SKILL.md

@@ -5,7 +5,7 @@ description: Publish npm packages safely, especially packages that require npm 2
 
 # NPM Publish
 
-Use this skill to publish an npm package from a repo while preserving the exact web-auth flow that works in this environment.
+Use this skill to publish an npm package from a repo. Prefer the normal no-2FA publish path first. Fall back to npm web-auth only when npm explicitly prompts for it.
 
 ## Release Checklist
 
@@ -41,32 +41,44 @@ Use this skill to publish an npm package from a repo while preserving the exact
    git push
    ```
 
-## 2FA Web Auth Publish Flow
+## Publish Flow
 
-Use this exact flow when npm returns `EOTP` or when the account uses web auth for publish:
-
-1. Start publish in a TTY and disable local browser opening:
+1. Start publish in a TTY and disable local browser opening. This works both when npm publishes directly and when it asks for web auth:
    ```bash
    BROWSER=true npm publish
    ```
 
-2. Wait for npm to print:
+2. If npm publishes directly, it should finish with:
    ```text
-   Authenticate your account at:
-   https://www.npmjs.com/auth/cli/<auth-id>
-   Press ENTER to open in the browser...
+   + <package-name>@<version>
    ```
+   Then verify:
+   ```bash
+   npm view <package-name> version
+   git status --short --branch
+   ```
+
+3. If npm instead prints a web-auth prompt, use the fallback flow below.
+
+## Web Auth Fallback
+
+Use this only when npm prints:
+```text
+Authenticate your account at:
+https://www.npmjs.com/auth/cli/<auth-id>
+Press ENTER to open in the browser...
+```
 
-3. Send the URL to the user as a bare URL, not inside backticks or a code block. Bare URLs are easier to tap.
+1. Send the URL to the user as a bare URL, not inside backticks or a code block. Bare URLs are easier to tap.
 
-4. Do not press Enter immediately. Wait until the user says they clicked/confirmed the npm page.
+2. Do not press Enter immediately. Wait until the user says they clicked/confirmed the npm page.
 
-5. After the user confirms, send Enter to the still-running TTY process. npm should retrieve the temporary token and finish:
+3. After the user confirms, send Enter to the still-running TTY process. npm should retrieve the temporary token and finish:
    ```text
    + <package-name>@<version>
    ```
 
-6. Verify the published version:
+4. Verify the published version:
    ```bash
    npm view <package-name> version
    git status --short --branch
@@ -74,7 +86,7 @@ Use this exact flow when npm returns `EOTP` or when the account uses web auth fo
 
 ## Failure Modes
 
-- If `npm publish` is run without a TTY, npm may print an `EOTP` error with the auth URL redacted as `***`. Stop that attempt and rerun with a TTY.
+- If `npm publish` is run without a TTY, npm may print an `EOTP` error with the auth URL redacted as `***`. Stop that attempt and rerun with `BROWSER=true npm publish` in a TTY.
 - If `xdg-open` fails because the environment has no browser, rerun with `BROWSER=true npm publish`.
 - If the auth link expires or the publish process exits, rerun `BROWSER=true npm publish` to generate a new link.
 - If the user provides a classic authenticator OTP instead of using the web link, publish can be retried with `npm publish --otp <code>`, but prefer web auth when the user asks for a clickable confirmation link.