@simonyea/holysheep-cli 1.7.12 → 1.7.13

package/README.md

@@ -70,11 +70,12 @@ 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.
 
 > **OpenClaw itself requires Node.js 20+**. If setup fails, first check `node --version`.
 
@@ -157,11 +158,12 @@ 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` 缓存路径上。
 
 > ⚠️ **OpenClaw 自身要求 Node.js 20+**。如果配置失败，请先运行 `node --version` 检查版本。
 
@@ -205,6 +207,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.13",
   "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.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
@@ -299,6 +301,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 +481,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,
@@ -466,7 +532,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,6 +565,11 @@ 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 bridgePort = findAvailableGatewayPort(DEFAULT_BRIDGE_PORT)
@@ -544,7 +615,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 +625,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,6 +644,9 @@ 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)
@@ -578,14 +654,16 @@ module.exports = {
     if (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 = 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 启动方式: ${serviceReady ? 'daemon' : 'direct process'}`))
+    console.log(chalk.gray('     浏览器应直接打开 dashboard URL，不应停在 about:blank'))
     console.log(chalk.gray('     如在 Windows 上打开裸 http://127.0.0.1:PORT/ 仍报 Unauthorized，请使用上面的 dashboard 地址'))
 
     return {
@@ -593,6 +671,8 @@ module.exports = {
       hot: false,
       dashboardUrl: dashUrl,
       gatewayPort,
+      gatewayReady: ok,
+      gatewayLaunchMode: serviceReady ? 'daemon' : 'direct-process',
       launchCmd: getLaunchCommand(gatewayPort),
     }
   },
@@ -607,6 +687,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 +701,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',