@simonyea/holysheep-cli 1.7.12 → 1.7.14

package/README.md

@@ -70,11 +70,13 @@ You'll be prompted for your API Key (`cr_xxx`), then select the tools to configu
 1. HolySheep configures OpenClaw to use HolySheep API
 2. The OpenClaw Gateway starts on **`http://127.0.0.1:18789/` by default**
 3. If `18789` is occupied, `hs setup` automatically picks the next available local port
-4. Open the exact browser URL shown in the terminal and start chatting — no token required
+4. Open the exact dashboard URL shown in the terminal and start chatting — do not use a blank browser shell or `about:blank`
 
 **Default OpenClaw model:** `gpt-5.4`
 
 > **Keep the gateway window open** while using OpenClaw. The gateway must be running for the browser UI to work.
+> If only `npx openclaw` is available, HolySheep will start Gateway as a direct process and will not install a persistent daemon from a temporary `npx` cache path.
+> HolySheep Bridge now watches the local OpenClaw Gateway and exits automatically if the Gateway stays unavailable, so it won't keep a blank browser shell alive after OpenClaw has stopped.
 
 > **OpenClaw itself requires Node.js 20+**. If setup fails, first check `node --version`.
 
@@ -157,11 +159,13 @@ hs setup
 1. HolySheep 会自动把 OpenClaw 接到 HolySheep API
 2. 默认启动在 **`http://127.0.0.1:18789/`**
 3. 如果 `18789` 被占用，`hs setup` 会自动切换到下一个可用本地端口
-4. 按终端里显示的准确地址打开浏览器，直接开始聊天，无需填写 token
+4. 按终端里显示的准确 dashboard 地址打开浏览器，直接开始聊天，不要打开空白浏览器壳窗口或 `about:blank`
 
 **OpenClaw 默认模型：** `gpt-5.4`
 
 > ⚠️ **保持 Gateway 窗口开启**，关闭后 Gateway 停止，浏览器界面无法使用。
+> 如果机器上只有 `npx openclaw`，HolySheep 会直接启动 Gateway 进程，不会把 daemon 安装到临时 `npx` 缓存路径上。
+> HolySheep Bridge 会持续检查本地 OpenClaw Gateway；如果 Gateway 持续不可用，Bridge 会自动退出，避免空白浏览器壳窗口一直残留。
 
 > ⚠️ **OpenClaw 自身要求 Node.js 20+**。如果配置失败，请先运行 `node --version` 检查版本。
 
@@ -205,6 +209,9 @@ A: 支持，需要 Node.js 16+。如果 `hs` 命令找不到，请重启终端
 **Q: OpenClaw Gateway 窗口可以最小化吗？**  
 A: 可以最小化，但不能关闭。关闭后 Gateway 停止，需要按 `hs setup` / `hs doctor` 显示的端口重新运行 `openclaw gateway --port <端口>` 或 `npx openclaw gateway --port <端口>`。
 
+**Q: 为什么浏览器会只剩黑屏 / 空白窗口？**  
+A: 最常见原因是 Gateway 实际没有启动成功，或者你打开了空白浏览器壳窗口而不是终端输出的 dashboard URL。先运行 `hs doctor` 检查 `gateway.port` 是否正在监听，再打开终端里输出的准确 dashboard 地址。
+
 **Q: 18789 端口被占用怎么办？**  
 A: `hs setup` 会自动切换到下一个可用本地端口，并把准确访问地址打印出来；也可以运行 `hs doctor` 查看当前 `gateway.port` 和端口占用情况。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simonyea/holysheep-cli",
