@autotask/atools-tool 0.1.8 → 0.1.9

package/README.md

@@ -31,6 +31,8 @@ Selection UX:
 - TTY terminal: use `↑/↓` and `Enter`
 - Non-TTY: falls back to number input
 
+If proxy startup fails during `atools-tool openclaw`, the CLI now prints environment-aware troubleshooting hints (systemd user bus, permissions, port readiness) and does not silently fail.
+
 Rollback to codex-compatible defaults:
 
 ```bash
@@ -64,7 +66,7 @@ atools-tool-install --help
 
 `atools-tool-install` service behavior by platform:
 
-- Linux: systemd user service
+- Linux: systemd user service (fallback to detached process if `systemctl --user` is unavailable)
 - macOS: launchd user agent (`~/Library/LaunchAgents`)
 - Windows: Task Scheduler user task (ONLOGON + start now)
 
@@ -98,6 +100,7 @@ curl -fsSL https://raw.githubusercontent.com/aak1247/sub2api-openclaw-proxy/main
 - patches `~/.openclaw/agents/main/agent/auth-profiles.json` (if API key is available)
 - service install by platform:
   - Linux: creates/enables `~/.config/systemd/user/openclaw-atools-proxy.service`
+    - if user bus/systemd is unavailable (for example container/root without login bus), installer auto-falls back to detached proxy process
   - macOS: creates/enables `~/Library/LaunchAgents/openclaw-atools-proxy.plist`
   - Windows: creates/updates scheduled task `openclaw-atools-proxy`
 - restarts `openclaw-gateway.service` only on Linux (unless `--no-restart`)

package/lib/config-openclaw.mjs

@@ -296,9 +296,22 @@ function isLinuxProxyServiceActive() {
 
 function startLinuxProxyService() {
   const reload = runSystemctl(['daemon-reload']);
-  if (reload.status !== 0) return false;
+  if (reload.status !== 0) {
+    return {
+      ok: false,
+      step: 'daemon-reload',
+      detail: String(reload.stderr || reload.stdout || '').trim()
+    };
+  }
   const start = runSystemctl(['enable', '--now', PROXY_SERVICE]);
-  return start.status === 0;
+  if (start.status !== 0) {
+    return {
+      ok: false,
+      step: 'enable-start',
+      detail: String(start.stderr || start.stdout || '').trim()
+    };
+  }
+  return { ok: true, step: 'enable-start', detail: '' };
 }
 
 function startDetachedProxy() {
@@ -350,6 +363,31 @@ async function isPortOpen(host, port, timeoutMs = 900) {
   });
 }
 
+function buildProxyTroubleshootingHints({ linuxSystemdError } = {}) {
+  const hints = [];
+  const err = String(linuxSystemdError || '');
+
+  if (/Failed to connect to bus|No medium found/i.test(err)) {
+    hints.push('当前环境没有可用的 systemd 用户会话（常见于容器、root、无登录会话）。');
+    hints.push('建议：直接重新执行 `atools-tool-install`，新版会自动降级到非-systemd进程模式。');
+    hints.push('如果是容器环境，请确保进程管理策略允许后台常驻进程。');
+    return hints;
+  }
+
+  if (/permission denied|access denied/i.test(err)) {
+    hints.push('权限不足，无法通过 systemd --user 启动服务。');
+    hints.push('建议：使用普通登录用户执行安装与配置，不要混用 root 与普通用户的 OpenClaw 目录。');
+    return hints;
+  }
+
+  if (err) {
+    hints.push(`systemd 启动失败：${err}`);
+  }
+  hints.push('建议：检查 OpenClaw Home 路径与 Node 可执行路径是否存在且可访问。');
+  hints.push(`建议：确认端口 ${PROXY_PORT} 未被防火墙或策略阻断。`);
+  return hints;
+}
+
 async function ensureProxyReady() {
   if (process.platform === 'linux') {
     const service = configureLinuxProxyService();
@@ -360,13 +398,13 @@ async function ensureProxyReady() {
     }
   }
 
-  if (await isPortOpen(PROXY_HOST, PROXY_PORT)) return true;
+  if (await isPortOpen(PROXY_HOST, PROXY_PORT)) return { ok: true, mode: 'already-running' };
 
   // Linux retry: service may exist but not running.
   if (process.platform === 'linux') {
     const service = configureLinuxProxyService();
     if (service.exists && isLinuxProxyServiceActive()) {
-      if (await isPortOpen(PROXY_HOST, PROXY_PORT)) return true;
+      if (await isPortOpen(PROXY_HOST, PROXY_PORT)) return { ok: true, mode: 'already-running' };
     }
   }
 
@@ -388,26 +426,45 @@ async function ensureProxyReady() {
   }
 
   if (action === '取消并退出') {
-    return false;
+    return { ok: false, reason: 'user-cancelled', hints: [] };
   }
 
   let started = false;
+  let linuxSystemdError = '';
   if (process.platform === 'linux') {
-    started = startLinuxProxyService();
+    const systemdStart = startLinuxProxyService();
+    started = systemdStart.ok;
+    linuxSystemdError = systemdStart.detail || '';
   }
+  let mode = 'systemd';
   if (!started) {
     started = startDetachedProxy();
+    mode = 'detached';
   }
 
-  if (!started) return false;
+  if (!started) {
+    return {
+      ok: false,
+      reason: 'start-failed',
+      hints: buildProxyTroubleshootingHints({ linuxSystemdError })
+    };
+  }
 
   for (let i = 0; i < 5; i += 1) {
     await sleep(500);
     if (await isPortOpen(PROXY_HOST, PROXY_PORT)) {
-      return true;
+      return { ok: true, mode };
     }
   }
-  return false;
+  return {
+    ok: false,
+    reason: 'port-not-open',
+    hints: [
+      '代理进程启动后端口仍未就绪。',
+      `请检查日志：${PROXY_LOG_FILE}`,
+      '如为受限环境（容器/最小系统），请确认允许本地监听 127.0.0.1。'
+    ]
+  };
 }
 
 function printRestartHint() {
@@ -442,11 +499,18 @@ export async function runConfigOpenclaw({ openclawHome } = {}) {
     process.stdout.write(`固定代理目标: ${PROXY_UPSTREAM}\n`);
     process.stdout.write(`固定 Provider Base URL: ${PROXY_BASE_URL}\n`);
 
-    const proxyReady = await ensureProxyReady();
-    if (!proxyReady) {
-      process.stdout.write('\n已取消：本地代理未就绪，未修改 OpenClaw 模型配置。\n');
+    const proxyStatus = await ensureProxyReady();
+    if (!proxyStatus.ok) {
+      process.stdout.write('\n本地代理未就绪，未修改 OpenClaw 模型配置。\n');
+      if (Array.isArray(proxyStatus.hints) && proxyStatus.hints.length > 0) {
+        process.stdout.write('可行解决方案:\n');
+        proxyStatus.hints.forEach((hint) => process.stdout.write(`- ${hint}\n`));
+      }
       return;
     }
+    if (proxyStatus.mode === 'detached') {
+      process.stdout.write('\n已通过非-systemd模式启动代理（兼容无 user bus 环境）。\n');
+    }
     rl = readlinePromises.createInterface({
       input: process.stdin,
       output: process.stdout

package/lib/install.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 const DEFAULT_PROVIDER = 'sub2api';
@@ -350,7 +350,56 @@ function runSystemctl(args, { dryRun } = {}) {
   execFileSync('systemctl', ['--user', ...args], { stdio: 'inherit' });
 }
 
-function installLinuxService({ serviceName, content, dryRun }) {
+function printSystemdFallbackHints(detail) {
+  const text = String(detail || '');
+  if (/Failed to connect to bus|No medium found/i.test(text)) {
+    info('detected: no systemd user bus in current environment');
+    info('hint: this is common in containers/root/non-login sessions');
+    info('hint: installer will continue with detached process mode');
+    return;
+  }
+  if (/permission denied|access denied/i.test(text)) {
+    info('detected: permission issue for systemd --user');
+    info('hint: run install under the same normal user as OpenClaw');
+    info('hint: installer will continue with detached process mode');
+    return;
+  }
+  info('detected: systemd --user is not usable in current environment');
+  info('hint: installer will continue with detached process mode');
+}
+
+function startDetachedProxyProcess({ nodeBin, cliPath, serveArgs, dryRun }) {
+  if (dryRun) {
+    info(`dry-run: detached start ${[nodeBin, cliPath, ...serveArgs].join(' ')}`);
+    return true;
+  }
+  try {
+    const child = spawn(nodeBin, [cliPath, ...serveArgs], {
+      detached: true,
+      stdio: 'ignore',
+      cwd: os.homedir(),
+      env: {
+        ...process.env,
+        HOME: process.env.HOME || os.homedir(),
+        TMPDIR: process.env.TMPDIR || '/tmp',
+        SUB2API_COMPAT_USER_AGENT: 'codex_cli_rs/0.101.0 (Ubuntu 24.4.0; x86_64) WindowsTerminal'
+      }
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function installLinuxService({
+  serviceName,
+  content,
+  nodeBin,
+  cliPath,
+  serveArgs,
+  dryRun
+}) {
   const serviceDir = path.join(os.homedir(), '.config/systemd/user');
   const servicePath = path.join(serviceDir, serviceName);
   ensureDir(serviceDir);
@@ -366,8 +415,22 @@ function installLinuxService({ serviceName, content, dryRun }) {
     info(`wrote: ${servicePath}`);
   }
 
-  runSystemctl(['daemon-reload'], { dryRun });
-  runSystemctl(['enable', '--now', serviceName], { dryRun });
+  try {
+    runSystemctl(['daemon-reload'], { dryRun });
+    runSystemctl(['enable', '--now', serviceName], { dryRun });
+    info(`service started with systemd --user: ${serviceName}`);
+    return;
+  } catch (err) {
+    const detail = String(err?.message || err);
+    info(`systemd --user unavailable, fallback to detached process (${detail})`);
+    printSystemdFallbackHints(detail);
+  }
+
+  const started = startDetachedProxyProcess({ nodeBin, cliPath, serveArgs, dryRun });
+  if (!started) {
+    throw new Error(`failed to start proxy with both systemd --user and detached mode`);
+  }
+  info('proxy started in detached mode (non-systemd fallback)');
 }
 
 function runLaunchctl(args, { dryRun, allowFailure = false } = {}) {
@@ -444,7 +507,14 @@ function installService({
   dryRun
 }) {
   if (process.platform === 'linux') {
-    installLinuxService({ serviceName, content: linuxServiceContent, dryRun });
+    installLinuxService({
+      serviceName,
+      content: linuxServiceContent,
+      nodeBin,
+      cliPath,
+      serveArgs,
+      dryRun
+    });
     return;
   }
   if (process.platform === 'darwin') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autotask/atools-tool",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "ATools CLI for OpenClaw proxy compatibility and interactive model configuration",
   "type": "module",
   "license": "MIT",