@foxden-app/foxclaw 0.3.10 → 0.3.12

package/.env.example

@@ -29,12 +29,15 @@ 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.
+# Optional: standard HTTP(S) proxy for Telegram and ChatGPT/Codex backend requests.
 # Put these in the same env file that `foxclaw start` installs into systemd/launchd.
+# FoxClaw passes them to the service and enables Node's env proxy support.
 # 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
+# Optional Linux-only fallback when a service must run through proxychains4.
+# FOXCLAW_PROXYCHAINS_CONF=/absolute/path/to/proxychains.conf
 
 # Weixin (iLink): run `foxclaw weixin-login` once, then enable:
 # WX_ENABLED=true

package/dist/main.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 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';
+import { refreshFoxclawExecStartDropIns, removeFoxclawExecStartDropIns } from './systemd.js';
 const rawCommand = process.argv[2];
 const command = rawCommand || 'serve';
 loadEnv();
@@ -23,6 +24,7 @@ const PROXY_ENV_KEYS = [
     'all_proxy',
     'no_proxy',
 ];
+const STANDARD_NODE_PROXY_ENV_KEYS = ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy'];
 async function main() {
     if (isVersionCommand(command)) {
         console.log(readPackageVersion());
@@ -492,9 +494,38 @@ function runDoctorChecks() {
         passed = false;
     }
     warnIfProxyEnvMissingFromLoadedEnv();
+    warnIfProxyConfigNeedsAttention();
     warnIfInstalledServiceNodeLooksWrong();
     return passed;
 }
+function warnIfProxyConfigNeedsAttention() {
+    const proxychainsConf = process.env.FOXCLAW_PROXYCHAINS_CONF?.trim() || '';
+    if (proxychainsConf) {
+        if (process.platform !== 'linux') {
+            console.log('[WARN] FOXCLAW_PROXYCHAINS_CONF is only used by systemd on Linux.');
+        }
+        else if (!fs.existsSync(proxychainsConf)) {
+            console.log(`[WARN] FOXCLAW_PROXYCHAINS_CONF does not exist: ${proxychainsConf}`);
+        }
+        else if (!hasCommand('proxychains4')) {
+            console.log('[WARN] proxychains4 is not available, but FOXCLAW_PROXYCHAINS_CONF is set.');
+        }
+        else {
+            console.log(`[OK] proxychains config exists: ${proxychainsConf}`);
+        }
+        return;
+    }
+    const proxyKeys = PROXY_ENV_KEYS.filter((key) => proxyEnvValue(key));
+    if (proxyKeys.length === 0) {
+        return;
+    }
+    if (hasStandardNodeProxyEnv()) {
+        console.log(`[OK] service proxy env configured: ${proxyKeys.join(', ')}`);
+        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.');
+}
 function warnIfProxyEnvMissingFromLoadedEnv() {
     const envPath = serviceEnvPath();
     const proxyUpdates = detectMissingProxyEnv(envPath);
@@ -518,7 +549,7 @@ function warnIfInstalledServiceNodeLooksWrong() {
         return;
     }
     const execStart = text.match(/^ExecStart=(.+)$/m)?.[1]?.trim();
-    const nodePath = execStart ? systemdUnescape(execStart.split(/\s+/)[0] ?? '') : '';
+    const nodePath = execStart ? extractNodePathFromExecStart(execStart) : '';
     if (!nodePath) {
         return;
     }
@@ -537,6 +568,14 @@ 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 extractNodePathFromExecStart(execStart) {
+    const tokens = execStart.split(/\s+/).map(systemdUnescape).filter(Boolean);
+    const directNode = tokens[0] || '';
+    if (path.basename(directNode) === 'node') {
+        return directNode;
+    }
+    return tokens.find((token) => path.basename(token) === 'node') || directNode;
+}
 function installSystemd() {
     if (!hasCommand('systemctl')) {
         console.error('systemctl not found (need systemd)');
@@ -550,9 +589,16 @@ function installSystemd() {
     const nodeBin = process.execPath;
     const nodeDir = path.dirname(nodeBin);
     const pathValue = buildServicePath(nodeDir);
+    const proxychainsConf = process.env.FOXCLAW_PROXYCHAINS_CONF?.trim() || '';
+    const proxychainsBin = proxychainsConf ? resolveCommand('proxychains4') || '/usr/bin/proxychains4' : '';
+    const nodeProxyArgs = !proxychainsConf && hasStandardNodeProxyEnv() ? ' --use-env-proxy' : '';
+    const execStart = proxychainsConf
+        ? `${systemdEscape(proxychainsBin)} -f ${systemdEscape(proxychainsConf)} ${systemdEscape(nodeBin)} ${systemdEscape(entryPoint)} serve`
+        : `${systemdEscape(nodeBin)}${nodeProxyArgs} ${systemdEscape(entryPoint)} serve`;
     fs.mkdirSync(userSystemdDir, { recursive: true });
     fs.mkdirSync(configDir, { recursive: true });
     fs.mkdirSync(path.join(APP_HOME, 'logs'), { recursive: true });
+    const escapedEntryPoint = systemdEscape(entryPoint);
     fs.writeFileSync(unitPath, `[Unit]
 Description=FoxClaw local Codex execution bridge
 Documentation=https://github.com/foxden-app/foxclaw
@@ -564,12 +610,13 @@ StartLimitBurst=5
 [Service]
 Type=simple
 WorkingDirectory=${systemdEscape(configDir)}
+EnvironmentFile=-${systemdEscape(envPath)}
 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)}
 Environment=FOXCLAW_ENV=${systemdEscape(envPath)}
-ExecStart=${systemdEscape(nodeBin)} ${systemdEscape(entryPoint)} serve
+ExecStart=${execStart}
 Restart=always
 RestartSec=10
 TimeoutStopSec=45
@@ -578,6 +625,24 @@ KillMode=process
 [Install]
 WantedBy=default.target
 `);
+    if (proxychainsConf) {
+        console.log(`[OK] systemd proxychains enabled: ${proxychainsConf}`);
+    }
+    else if (nodeProxyArgs) {
+        console.log('[OK] systemd Node env proxy enabled');
+    }
+    if (proxychainsConf) {
+        const dropInUpdates = removeFoxclawExecStartDropIns(userSystemdDir, unitName);
+        for (const update of dropInUpdates) {
+            console.log(`[OK] removed stale FoxClaw ExecStart override: ${update.path}`);
+        }
+    }
+    else {
+        const dropInUpdates = refreshFoxclawExecStartDropIns(userSystemdDir, unitName, escapedEntryPoint);
+        for (const update of dropInUpdates) {
+            console.log(`[OK] updated FoxClaw ExecStart override: ${update.path}`);
+        }
+    }
     spawnChecked('systemctl', ['--user', 'daemon-reload']);
     spawnChecked('systemctl', ['--user', 'enable', unitName]);
     const restarted = spawnSync('systemctl', ['--user', 'restart', unitName], { stdio: 'inherit' });
@@ -619,6 +684,9 @@ function installLaunchd() {
     const plist = path.join(home, 'Library', 'LaunchAgents', 'app.foxden.foxclaw.plist');
     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 });
@@ -631,7 +699,7 @@ function installLaunchd() {
   <key>ProgramArguments</key>
   <array>
     <string>${xmlEscape(process.execPath)}</string>
-    <string>${xmlEscape(entryPoint)}</string>
+${nodeProxyArgXml ? `${nodeProxyArgXml}\n` : ''}    <string>${xmlEscape(entryPoint)}</string>
     <string>serve</string>
   </array>
   <key>WorkingDirectory</key>
@@ -648,6 +716,7 @@ function installLaunchd() {
     <string>${xmlEscape(process.env.LOGNAME || process.env.USER || '')}</string>
     <key>FOXCLAW_ENV</key>
     <string>${xmlEscape(envPath)}</string>
+${proxyEnvXml}
   </dict>
   <key>RunAtLoad</key>
   <true/>
@@ -663,6 +732,9 @@ function installLaunchd() {
     spawnSync('launchctl', ['unload', plist], { stdio: 'ignore' });
     spawnChecked('launchctl', ['load', plist]);
     console.log(`Installed ${plist}`);
+    if (nodeProxyArgs.length > 0) {
+        console.log('[OK] launchd Node env proxy enabled');
+    }
 }
 function stopLaunchd() {
     if (process.platform !== 'darwin') {
@@ -693,6 +765,23 @@ function buildServicePath(nodeDir) {
 function serviceEnvPath() {
     return path.resolve(process.env.FOXCLAW_ENV?.trim() || getLoadedEnvPath() || DEFAULT_ENV_PATH);
 }
+function hasStandardNodeProxyEnv() {
+    return STANDARD_NODE_PROXY_ENV_KEYS.some((key) => Boolean(proxyEnvValue(key)));
+}
+function proxyEnvValue(key) {
+    return process.env[key]?.trim() || '';
+}
+function buildLaunchdProxyEnvironmentXml() {
+    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>`);
+    }
+    return entries.length > 0 ? `${entries.join('\n')}\n` : '';
+}
 function spawnChecked(commandName, args) {
     const result = spawnSync(commandName, args, { stdio: 'inherit' });
     if (result.status !== 0) {

package/dist/systemd.d.ts

@@ -0,0 +1,14 @@
+export interface SystemdDropInUpdate {
+    path: string;
+    replacements: number;
+}
+export declare function refreshFoxclawExecStartDropIns(userSystemdDir: string, unitName: string, escapedEntryPoint: string): SystemdDropInUpdate[];
+export declare function removeFoxclawExecStartDropIns(userSystemdDir: string, unitName: string): SystemdDropInUpdate[];
+export declare function refreshFoxclawExecStartText(text: string, escapedEntryPoint: string): {
+    text: string;
+    replacements: number;
+};
+export declare function removeFoxclawExecStartText(text: string): {
+    text: string;
+    replacements: number;
+};

package/dist/systemd.js

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const FOXCLAW_MAIN_PATH_RE = /\S*(?:\.pnpm\/@foxden-app\+foxclaw@[^/\s]+\/node_modules\/@foxden-app\/foxclaw|node_modules\/@foxden-app\/foxclaw)\/dist\/main\.js/g;
+export function refreshFoxclawExecStartDropIns(userSystemdDir, unitName, escapedEntryPoint) {
+    const dropInDir = path.join(userSystemdDir, `${unitName}.d`);
+    let names;
+    try {
+        names = fs.readdirSync(dropInDir).filter((name) => name.endsWith('.conf')).sort();
+    }
+    catch {
+        return [];
+    }
+    const updates = [];
+    for (const name of names) {
+        const filePath = path.join(dropInDir, name);
+        let before = '';
+        try {
+            before = fs.readFileSync(filePath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const { text, replacements } = refreshFoxclawExecStartText(before, escapedEntryPoint);
+        if (replacements === 0 || text === before) {
+            continue;
+        }
+        fs.writeFileSync(filePath, text, 'utf8');
+        updates.push({ path: filePath, replacements });
+    }
+    return updates;
+}
+export function removeFoxclawExecStartDropIns(userSystemdDir, unitName) {
+    const dropInDir = path.join(userSystemdDir, `${unitName}.d`);
+    let names;
+    try {
+        names = fs.readdirSync(dropInDir).filter((name) => name.endsWith('.conf')).sort();
+    }
+    catch {
+        return [];
+    }
+    const updates = [];
+    for (const name of names) {
+        const filePath = path.join(dropInDir, name);
+        let before = '';
+        try {
+            before = fs.readFileSync(filePath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const { text, replacements } = removeFoxclawExecStartText(before);
+        if (replacements === 0 || text === before) {
+            continue;
+        }
+        if (isEmptyServiceDropIn(text)) {
+            fs.rmSync(filePath, { force: true });
+        }
+        else {
+            fs.writeFileSync(filePath, text, 'utf8');
+        }
+        updates.push({ path: filePath, replacements });
+    }
+    return updates;
+}
+export function refreshFoxclawExecStartText(text, escapedEntryPoint) {
+    let replacements = 0;
+    const lines = text.split(/(\r?\n)/);
+    const refreshed = lines.map((part) => {
+        if (!part.startsWith('ExecStart=') || part.trim() === 'ExecStart=') {
+            return part;
+        }
+        return part.replace(FOXCLAW_MAIN_PATH_RE, () => {
+            replacements += 1;
+            return escapedEntryPoint;
+        });
+    });
+    return { text: refreshed.join(''), replacements };
+}
+export function removeFoxclawExecStartText(text) {
+    const hasFoxclawExecStart = text
+        .split(/\r?\n/)
+        .some((line) => line.startsWith('ExecStart=') && FOXCLAW_MAIN_PATH_RE.test(line));
+    if (!hasFoxclawExecStart) {
+        return { text, replacements: 0 };
+    }
+    let replacements = 0;
+    const lines = text.split(/(\r?\n)/);
+    const cleaned = lines.map((part) => {
+        if (!part.startsWith('ExecStart=')) {
+            return part;
+        }
+        replacements += 1;
+        return '';
+    });
+    return { text: cleaned.join(''), replacements };
+}
+function isEmptyServiceDropIn(text) {
+    const meaningfulLines = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return meaningfulLines.length === 0 || (meaningfulLines.length === 1 && meaningfulLines[0] === '[Service]');
+}

package/docs/troubleshooting.md

@@ -203,12 +203,28 @@ ALL_PROXY=socks5://127.0.0.1:20170
 NO_PROXY=127.0.0.1,localhost
 ```
 
+When `HTTP_PROXY` or `HTTPS_PROXY` is configured, FoxClaw passes those variables to systemd/launchd explicitly and starts Node with `--use-env-proxy`. Do not rely on proxy variables from the current shell; service processes do not inherit them automatically.
+
 Restart FoxClaw after editing. The restart also restarts the managed Codex app-server so the new proxy environment takes effect:
 
 ```bash
 foxclaw restart
 ```
 
+If a Linux host must use `proxychains4` to reach Telegram or ChatGPT, do not hand-write a systemd drop-in that overrides `ExecStart`. Add this to the FoxClaw env file instead:
+
+```dotenv
+FOXCLAW_PROXYCHAINS_CONF=/home/wuya/.proxychains-rt.conf
+```
+
+Then run:
+
+```bash
+foxclaw restart
+```
+
+FoxClaw writes proxychains into the main service and removes stale FoxClaw `ExecStart` overrides, so later upgrades still only need the normal `pnpm install -g` and `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` 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.

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. 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:
+`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. When `HTTP_PROXY` or `HTTPS_PROXY` is configured, FoxClaw passes it to systemd/launchd explicitly and enables Node's env proxy support. Press Enter on any field to skip it, then edit manually if needed:
 
 ```bash
 $EDITOR ~/.foxclaw/.env

package/docs/zh/troubleshooting.md

@@ -204,12 +204,28 @@ ALL_PROXY=socks5://127.0.0.1:20170
 NO_PROXY=127.0.0.1,localhost
 ```
 
+只要配置了 `HTTP_PROXY` 或 `HTTPS_PROXY`，FoxClaw 安装 systemd/launchd 时会把这些变量显式传给服务，并给 Node 加上 `--use-env-proxy`。不要依赖“当前 shell 里有代理变量”，服务进程不会自动继承它们。
+
 改完后重启 FoxClaw。重启会同时重启托管的 Codex app-server，让新代理生效：
 
 ```bash
 foxclaw restart
 ```
 
+如果这台 Linux 机器必须用 `proxychains4` 才能访问 Telegram 或 ChatGPT，不要手写 systemd drop-in 覆盖 `ExecStart`。在 FoxClaw env 文件里写：
+
+```dotenv
+FOXCLAW_PROXYCHAINS_CONF=/home/wuya/.proxychains-rt.conf
+```
+
+然后运行：
+
+```bash
+foxclaw restart
+```
+
+FoxClaw 会把 proxychains 写进主 service，并清理旧的 FoxClaw `ExecStart` 覆盖，后续升级仍然只需要正常 `pnpm install -g` 和 `foxclaw restart`。
+
 ## 服务用了错误的 Node 版本
 
 systemd 安装脚本会记录当时正在运行的 Node 绝对路径，不依赖 systemd 去加载 `nvm.sh` 或其它 shell 初始化脚本。无论你用 nvm、fnm、asdf、mise、Volta、Homebrew 还是系统 Node，原则都是：从 Node 24+ 的 shell 里执行 `foxclaw start`，服务之后就固定使用这个 Node 24+ 路径。

package/docs/zh/user-manual.md

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

package/package.json

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

package/skills/foxclaw/SKILL.md

@@ -184,6 +184,7 @@ Use this checklist when the user asks for standard closing actions, release wrap
    - If the user has a pnpm global FoxClaw install, prefer `pnpm add -g <repo-path>` so the global `foxclaw` points at the local repo.
    - Rebuild before restarting because local linked installs run `dist/main.js`.
    - Refresh systemd with the existing service env path, for example `FOXCLAW_ENV=<existing-env> <node24> dist/main.js install-systemd`. Do not run `install-systemd` from the repo without `FOXCLAW_ENV`, because it may rewrite the service to use the repo `.env`.
+   - Do not create systemd drop-ins that override FoxClaw `ExecStart`. For Linux hosts that require proxychains, set `FOXCLAW_PROXYCHAINS_CONF=/absolute/path/to/proxychains.conf` in the FoxClaw env file and rerun `foxclaw restart`.
    - For macOS launchd, use the launchd install/start path from this skill and verify with `node dist/main.js status`.
    - Verify the running service reports the expected FoxClaw version in `status`.
    - If `doctor` fails only because `DEFAULT_CWD` is missing, report that separately; do not treat it as evidence that the service update failed.