-  "version": "1.7.12",
+  "version": "1.7.14",
   "description": "Claude Code/Cursor/Cline API relay for China — ¥1=$1, WeChat/Alipay payment, no credit card, no VPN. One command setup for all AI coding tools.",
   "keywords": [
     "openai-china",

package/src/commands/doctor.js

@@ -99,9 +99,14 @@ function printCheck(ok, label, detail = '') {
 function printOpenClawDetails(tool, installState, nodeMajor) {
   const details = []
   const gatewayPort = typeof tool.getGatewayPort === 'function' ? tool.getGatewayPort() : 18789
+  const bridgePort = typeof tool.getBridgePort === 'function' ? tool.getBridgePort() : null
   const primaryModel = typeof tool.getPrimaryModel === 'function' ? tool.getPrimaryModel() : ''
   const listeners = typeof tool.getPortListeners === 'function' ? tool.getPortListeners(gatewayPort) : []
   const foreignListeners = listeners.filter((item) => !String(item.command || '').toLowerCase().includes('openclaw'))
+  const launchAgent = typeof tool.getLaunchAgentDiagnosis === 'function' ? tool.getLaunchAgentDiagnosis() : null
+  const launchHint = Array.isArray(tool.launchSteps) && tool.launchSteps.length > 1
+    ? tool.launchSteps[1].cmd
+    : tool.launchCmd || 'npx openclaw gateway --port <port>'
 
   if (installState.detail === 'npx fallback') {
     details.push({
@@ -123,6 +128,25 @@ function printOpenClawDetails(tool, installState, nodeMajor) {
     })
   }
 
+  if (bridgePort) {
+    details.push({
+      level: 'info',
+      text: `Bridge 端口：${bridgePort}`,
+    })
+  }
+
+  if (launchAgent?.unstable) {
+    details.push({
+      level: 'warn',
+      text: `检测到失效的 LaunchAgent，引用了临时 npx 缓存路径：${launchAgent.unstableArg}`,
+    })
+  } else if (launchAgent?.exists) {
+    details.push({
+      level: 'ok',
+      text: `LaunchAgent 配置存在：${launchAgent.path}`,
+    })
+  }
+
   if (foreignListeners.length) {
     const occupiedBy = foreignListeners
       .slice(0, 2)
@@ -139,8 +163,10 @@ function printOpenClawDetails(tool, installState, nodeMajor) {
     })
   } else {
     details.push({
-      level: 'info',
-      text: `Gateway 端口 ${gatewayPort} 当前空闲；如刚完成配置，可运行 ${tool.launchCmd}`,
+      level: launchAgent?.unstable ? 'warn' : 'info',
+      text: launchAgent?.unstable
+        ? `Gateway 端口 ${gatewayPort} 当前未监听；这通常会导致浏览器只剩空白/黑屏窗口`
+        : `Gateway 端口 ${gatewayPort} 当前空闲；如刚完成配置，可运行 ${launchHint}`,
     })
   }
 

package/src/commands/setup.js

@@ -378,6 +378,9 @@ async function setup(options) {
       const hot = r.result?.hot ? chalk.cyan(' (热切换，无需重启)') : chalk.gray(' (重启终端生效)')
       console.log(`  ✓ ${r.tool.name}${hot}`)
       if (r.tool.hint) console.log(`    ${chalk.gray('💡 ' + r.tool.hint)}`)
+      if (r.result?.dashboardUrl) {
+        console.log(`    ${chalk.gray('🌐 Dashboard:')} ${chalk.cyan.bold(r.result.dashboardUrl)}`)
+      }
       // 显示启动命令
       if (r.tool.launchSteps) {
         // 多步骤启动（如 openclaw）

package/src/tools/openclaw-bridge.js

@@ -9,6 +9,10 @@ const fetch = global.fetch || require('node-fetch')
 
 const OPENCLAW_DIR = path.join(os.homedir(), '.openclaw')
 const BRIDGE_CONFIG_FILE = path.join(OPENCLAW_DIR, 'holysheep-bridge.json')
+const DEFAULT_WATCHDOG_INTERVAL_MS = 3000
+const DEFAULT_WATCHDOG_FAILURE_THRESHOLD = 3
+const DEFAULT_WATCHDOG_STARTUP_GRACE_MS = 30000
+const DEFAULT_WATCHDOG_REQUEST_TIMEOUT_MS = 1500
 
 function readBridgeConfig(configPath = BRIDGE_CONFIG_FILE) {
   return JSON.parse(fs.readFileSync(configPath, 'utf8'))
@@ -581,6 +585,93 @@ function buildModelsResponse(config) {
   }
 }
 
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    if (error && error.code === 'EPERM') return true
+    return false
+  }
+}
+
+async function checkGatewayHealth(config) {
+  const gatewayPort = Number(config.gatewayPort)
+  if (!Number.isInteger(gatewayPort) || gatewayPort <= 0) {
+    return { ok: true, reason: 'no_gateway_port' }
+  }
+
+  const gatewayPid = Number(config.gatewayPid)
+  const pidAlive = isProcessAlive(gatewayPid)
+  if (pidAlive === false) {
+    return { ok: false, reason: 'gateway_pid_exited' }
+  }
+
+  const host = config.gatewayHost || '127.0.0.1'
+  const timeout = Number(config.watchdog?.requestTimeoutMs) || DEFAULT_WATCHDOG_REQUEST_TIMEOUT_MS
+
+  try {
+    const response = await fetch(`http://${host}:${gatewayPort}/`, { method: 'GET', timeout })
+    return response.ok
+      ? { ok: true, reason: 'gateway_http_ok' }
+      : { ok: false, reason: `gateway_http_${response.status}` }
+  } catch {
+    return { ok: false, reason: 'gateway_http_unreachable' }
+  }
+}
+
+function stopBridge(server, reason) {
+  process.stdout.write(`HolySheep OpenClaw bridge stopping: ${reason}\n`)
+  server.close(() => process.exit(0))
+  setTimeout(() => process.exit(0), 250).unref()
+}
+
+function startGatewayWatchdog(server, configPath = BRIDGE_CONFIG_FILE) {
+  const bridgeStartedAt = Date.now()
+  let consecutiveFailures = 0
+  let stopping = false
+
+  const timer = setInterval(async () => {
+    if (stopping) return
+
+    let config
+    try {
+      config = readBridgeConfig(configPath)
+    } catch {
+      stopping = true
+      stopBridge(server, 'bridge config missing')
+      return
+    }
+
+    const watchdog = config.watchdog || {}
+    if (watchdog.enabled === false) return
+
+    const startupGraceMs = Number(watchdog.startupGraceMs) || DEFAULT_WATCHDOG_STARTUP_GRACE_MS
+    const failureThreshold = Number(watchdog.failureThreshold) || DEFAULT_WATCHDOG_FAILURE_THRESHOLD
+    const health = await checkGatewayHealth(config)
+
+    if (health.ok) {
+      consecutiveFailures = 0
+      return
+    }
+
+    const gatewayStartedAt = Date.parse(config.gatewayStartedAt || '') || bridgeStartedAt
+    if (Date.now() - gatewayStartedAt < startupGraceMs) {
+      return
+    }
+
+    consecutiveFailures += 1
+    if (consecutiveFailures < failureThreshold) return
+
+    stopping = true
+    stopBridge(server, `OpenClaw Gateway unavailable (${health.reason})`)
+  }, DEFAULT_WATCHDOG_INTERVAL_MS)
+
+  timer.unref()
+  server.on('close', () => clearInterval(timer))
+}
+
 function createBridgeServer(configPath = BRIDGE_CONFIG_FILE) {
   return http.createServer(async (req, res) => {
     if (req.method === 'OPTIONS') {
@@ -627,6 +718,7 @@ function startBridge(args = parseArgs(process.argv.slice(2))) {
   server.listen(port, host, () => {
     process.stdout.write(`HolySheep OpenClaw bridge listening on http://${host}:${port}\n`)
   })
+  startGatewayWatchdog(server, args.config)
 
   return server
 }

package/src/tools/openclaw.js

@@ -13,6 +13,8 @@ const { BRIDGE_CONFIG_FILE } = require('./openclaw-bridge')
 
 const OPENCLAW_DIR = path.join(os.homedir(), '.openclaw')
 const CONFIG_FILE = path.join(OPENCLAW_DIR, 'openclaw.json')
+const OPENCLAW_LAUNCH_AGENTS_DIR = path.join(os.homedir(), 'Library', 'LaunchAgents')
+const OPENCLAW_GATEWAY_PLIST = path.join(OPENCLAW_LAUNCH_AGENTS_DIR, 'ai.openclaw.gateway.plist')
 const isWin = process.platform === 'win32'
 const DEFAULT_BRIDGE_PORT = 18788
 const DEFAULT_GATEWAY_PORT = 18789
@@ -161,6 +163,14 @@ function writeBridgeConfig(data) {
   fs.writeFileSync(BRIDGE_CONFIG_FILE, JSON.stringify(data, null, 2), 'utf8')
 }
 
+function updateBridgeConfig(patch) {
+  const current = readBridgeConfig()
+  writeBridgeConfig({
+    ...current,
+    ...patch,
+  })
+}
+
 function getConfiguredBridgePort(config = readBridgeConfig()) {
   const port = Number(config?.port)
   return Number.isInteger(port) && port > 0 ? port : DEFAULT_BRIDGE_PORT
@@ -299,6 +309,68 @@ function getDashboardCommand() {
   return `${runtime} dashboard --no-open`
 }
 
+function getDashboardUrlForPort(port) {
+  return `http://127.0.0.1:${port}/`
+}
+
+function isNpxCachePath(value) {
+  return /[\\/]_npx[\\/]/i.test(String(value || ''))
+}
+
+function readOpenClawLaunchAgent() {
+  if (process.platform !== 'darwin') return null
+  try {
+    if (!fs.existsSync(OPENCLAW_GATEWAY_PLIST)) return null
+    return fs.readFileSync(OPENCLAW_GATEWAY_PLIST, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+function parseLaunchAgentProgramArguments(content) {
+  const match = String(content || '').match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/i)
+  if (!match) return []
+
+  return Array.from(match[1].matchAll(/<string>([\s\S]*?)<\/string>/g)).map((item) => item[1])
+}
+
+function getLaunchAgentDiagnosis() {
+  const content = readOpenClawLaunchAgent()
+  if (!content) {
+    return { exists: false, path: OPENCLAW_GATEWAY_PLIST, unstable: false, programArguments: [] }
+  }
+
+  const programArguments = parseLaunchAgentProgramArguments(content)
+  const unstableArg = programArguments.find(isNpxCachePath) || ''
+
+  return {
+    exists: true,
+    path: OPENCLAW_GATEWAY_PLIST,
+    unstable: Boolean(unstableArg),
+    unstableArg,
+    programArguments,
+  }
+}
+
+function removeBrokenLaunchAgent() {
+  const diagnosis = getLaunchAgentDiagnosis()
+  if (!diagnosis.exists || !diagnosis.unstable) return false
+
+  try {
+    execSync(`launchctl bootout "gui/${process.getuid()}" "${diagnosis.path}"`, {
+      shell: true,
+      stdio: 'ignore',
+    })
+  } catch {}
+
+  try {
+    fs.unlinkSync(diagnosis.path)
+    return true
+  } catch {
+    return false
+  }
+}
+
 function buildModelEntry(id) {
   return {
     id,
@@ -417,6 +489,8 @@ function _disableGatewayAuth(preferNpx = false) {
 }
 
 function _installGatewayService(port, preferNpx = false) {
+  if (preferNpx) return false
+
   const result = runOpenClaw(['gateway', 'install', '--force', '--port', String(port)], {
     preferNpx,
     timeout: 60000,
@@ -429,13 +503,15 @@ function _startGateway(port, preferNpx = false, preferService = true) {
     ? runOpenClaw(['gateway', 'start'], { preferNpx, timeout: 20000 })
     : { status: 1 }
 
+  let directChild = null
+
   if (serviceResult.status !== 0) {
-    const child = spawnOpenClaw(['gateway', '--port', String(port)], {
+    directChild = spawnOpenClaw(['gateway', '--port', String(port)], {
       preferNpx,
       detached: true,
       stdio: 'ignore',
     })
-    child.unref()
+    directChild.unref()
   }
 
   for (let i = 0; i < 8; i++) {
@@ -449,11 +525,19 @@ function _startGateway(port, preferNpx = false, preferService = true) {
           : `curl -sf http://127.0.0.1:${port}/ -o /dev/null --max-time 1`,
         { stdio: 'ignore', timeout: 3000 }
       )
-      return true
+      return {
+        ok: true,
+        pid: directChild?.pid || null,
+        mode: directChild ? 'direct-process' : 'daemon',
+      }
     } catch {}
   }
 
-  return false
+  return {
+    ok: false,
+    pid: directChild?.pid || null,
+    mode: directChild ? 'direct-process' : 'daemon',
+  }
 }
 
 function getDashboardUrl(port, preferNpx = false) {
@@ -466,7 +550,7 @@ function getDashboardUrl(port, preferNpx = false) {
     const match = output.match(/Dashboard URL:\s*(\S+)/) || output.match(/(https?:\/\/\S+)/)
     if (match) return match[1]
   }
-  return `http://127.0.0.1:${port}/`
+  return getDashboardUrlForPort(port)
 }
 
 module.exports = {
@@ -499,8 +583,19 @@ module.exports = {
       throw new Error('未检测到 OpenClaw；请先全局安装，或确保 npx 可用')
     }
     this._lastRuntimeCommand = runtime.command
+    this._lastRuntimeVia = runtime.via
+
+    if (runtime.via === 'npx' && removeBrokenLaunchAgent()) {
+      console.log(chalk.gray('  → 已清理旧的 OpenClaw 守护进程配置（失效的 npx 缓存路径）'))
+    }
 
     const resolvedPrimaryModel = pickPrimaryModel(primaryModel, selectedModels)
+    const gatewayPort = findAvailableGatewayPort(DEFAULT_GATEWAY_PORT)
+    if (!gatewayPort) {
+      throw new Error(`找不到可用端口（已检查 ${DEFAULT_GATEWAY_PORT}-${DEFAULT_GATEWAY_PORT + MAX_PORT_SCAN - 1}）`)
+    }
+    this._lastGatewayPort = gatewayPort
+
     const bridgePort = findAvailableGatewayPort(DEFAULT_BRIDGE_PORT)
     if (!bridgePort) {
       throw new Error(`找不到可用桥接端口（已检查 ${DEFAULT_BRIDGE_PORT}-${DEFAULT_BRIDGE_PORT + MAX_PORT_SCAN - 1}）`)
@@ -509,10 +604,22 @@ module.exports = {
 
     writeBridgeConfig({
       port: bridgePort,
+      host: '127.0.0.1',
       apiKey,
       baseUrlAnthropic,
       baseUrlOpenAI,
       models: normalizeRequestedModels(selectedModels),
+      gatewayPort,
+      gatewayHost: '127.0.0.1',
+      gatewayPid: null,
+      gatewayLaunchMode: null,
+      watchdog: {
+        enabled: true,
+        intervalMs: 3000,
+        failureThreshold: 3,
+        startupGraceMs: 30000,
+        requestTimeoutMs: 1500,
+      },
     })
 
     console.log(chalk.gray('  → 正在启动 HolySheep Bridge...'))
@@ -523,12 +630,6 @@ module.exports = {
 
     runOpenClaw(['gateway', 'stop'], { preferNpx: runtime.via === 'npx' })
 
-    const gatewayPort = findAvailableGatewayPort(DEFAULT_GATEWAY_PORT)
-    if (!gatewayPort) {
-      throw new Error(`找不到可用端口（已检查 ${DEFAULT_GATEWAY_PORT}-${DEFAULT_GATEWAY_PORT + MAX_PORT_SCAN - 1}）`)
-    }
-    this._lastGatewayPort = gatewayPort
-
     if (gatewayPort !== DEFAULT_GATEWAY_PORT) {
       console.log(chalk.yellow(`  ⚠️  端口 ${DEFAULT_GATEWAY_PORT} 已占用，自动切换到 ${gatewayPort}`))
       const listeners = listPortListeners(DEFAULT_GATEWAY_PORT)
@@ -544,7 +645,7 @@ module.exports = {
     try { fs.unlinkSync(CONFIG_FILE) } catch {}
 
     console.log(chalk.gray('  → 写入配置...'))
-    const result = runOpenClaw([
+    const onboardArgs = [
       'onboard',
       '--non-interactive',
       '--accept-risk',
@@ -554,8 +655,10 @@ module.exports = {
       '--custom-model-id', resolvedPrimaryModel,
       '--custom-compatibility', 'openai',
       '--gateway-port', String(gatewayPort),
-      '--install-daemon',
-    ], { preferNpx: runtime.via === 'npx' })
+    ]
+    if (runtime.via !== 'npx') onboardArgs.push('--install-daemon')
+
+    const result = runOpenClaw(onboardArgs, { preferNpx: runtime.via === 'npx' })
 
     if (result.status !== 0) {
       console.log(chalk.yellow('  ⚠️  onboard 失败，使用备用配置...'))
@@ -571,21 +674,33 @@ module.exports = {
 
     _disableGatewayAuth(runtime.via === 'npx')
     const serviceReady = _installGatewayService(gatewayPort, runtime.via === 'npx')
+    if (runtime.via === 'npx') {
+      console.log(chalk.gray('  → 当前仅检测到 npx openclaw，跳过 daemon 安装，改为直接启动 Gateway 进程'))
+    }
 
     console.log(chalk.gray('  → 正在启动 Gateway...'))
-    const ok = _startGateway(gatewayPort, runtime.via === 'npx', serviceReady)
+    const gatewayState = _startGateway(gatewayPort, runtime.via === 'npx', serviceReady)
+    updateBridgeConfig({
+      gatewayPort,
+      gatewayPid: gatewayState.pid,
+      gatewayLaunchMode: gatewayState.mode,
+      gatewayStartedAt: new Date().toISOString(),
+    })
 
-    if (ok) {
+    if (gatewayState.ok) {
       console.log(chalk.green('  ✓ OpenClaw Gateway 已启动'))
     } else {
-      console.log(chalk.yellow('  ⚠️  Gateway 启动中，稍等几秒后刷新浏览器'))
+      console.log(chalk.yellow('  ⚠️  Gateway 未就绪；当前不要打开 about:blank 或裸浏览器壳窗口'))
     }
 
-    const dashUrl = getDashboardUrl(gatewayPort, runtime.via === 'npx')
+    const dashUrl = gatewayState.ok ? getDashboardUrl(gatewayPort, runtime.via === 'npx') : getDashboardUrlForPort(gatewayPort)
     console.log(chalk.cyan('\n  → 浏览器打开（推荐使用此地址）:'))
     console.log(chalk.bold.cyan(`     ${dashUrl}`))
     console.log(chalk.gray(`     Bridge 地址: ${bridgeBaseUrl}`))
     console.log(chalk.gray(`     默认模型: ${plan.primaryRef || OPENCLAW_DEFAULT_MODEL}`))
+    console.log(chalk.gray(`     Gateway 启动方式: ${gatewayState.mode}`))
+    console.log(chalk.gray('     浏览器应直接打开 dashboard URL，不应停在 about:blank'))
+    console.log(chalk.gray('     Bridge 会在检测到 OpenClaw Gateway 持续不可用后自动退出'))
     console.log(chalk.gray('     如在 Windows 上打开裸 http://127.0.0.1:PORT/ 仍报 Unauthorized，请使用上面的 dashboard 地址'))
 
     return {
@@ -593,6 +708,8 @@ module.exports = {
       hot: false,
       dashboardUrl: dashUrl,
       gatewayPort,
+      gatewayReady: gatewayState.ok,
+      gatewayLaunchMode: gatewayState.mode,
       launchCmd: getLaunchCommand(gatewayPort),
     }
   },
@@ -607,6 +724,7 @@ module.exports = {
   getGatewayPort() { return getConfiguredGatewayPort() },
   getPrimaryModel() { return getConfiguredPrimaryModel() },
   getPortListeners(port = getConfiguredGatewayPort()) { return listPortListeners(port) },
+  getLaunchAgentDiagnosis,
   get hint() {
     return `Bridge + Gateway 已配置，默认模型为 ${getConfiguredPrimaryModel() || OPENCLAW_DEFAULT_MODEL}`
   },
@@ -620,7 +738,8 @@ module.exports = {
     ]
   },
   get launchNote() {
-    return `🌐 请先启动 Bridge，再启动 Gateway；最后运行 ${getDashboardCommand()}`
+    const runtime = module.exports._lastRuntimeVia === 'npx' ? '当前为 npx 模式，不安装常驻 daemon。' : ''
+    return `🌐 请先启动 Bridge，再启动 Gateway；最后运行 ${getDashboardCommand()} ${runtime}`.trim()
   },
   installCmd: 'npm install -g openclaw@latest',
   docsUrl: 'https://docs.openclaw.ai',