@simonyea/holysheep-cli 1.6.0 → 1.6.3

package/README.md

@@ -38,7 +38,7 @@ Instead of manually editing config files for each tool, run one command and you'
 |------|-------------|--------|
 | [Claude Code](https://docs.anthropic.com/claude-code) | `~/.claude/settings.json` | ✅ Auto |
 | [Codex CLI](https://github.com/openai/codex) | `~/.codex/config.toml` | ✅ Auto |
-| Droid CLI | `~/.factory/config.json` | ✅ Auto |
+| Droid CLI | `~/.factory/settings.json` | ✅ Auto |
 | [Aider](https://aider.chat) | `~/.aider.conf.yml` | ✅ Auto |
 | [Continue.dev](https://continue.dev) | `~/.continue/config.yaml` | ✅ Auto |
 | [OpenCode](https://github.com/anomalyco/opencode) | `~/.config/opencode/opencode.json` | ✅ Auto |
@@ -67,17 +67,26 @@ You'll be prompted for your API Key (`cr_xxx`), then select the tools to configu
 
 [OpenClaw](https://openclaw.ai) is a powerful AI agent gateway with a web dashboard. After running `hs setup`:
 
-1. A new terminal window opens running the OpenClaw Gateway
-2. Open your browser: **http://127.0.0.1:18789/**
-3. Start chatting — no token required
+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
+
+**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.
 
+> **OpenClaw itself requires Node.js 20+**. If setup fails, first check `node --version`.
+
 To restart the gateway later:
 ```bash
-npx openclaw gateway --port 18789
+openclaw gateway --port <shown-port>
+# or
+npx openclaw gateway --port <shown-port>
 ```
 
+If you forget the port, check `~/.openclaw/openclaw.json` (`gateway.port`) or run `hs doctor`.
+
 ### Commands
 
 | Command | Description |
@@ -145,18 +154,27 @@ hs setup
 
 **`hs setup` 配置完成后：**
 
-1. 自动弹出一个新终端窗口，运行 OpenClaw Gateway
-2. 打开浏览器访问：**http://127.0.0.1:18789/**
-3. 直接开始聊天，无需填写 token
+1. HolySheep 会自动把 OpenClaw 接到 HolySheep API
+2. 默认启动在 **`http://127.0.0.1:18789/`**
+3. 如果 `18789` 被占用，`hs setup` 会自动切换到下一个可用本地端口
+4. 按终端里显示的准确地址打开浏览器，直接开始聊天，无需填写 token
+
+**OpenClaw 默认模型：** `gpt-5.4`
 
 > ⚠️ **保持 Gateway 窗口开启**，关闭后 Gateway 停止，浏览器界面无法使用。
 
+> ⚠️ **OpenClaw 自身要求 Node.js 20+**。如果配置失败，请先运行 `node --version` 检查版本。
+
 **下次启动 Gateway：**
 ```bash
-npx openclaw gateway --port 18789
+openclaw gateway --port <显示的端口>
+# 或
+npx openclaw gateway --port <显示的端口>
 ```
 
-**使用的模型：** `claude-sonnet-4-6`（通过 HolySheep 中转）
+如果忘了端口，可以查看 `~/.openclaw/openclaw.json` 里的 `gateway.port`，或直接运行 `hs doctor`。
+
+**默认模型：** `gpt-5.4`（可在 OpenClaw 内切换到 Claude 模型）
 
 ### 命令说明
 
@@ -185,18 +203,23 @@ A: 在 [holysheep.ai](https://holysheep.ai) 注册后，在「API 密钥」页
 A: 支持，需要 Node.js 16+。如果 `hs` 命令找不到，请重启终端，或直接用 `npx @simonyea/holysheep-cli@latest setup`。
 
 **Q: OpenClaw Gateway 窗口可以最小化吗？**  
-A: 可以最小化，但不能关闭。关闭后 Gateway 停止，需重新运行 `npx openclaw gateway --port 18789`。
+A: 可以最小化，但不能关闭。关闭后 Gateway 停止，需要按 `hs setup` / `hs doctor` 显示的端口重新运行 `openclaw gateway --port <端口>` 或 `npx openclaw gateway --port <端口>`。
+
+**Q: 18789 端口被占用怎么办？**  
+A: `hs setup` 会自动切换到下一个可用本地端口，并把准确访问地址打印出来；也可以运行 `hs doctor` 查看当前 `gateway.port` 和端口占用情况。
 
 **Q: 如何恢复原来的配置？**  
 A: 运行 `hs reset` 清除所有 HolySheep 相关配置。
 
 **Q: OpenClaw 安装失败？**  
-A: OpenClaw 需要 Node.js 20+，运行 `node --version` 确认版本后重试。
+A: OpenClaw 需要 Node.js 20+，运行 `node --version` 确认版本后重试；如果全局安装失败，`hs setup` 也会尽量回退到 `npx openclaw` 继续配置。
 
 ---
 
 ## Changelog
 
+- **v1.6.3** — OpenClaw 默认模型改为 GPT-5.4，并继续保留 Claude 模型切换能力
+- **v1.6.2** — 修复 OpenClaw 配置误判与 npx 回退，端口冲突时自动切换空闲端口，并补充 Doctor 诊断
 - **v1.6.0** — 新增 Droid CLI 一键配置，默认写入 GPT-5.4 / Sonnet 4.6 / Opus 4.6 / MiniMax 2.7 Highspeed / Haiku 4.5
 - **v1.5.2** — OpenClaw 安装失败（无 git 环境）时自动降级为 npx 模式继续配置
 - **v1.5.0** — OpenClaw gateway 无需 token，直接浏览器打开 http://127.0.0.1:18789/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simonyea/holysheep-cli",
-  "version": "1.6.0",
+  "version": "1.6.3",
   "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",
@@ -42,7 +42,7 @@
   "homepage": "https://holysheep.ai",
   "repository": {
     "type": "git",
-    "url": "https://github.com/holysheep123/holysheep-cli"
+    "url": "git+https://github.com/holysheep123/holysheep-cli.git"
   },
   "license": "MIT",
   "bin": {

package/src/commands/doctor.js

@@ -12,9 +12,11 @@ async function doctor() {
   console.log(chalk.gray('━'.repeat(50)))
   console.log()
 
+  const nodeMajor = parseInt(process.version.slice(1), 10)
+
   // Node.js 版本
   const nodeVer = process.version
-  const nodeOk = parseInt(nodeVer.slice(1)) >= 16
+  const nodeOk = nodeMajor >= 16
   printCheck(nodeOk, `Node.js ${nodeVer}`, nodeOk ? '' : '需要 >= 16')
 
   // API Key
@@ -23,32 +25,38 @@ async function doctor() {
 
   // 环境变量
   const envAnthropicKey = process.env.ANTHROPIC_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN
-  const envOpenAIKey    = process.env.OPENAI_API_KEY
+  const envOpenAIKey = process.env.OPENAI_API_KEY
   const envAnthropicUrl = process.env.ANTHROPIC_BASE_URL
-  const envOpenAIUrl    = process.env.OPENAI_BASE_URL
+  const envOpenAIUrl = process.env.OPENAI_BASE_URL
 
   console.log()
   console.log(chalk.bold('环境变量:'))
   printCheck(!!envAnthropicKey, 'ANTHROPIC_API_KEY / AUTH_TOKEN', envAnthropicKey ? maskKey(envAnthropicKey) : '未设置')
   printCheck(!!envAnthropicUrl, 'ANTHROPIC_BASE_URL', envAnthropicUrl || '未设置')
-  printCheck(!!envOpenAIKey,    'OPENAI_API_KEY',     envOpenAIKey ? maskKey(envOpenAIKey) : '未设置')
-  printCheck(!!envOpenAIUrl,    'OPENAI_BASE_URL',    envOpenAIUrl || '未设置')
+  printCheck(!!envOpenAIKey, 'OPENAI_API_KEY', envOpenAIKey ? maskKey(envOpenAIKey) : '未设置')
+  printCheck(!!envOpenAIUrl, 'OPENAI_BASE_URL', envOpenAIUrl || '未设置')
 
   // 各工具检查
   console.log()
   console.log(chalk.bold('工具状态:'))
 
   for (const tool of TOOLS) {
-    const installed  = tool.checkInstalled()
+    const installState = getInstallState(tool)
+    const installed = installState.installed
     const configured = installed ? tool.isConfigured() : null
-    const version    = installed ? getVersion(tool.id) : null
+    const version = installState.version
+    const suffix = installState.detail ? chalk.gray(` (${installState.detail})`) : ''
 
     if (!installed) {
       console.log(`  ${chalk.gray('○')} ${chalk.gray(tool.name.padEnd(20))} ${chalk.gray('未安装')} ${chalk.gray(`— ${tool.installCmd}`)}`)
     } else if (configured) {
-      console.log(`  ${chalk.green('✓')} ${chalk.green(tool.name.padEnd(20))} ${chalk.gray(version || '已安装')} ${chalk.green('已配置 HolySheep')}`)
+      console.log(`  ${chalk.green('✓')} ${chalk.green(tool.name.padEnd(20))} ${chalk.gray(version || '已安装')}${suffix} ${chalk.green('已配置 HolySheep')}`)
     } else {
-      console.log(`  ${chalk.yellow('!')} ${chalk.yellow(tool.name.padEnd(20))} ${chalk.gray(version || '已安装')} ${chalk.yellow('未配置')} ${chalk.gray(`— 运行 hs setup`)}`)
+      console.log(`  ${chalk.yellow('!')} ${chalk.yellow(tool.name.padEnd(20))} ${chalk.gray(version || '已安装')}${suffix} ${chalk.yellow('未配置')} ${chalk.gray('— 运行 hs setup')}`)
+    }
+
+    if (tool.id === 'openclaw' && installed) {
+      printOpenClawDetails(tool, installState, nodeMajor)
     }
   }
 
@@ -79,32 +87,119 @@ async function doctor() {
 }
 
 function printCheck(ok, label, detail = '') {
-  const icon   = ok ? chalk.green('✓') : chalk.red('✗')
-  const lbl    = ok ? chalk.green(label.padEnd(35)) : chalk.red(label.padEnd(35))
-  const det    = detail ? chalk.gray(detail) : ''
+  const icon = ok ? chalk.green('✓') : chalk.red('✗')
+  const lbl = ok ? chalk.green(label.padEnd(35)) : chalk.red(label.padEnd(35))
+  const det = detail ? chalk.gray(detail) : ''
   console.log(`  ${icon} ${lbl} ${det}`)
 }
 
+function printOpenClawDetails(tool, installState, nodeMajor) {
+  const details = []
+  const gatewayPort = typeof tool.getGatewayPort === 'function' ? tool.getGatewayPort() : 18789
+  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'))
+
+  if (installState.detail === 'npx fallback') {
+    details.push({
+      level: 'info',
+      text: '未检测到全局 openclaw，当前将通过 npx 运行',
+    })
+  }
+
+  details.push(
+    nodeMajor >= 20
+      ? { level: 'ok', text: `OpenClaw Node 版本要求满足（当前 ${process.version}）` }
+      : { level: 'warn', text: `OpenClaw 建议 Node.js >= 20（当前 ${process.version}）` }
+  )
+
+  if (primaryModel) {
+    details.push({
+      level: 'info',
+      text: `当前默认模型：${primaryModel}`,
+    })
+  }
+
+  if (foreignListeners.length) {
+    const occupiedBy = foreignListeners
+      .slice(0, 2)
+      .map((item) => `${item.command}(${item.pid})`)
+      .join(', ')
+    details.push({
+      level: 'warn',
+      text: `Gateway 端口 ${gatewayPort} 被其他进程占用：${occupiedBy}`,
+    })
+  } else if (listeners.length) {
+    details.push({
+      level: 'ok',
+      text: `Gateway 端口 ${gatewayPort} 当前由 OpenClaw 占用`,
+    })
+  } else {
+    details.push({
+      level: 'info',
+      text: `Gateway 端口 ${gatewayPort} 当前空闲；如刚完成配置，可运行 ${tool.launchCmd}`,
+    })
+  }
+
+  details.forEach((detail) => {
+    const icon = detail.level === 'ok'
+      ? chalk.green('↳')
+      : detail.level === 'warn'
+        ? chalk.yellow('↳')
+        : chalk.gray('↳')
+    const text = detail.level === 'ok'
+      ? chalk.green(detail.text)
+      : detail.level === 'warn'
+        ? chalk.yellow(detail.text)
+        : chalk.gray(detail.text)
+    console.log(`    ${icon} ${text}`)
+  })
+}
+
 function maskKey(key) {
   if (!key || key.length < 8) return '****'
   return key.slice(0, 6) + '...' + key.slice(-4)
 }
 
-function getVersion(toolId) {
+function getInstallState(tool) {
+  if (tool.id === 'openclaw' && typeof tool.detectRuntime === 'function') {
+    const runtime = tool.detectRuntime()
+    return {
+      installed: runtime.available,
+      version: runtime.version,
+      detail: runtime.via === 'npx' ? 'npx fallback' : '',
+    }
+  }
+
+  const installed = tool.checkInstalled()
+  return {
+    installed,
+    version: installed ? getVersion(tool) : null,
+    detail: '',
+  }
+}
+
+function getVersion(tool) {
+  if (typeof tool.getVersion === 'function') {
+    return tool.getVersion()
+  }
+
   const cmds = {
     'claude-code': 'claude --version',
-    'codex':       'codex --version',
-    'droid':       'droid --version',
-    'gemini-cli':  'gemini --version',
-    'opencode':    'opencode --version',
-    'openclaw':    'openclaw --version',
-    'aider':       'aider --version',
+    'codex': 'codex --version',
+    'droid': 'droid --version',
+    'gemini-cli': 'gemini --version',
+    'opencode': 'opencode --version',
+    'openclaw': 'openclaw --version',
+    'aider': 'aider --version',
   }
-  const cmd = cmds[toolId]
+  const cmd = cmds[tool.id]
   if (!cmd) return null
   try {
     return execSync(cmd, { stdio: 'pipe' }).toString().trim().split('\n')[0].slice(0, 30)
-  } catch { return null }
+  } catch {
+    return null
+  }
 }
 
 module.exports = doctor

package/src/commands/setup.js

@@ -195,7 +195,7 @@ async function setup(options) {
           justInstalled.add(tool.id)
         } else if (tool.id === 'openclaw') {
           // openclaw 安装失败时（如无 git），改用 npx 模式继续配置
-          // checkInstalled() 里已有 npx fallback，标记为已安装
+          // 这里直接标记为本次可配置，具体执行阶段再走 npx fallback
           console.log(chalk.yellow(`  ⚠️  全局安装失败，将使用 npx openclaw 代替`))
           tool._useNpx = true
           justInstalled.add(tool.id)

package/src/tools/droid.js

@@ -1,6 +1,6 @@
 /**
  * Droid CLI 适配器
- * 配置文件: ~/.factory/config.json
+ * 配置文件: ~/.factory/settings.json
  *
  * 使用 Droid 原生 customModels 配置 HolySheep 的多个模型入口：
  * - GPT 走 OpenAI 兼容入口:   https://api.holysheep.ai/openai
@@ -12,7 +12,7 @@ const path = require('path')
 const os = require('os')
 
 const CONFIG_DIR = path.join(os.homedir(), '.factory')
-const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json')
+const SETTINGS_FILE = path.join(CONFIG_DIR, 'settings.json')
 
 const DEFAULT_MODELS = [
   {
@@ -52,18 +52,18 @@ const DEFAULT_MODELS = [
   },
 ]
 
-function readConfig() {
+function readSettings() {
   try {
-    if (fs.existsSync(CONFIG_FILE)) {
-      return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'))
+    if (fs.existsSync(SETTINGS_FILE)) {
+      return JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'))
     }
   } catch {}
   return {}
 }
 
-function writeConfig(data) {
+function writeSettings(data) {
   fs.mkdirSync(CONFIG_DIR, { recursive: true })
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2), 'utf8')
+  fs.writeFileSync(SETTINGS_FILE, JSON.stringify(data, null, 2), 'utf8')
 }
 
 function normalizeSelectedModels(selectedModels) {
@@ -106,43 +106,43 @@ module.exports = {
     return require('../utils/which').commandExists('droid')
   },
   isConfigured() {
-    const config = readConfig()
-    const customModels = Array.isArray(config.customModels) ? config.customModels : []
+    const settings = readSettings()
+    const customModels = Array.isArray(settings.customModels) ? settings.customModels : []
     return customModels.some((item) =>
       typeof item.baseUrl === 'string' && item.baseUrl.includes('api.holysheep.ai')
     )
   },
   configure(apiKey, baseUrlAnthropic, _baseUrlOpenAI, _primaryModel, selectedModels) {
-    const config = readConfig()
-    const preservedModels = Array.isArray(config.customModels)
-      ? config.customModels.filter(
+    const settings = readSettings()
+    const preservedModels = Array.isArray(settings.customModels)
+      ? settings.customModels.filter(
           (item) => !(typeof item.baseUrl === 'string' && item.baseUrl.includes('api.holysheep.ai'))
         )
       : []
 
-    config.customModels = [
+    settings.customModels = [
       ...buildCustomModels(apiKey, baseUrlAnthropic, selectedModels),
       ...preservedModels,
     ]
-    config.logoAnimation = 'off'
-    writeConfig(config)
+    settings.logoAnimation = 'off'
+    writeSettings(settings)
 
     return {
-      file: CONFIG_FILE,
+      file: SETTINGS_FILE,
       hot: true,
     }
   },
   reset() {
-    const config = readConfig()
-    if (Array.isArray(config.customModels)) {
-      config.customModels = config.customModels.filter(
+    const settings = readSettings()
+    if (Array.isArray(settings.customModels)) {
+      settings.customModels = settings.customModels.filter(
         (item) => !(typeof item.baseUrl === 'string' && item.baseUrl.includes('api.holysheep.ai'))
       )
     }
-    writeConfig(config)
+    writeSettings(settings)
   },
-  getConfigPath() { return CONFIG_FILE },
-  hint: '已写入 ~/.factory/config.json；重启 Droid 后可见 HolySheep 模型列表',
+  getConfigPath() { return SETTINGS_FILE },
+  hint: '已写入 ~/.factory/settings.json；重启 Droid 后可见 HolySheep 模型列表',
   launchCmd: 'droid',
   installCmd: 'brew install --cask droid',
   docsUrl: 'https://docs.factory.ai/cli/getting-started/overview',

package/src/tools/openclaw.js

@@ -1,221 +1,491 @@
 /**
  * OpenClaw 适配器 (v2 — 基于实测的正确配置格式)
  *
- * 正确方案：custom-api-key provider，配置在 models.providers 里
- * provider name 自动生成为 "custom-api-{hostname}"
- * 模型引用格式: "custom-api-holysheep-ai/claude-sonnet-4-6"
- *
- * 必须的 onboard 参数:
- *   --accept-risk --auth-choice custom-api-key
- *   --custom-base-url --custom-api-key --custom-model-id --custom-compatibility anthropic
- *   --install-daemon
+ * 正确方案：写入 HolySheep 的 OpenAI + Anthropic 双 provider，
+ * 默认模型固定为 GPT-5.4，同时保留 Claude 模型供 /model 切换。
  */
-const fs   = require('fs')
+const fs = require('fs')
 const path = require('path')
-const os   = require('os')
+const os = require('os')
 const { spawnSync, spawn, execSync } = require('child_process')
+const { commandExists } = require('../utils/which')
 
 const OPENCLAW_DIR = path.join(os.homedir(), '.openclaw')
-const CONFIG_FILE  = path.join(OPENCLAW_DIR, 'openclaw.json')
-const isWin        = process.platform === 'win32'
+const CONFIG_FILE = path.join(OPENCLAW_DIR, 'openclaw.json')
+const isWin = process.platform === 'win32'
+const DEFAULT_GATEWAY_PORT = 18789
+const MAX_PORT_SCAN = 20
+const OPENCLAW_DEFAULT_MODEL = 'gpt-5.4'
+const OPENCLAW_DEFAULT_CLAUDE_MODEL = 'claude-sonnet-4-6'
+
+function hasOpenClawBinary() {
+  return commandExists('openclaw')
+}
+
+function hasNpx() {
+  return commandExists('npx')
+}
+
+function getRunner(preferNpx = false) {
+  if (!preferNpx && hasOpenClawBinary()) {
+    return { cmd: 'openclaw', argsPrefix: [], shell: false, label: 'openclaw', via: 'binary' }
+  }
+  if (hasNpx()) {
+    return { cmd: 'npx', argsPrefix: ['openclaw'], shell: isWin, label: 'npx openclaw', via: 'npx' }
+  }
+  if (hasOpenClawBinary()) {
+    return { cmd: 'openclaw', argsPrefix: [], shell: false, label: 'openclaw', via: 'binary' }
+  }
+  return null
+}
+
+/** 运行 openclaw CLI（优先全局命令，可切换到 npx 回退） */
+function runOpenClaw(args, opts = {}) {
+  const runner = getRunner(Boolean(opts.preferNpx))
+  if (!runner) {
+    return { status: 1, stdout: '', stderr: 'OpenClaw CLI not found' }
+  }
 
-/** 运行 openclaw CLI */
-function npx(...args) {
-  return isWin
-    ? spawnSync('npx', ['openclaw', ...args], { shell: true,  timeout: 30000, stdio: 'pipe' })
-    : spawnSync('openclaw',           args,   { shell: false, timeout: 30000, stdio: 'pipe' })
+  return spawnSync(runner.cmd, [...runner.argsPrefix, ...args], {
+    shell: runner.shell,
+    timeout: opts.timeout || 30000,
+    stdio: opts.stdio || 'pipe',
+    encoding: 'utf8',
+  })
+}
+
+function spawnOpenClaw(args, opts = {}) {
+  const runner = getRunner(Boolean(opts.preferNpx))
+  if (!runner) throw new Error('OpenClaw CLI not found')
+
+  const { preferNpx: _preferNpx, ...spawnOpts } = opts
+  return spawn(runner.cmd, [...runner.argsPrefix, ...args], {
+    shell: runner.shell,
+    ...spawnOpts,
+  })
+}
+
+function getPreferredRuntime() {
+  return module.exports._useNpx || !hasOpenClawBinary()
+}
+
+function firstLine(text) {
+  return String(text || '').trim().split('\n')[0] || ''
+}
+
+function getOpenClawVersion(preferNpx = false) {
+  const result = runOpenClaw(['--version'], { preferNpx, timeout: 15000 })
+  if (result.status !== 0) return null
+  return firstLine(result.stdout)
+}
+
+function detectRuntime() {
+  const preferNpx = getPreferredRuntime()
+  const version = getOpenClawVersion(preferNpx)
+
+  if (version) {
+    const runner = getRunner(preferNpx)
+    return {
+      available: true,
+      via: runner?.via || (preferNpx ? 'npx' : 'binary'),
+      command: runner?.label || (preferNpx ? 'npx openclaw' : 'openclaw'),
+      version,
+    }
+  }
+
+  if (!preferNpx && hasNpx()) {
+    const fallbackVersion = getOpenClawVersion(true)
+    if (fallbackVersion) {
+      return {
+        available: true,
+        via: 'npx',
+        command: 'npx openclaw',
+        version: fallbackVersion,
+      }
+    }
+  }
+
+  return { available: false, via: null, command: null, version: null }
 }
 
 function readConfig() {
   try {
     if (fs.existsSync(CONFIG_FILE)) {
       const raw = fs.readFileSync(CONFIG_FILE, 'utf8')
-      // 去掉 JSON5 注释再解析
-      return JSON.parse(raw.replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, ''))
+      try {
+        return JSON.parse(raw)
+      } catch {
+        // 兼容极少数带注释的配置，但不要误伤 https:// 之类的 URL
+        return JSON.parse(raw.replace(/^\s*\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, ''))
+      }
     }
   } catch {}
   return {}
 }
 
-module.exports = {
-  name: 'OpenClaw',
-  id:   'openclaw',
+function getConfiguredGatewayPort(config = readConfig()) {
+  const port = Number(config?.gateway?.port)
+  return Number.isInteger(port) && port > 0 ? port : DEFAULT_GATEWAY_PORT
+}
 
-  checkInstalled() {
-    if (require('../utils/which').commandExists('openclaw')) return true
+function getConfiguredPrimaryModel(config = readConfig()) {
+  return config?.agents?.defaults?.model?.primary || ''
+}
+
+function isPortInUse(port) {
+  try {
     if (isWin) {
-      try {
-        execSync('npx openclaw --version', { stdio: 'ignore', timeout: 15000, shell: true })
-        return true
-      } catch {}
+      const out = execSync(`netstat -ano | findstr :${port}`, { shell: true, stdio: 'pipe', encoding: 'utf8' })
+      return out.trim().length > 0
     }
+
+    execSync(`lsof -nP -iTCP:${port} -sTCP:LISTEN`, { shell: true, stdio: 'ignore' })
+    return true
+  } catch {
     return false
-  },
+  }
+}
 
-  isConfigured() {
-    const cfg = JSON.stringify(readConfig())
-    return cfg.includes('holysheep.ai')
-  },
+function listPortListeners(port) {
+  try {
+    if (isWin) {
+      const out = execSync(`netstat -ano | findstr :${port}`, { shell: true, stdio: 'pipe', encoding: 'utf8' })
+      return out
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => {
+          const parts = line.trim().split(/\s+/)
+          return { pid: parts[parts.length - 1], command: 'pid', detail: parts[1] || '' }
+        })
+    }
 
-  configure(apiKey, baseUrl, _baseUrlOpenAI, primaryModel, selectedModels) {
-    const chalk = require('chalk')
-    console.log(chalk.gray('\n  ⚙️  正在配置 OpenClaw...'))
+    const out = execSync(`lsof -nP -iTCP:${port} -sTCP:LISTEN`, { shell: true, stdio: 'pipe', encoding: 'utf8' })
+    return out
+      .trim()
+      .split('\n')
+      .slice(1)
+      .filter(Boolean)
+      .map((line) => {
+        const parts = line.trim().split(/\s+/)
+        return {
+          command: parts[0] || 'unknown',
+          pid: parts[1] || '?',
+          detail: parts[parts.length - 1] || '',
+        }
+      })
+  } catch {
+    return []
+  }
+}
 
-    // 1. 先停旧 gateway（必须在 onboard 之前，否则 hot-reload 会覆盖新 token）
-    npx('gateway', 'stop')
-    // 强制 kill 占用 18789 端口的进程（gateway stop 停不掉手动启动的进程）
-    try {
-      if (isWin) {
-        // netstat 找 pid，然后 taskkill
-        const out = execSync('netstat -ano | findstr :18789', { shell: true, encoding: 'utf8', stdio: 'pipe' })
-        const match = out.match(/\s(\d+)\s*$/)
-        if (match) execSync(`taskkill /F /PID ${match[1]}`, { shell: true, stdio: 'ignore' })
-      } else {
-        execSync('lsof -ti:18789 | xargs kill -9 2>/dev/null || true', { shell: true, stdio: 'ignore' })
-      }
-    } catch {}
-    // 等 1s 让端口释放
-    const t0 = Date.now(); while (Date.now() - t0 < 1000) {}
+function findAvailableGatewayPort(startPort = DEFAULT_GATEWAY_PORT) {
+  for (let offset = 0; offset < MAX_PORT_SCAN; offset++) {
+    const port = startPort + offset
+    if (!isPortInUse(port)) return port
+  }
+  return null
+}
 
-    // 2. 删除旧配置，确保 onboard 会重新写入
-    try { fs.unlinkSync(CONFIG_FILE) } catch {}
+function getLaunchCommand(port = getConfiguredGatewayPort()) {
+  const runtime = module.exports._lastRuntimeCommand || (hasOpenClawBinary() ? 'openclaw' : 'npx openclaw')
+  return `${runtime} gateway --port ${port}`
+}
 
-    // 3. 用 openclaw 官方 onboard 命令写入正确配置
-    //    这会生成完整的 models.providers.custom-api-holysheep-ai 配置
-    console.log(chalk.gray('  → 写入配置...'))
-    const result = npx(
-      'onboard',
-      '--non-interactive',
-      '--accept-risk',
-      '--auth-choice', 'custom-api-key',
-      '--custom-base-url', baseUrl,
-      '--custom-api-key', apiKey,
-      '--custom-model-id', primaryModel || 'claude-sonnet-4-6',
-      '--custom-compatibility', 'anthropic',
-      '--install-daemon',
-    )
+function buildProviderName(baseUrl, prefix) {
+  const hostname = new URL(baseUrl).hostname.replace(/\./g, '-')
+  return `${prefix}-${hostname}`
+}
 
-    if (result.status !== 0) {
-      // onboard 失败时 fallback：手写最小化配置
-      console.log(chalk.yellow('  ⚠️  onboard 失败，使用备用配置...'))
-      _writeFallbackConfig(apiKey, baseUrl, selectedModels, primaryModel)
-    }
+function buildModelEntry(id) {
+  return {
+    id,
+    name: `${id} (HolySheep)`,
+    reasoning: false,
+    input: ['text'],
+    contextWindow: 200000,
+    maxTokens: id.startsWith('gpt-') ? 8192 : 16000,
+  }
+}
 
-    // 4. 关闭 gateway token 认证（直接打开浏览器无需 token）
-    _disableGatewayAuth()
+function buildManagedPlan(apiKey, baseUrlAnthropic, baseUrlOpenAI, selectedModels) {
+  const requestedModels = Array.isArray(selectedModels) && selectedModels.length > 0
+    ? selectedModels
+    : [OPENCLAW_DEFAULT_MODEL, OPENCLAW_DEFAULT_CLAUDE_MODEL]
 
-    // 5. 启动 Gateway
-    console.log(chalk.gray('  → 正在启动 Gateway...'))
-    const ok = _startGateway()
+  const openaiModels = requestedModels.filter((model) => model.startsWith('gpt-'))
+  if (!openaiModels.includes(OPENCLAW_DEFAULT_MODEL)) {
+    openaiModels.unshift(OPENCLAW_DEFAULT_MODEL)
+  }
 
-    if (ok) {
-      console.log(chalk.green('  ✓ OpenClaw Gateway 已启动'))
-    } else {
-      console.log(chalk.yellow('  ⚠️  Gateway 启动中，稍等几秒后刷新浏览器'))
-    }
+  const claudeModels = requestedModels.filter((model) => model.startsWith('claude-'))
+  if (claudeModels.length === 0) {
+    claudeModels.push(OPENCLAW_DEFAULT_CLAUDE_MODEL)
+  }
 
-    const dashUrl = 'http://127.0.0.1:18789/'
-    console.log(chalk.cyan('\n  → 浏览器打开（无需 token）:'))
-    console.log(chalk.bold.cyan(`     ${dashUrl}`))
+  const openaiProviderName = buildProviderName(baseUrlOpenAI, 'custom-openai')
+  const anthropicProviderName = buildProviderName(baseUrlAnthropic, 'custom-anthropic')
 
-    return { file: CONFIG_FILE, hot: false }
-  },
+  const providers = {
+    [openaiProviderName]: {
+      baseUrl: baseUrlOpenAI,
+      apiKey,
+      api: 'openai-completions',
+      models: openaiModels.map(buildModelEntry),
+    },
+    [anthropicProviderName]: {
+      baseUrl: baseUrlAnthropic,
+      apiKey,
+      api: 'anthropic-messages',
+      models: claudeModels.map(buildModelEntry),
+    },
+  }
 
-  reset() {
-    try { fs.unlinkSync(CONFIG_FILE) } catch {}
-  },
+  const managedModelRefs = [
+    ...openaiModels.map((id) => `${openaiProviderName}/${id}`),
+    ...claudeModels.map((id) => `${anthropicProviderName}/${id}`),
+  ]
 
-  getConfigPath() { return CONFIG_FILE },
-  hint: 'Gateway 已启动，打开浏览器即可使用',
-  launchCmd: null,
-  get launchNote() {
-    return '🌐 打开浏览器: http://127.0.0.1:18789/'
-  },
-  installCmd: 'npm install -g openclaw@latest',
-  docsUrl:    'https://docs.openclaw.ai',
+  return {
+    providers,
+    managedModelRefs,
+    primaryRef: `${openaiProviderName}/${OPENCLAW_DEFAULT_MODEL}`,
+  }
+}
+
+function isHolySheepProvider(provider) {
+  return typeof provider?.baseUrl === 'string' && provider.baseUrl.includes('api.holysheep.ai')
 }
 
-/** onboard 失败时的备用配置（基于实测的正确格式） */
-function _writeFallbackConfig(apiKey, baseUrl, selectedModels, primaryModel) {
+function writeManagedConfig(baseConfig, apiKey, baseUrlAnthropic, baseUrlOpenAI, selectedModels, gatewayPort) {
   fs.mkdirSync(OPENCLAW_DIR, { recursive: true })
 
-  const hostname = new URL(baseUrl).hostname.replace(/\./g, '-')
-  const providerName = `custom-api-${hostname}`
+  const plan = buildManagedPlan(apiKey, baseUrlAnthropic, baseUrlOpenAI, selectedModels)
+  const existingProviders = baseConfig?.models?.providers || {}
+  const managedProviderIds = Object.entries(existingProviders)
+    .filter(([, provider]) => isHolySheepProvider(provider))
+    .map(([providerId]) => providerId)
 
-  // 默认配置的 Claude 模型列表（只注册 Claude 系列，MiniMax 用独立 provider）
-  const claudeModels = (selectedModels || ['claude-sonnet-4-6'])
-    .filter(m => m.startsWith('claude-'))
-  if (claudeModels.length === 0) claudeModels.push('claude-sonnet-4-6')
+  const preservedProviders = Object.fromEntries(
+    Object.entries(existingProviders).filter(([, provider]) => !isHolySheepProvider(provider))
+  )
 
-  const primary = primaryModel || claudeModels[0]
+  const existingModelMap = baseConfig?.agents?.defaults?.models || {}
+  const preservedModelMap = Object.fromEntries(
+    Object.entries(existingModelMap).filter(([ref]) => {
+      return !managedProviderIds.some((providerId) => ref.startsWith(`${providerId}/`))
+    })
+  )
 
-  const config = {
+  const managedModelMap = Object.fromEntries(plan.managedModelRefs.map((ref) => [ref, {}]))
+
+  const nextConfig = {
+    ...baseConfig,
     models: {
+      ...(baseConfig.models || {}),
       mode: 'merge',
       providers: {
-        [providerName]: {
-          baseUrl,
-          apiKey,
-          api: 'anthropic-messages',
-          models: claudeModels.map(id => ({
-            id,
-            name: `${id} (HolySheep)`,
-            reasoning: false,
-            input: ['text'],
-            contextWindow: 200000,
-            maxTokens: 16000,
-          })),
-        }
-      }
+        ...preservedProviders,
+        ...plan.providers,
+      },
     },
     agents: {
+      ...(baseConfig.agents || {}),
       defaults: {
-        model: { primary: `${providerName}/${primary}` }
-      }
+        ...(baseConfig.agents?.defaults || {}),
+        model: {
+          ...(baseConfig.agents?.defaults?.model || {}),
+          primary: plan.primaryRef,
+        },
+        models: {
+          ...preservedModelMap,
+          ...managedModelMap,
+        },
+      },
     },
     gateway: {
+      ...(baseConfig.gateway || {}),
       mode: 'local',
-      port: 18789,
+      port: gatewayPort,
       bind: 'loopback',
-      auth: { mode: 'none' },   // 无需 token，本地访问直接打开
-    }
+      auth: {
+        ...(baseConfig.gateway?.auth || {}),
+        mode: 'none',
+      },
+    },
   }
 
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8')
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(nextConfig, null, 2), 'utf8')
+  return plan
 }
 
-/** 用 openclaw config set 把 gateway auth 改成 none */
-function _disableGatewayAuth() {
+function _disableGatewayAuth(preferNpx = false) {
   try {
-    npx('config', 'set', 'gateway.auth.mode', 'none')
+    runOpenClaw(['config', 'set', 'gateway.auth.mode', 'none'], { preferNpx })
   } catch {}
 }
 
-/** 启动 Gateway 后台进程 */
-function _startGateway() {
-  if (isWin) {
-    spawnSync('cmd /c start cmd /k "npx openclaw gateway --port 18789"', [], {
-      shell: true, timeout: 5000, stdio: 'ignore',
-    })
-  } else {
-    const child = spawn('openclaw', ['gateway', '--port', '18789'], {
-      detached: true, stdio: 'ignore',
+function _installGatewayService(port, preferNpx = false) {
+  const result = runOpenClaw(['gateway', 'install', '--force', '--port', String(port)], {
+    preferNpx,
+    timeout: 60000,
+  })
+  return result.status === 0
+}
+
+function _startGateway(port, preferNpx = false, preferService = true) {
+  const serviceResult = preferService
+    ? runOpenClaw(['gateway', 'start'], { preferNpx, timeout: 20000 })
+    : { status: 1 }
+
+  if (serviceResult.status !== 0) {
+    const child = spawnOpenClaw(['gateway', '--port', String(port)], {
+      preferNpx,
+      detached: true,
+      stdio: 'ignore',
     })
     child.unref()
   }
 
-  // 等待最多 8 秒
   for (let i = 0; i < 8; i++) {
-    const t = Date.now(); while (Date.now() - t < 1000) {}
+    const t0 = Date.now()
+    while (Date.now() - t0 < 1000) {}
+
     try {
       execSync(
         isWin
-          ? 'powershell -NonInteractive -Command "try{(Invoke-WebRequest -Uri http://127.0.0.1:18789/ -TimeoutSec 1 -UseBasicParsing).StatusCode}catch{exit 1}"'
-          : 'curl -sf http://127.0.0.1:18789/ -o /dev/null --max-time 1',
+          ? `powershell -NonInteractive -Command "try{(Invoke-WebRequest -Uri http://127.0.0.1:${port}/ -TimeoutSec 1 -UseBasicParsing).StatusCode}catch{exit 1}"`
+          : `curl -sf http://127.0.0.1:${port}/ -o /dev/null --max-time 1`,
         { stdio: 'ignore', timeout: 3000 }
       )
       return true
     } catch {}
   }
+
   return false
 }
+
+module.exports = {
+  name: 'OpenClaw',
+  id: 'openclaw',
+
+  checkInstalled() {
+    return hasOpenClawBinary()
+  },
+
+  detectRuntime,
+
+  getVersion() {
+    return detectRuntime().version
+  },
+
+  isConfigured() {
+    const cfg = JSON.stringify(readConfig())
+    return cfg.includes('holysheep.ai')
+  },
+
+  configure(apiKey, baseUrlAnthropic, baseUrlOpenAI, _primaryModel, selectedModels) {
+    const chalk = require('chalk')
+    console.log(chalk.gray('\n  ⚙️  正在配置 OpenClaw...'))
+
+    const runtime = detectRuntime()
+    if (!runtime.available) {
+      throw new Error('未检测到 OpenClaw；请先全局安装，或确保 npx 可用')
+    }
+    this._lastRuntimeCommand = runtime.command
+
+    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)
+      if (listeners.length) {
+        const summary = listeners
+          .slice(0, 2)
+          .map((item) => `${item.command}(${item.pid})`)
+          .join(', ')
+        console.log(chalk.gray(`     占用进程: ${summary}`))
+      }
+    }
+
+    try { fs.unlinkSync(CONFIG_FILE) } catch {}
+
+    console.log(chalk.gray('  → 写入配置...'))
+    const result = runOpenClaw([
+      'onboard',
+      '--non-interactive',
+      '--accept-risk',
+      '--auth-choice', 'custom-api-key',
+      '--custom-base-url', baseUrlOpenAI,
+      '--custom-api-key', apiKey,
+      '--custom-model-id', OPENCLAW_DEFAULT_MODEL,
+      '--custom-compatibility', 'openai',
+      '--gateway-port', String(gatewayPort),
+      '--install-daemon',
+    ], { preferNpx: runtime.via === 'npx' })
+
+    if (result.status !== 0) {
+      console.log(chalk.yellow('  ⚠️  onboard 失败，使用备用配置...'))
+    }
+
+    writeManagedConfig(
+      result.status === 0 ? readConfig() : {},
+      apiKey,
+      baseUrlAnthropic,
+      baseUrlOpenAI,
+      selectedModels,
+      gatewayPort,
+    )
+
+    _disableGatewayAuth(runtime.via === 'npx')
+    const serviceReady = _installGatewayService(gatewayPort, runtime.via === 'npx')
+
+    console.log(chalk.gray('  → 正在启动 Gateway...'))
+    const ok = _startGateway(gatewayPort, runtime.via === 'npx', serviceReady)
+
+    if (ok) {
+      console.log(chalk.green('  ✓ OpenClaw Gateway 已启动'))
+    } else {
+      console.log(chalk.yellow('  ⚠️  Gateway 启动中，稍等几秒后刷新浏览器'))
+    }
+
+    const dashUrl = `http://127.0.0.1:${gatewayPort}/`
+    console.log(chalk.cyan('\n  → 浏览器打开（无需 token）:'))
+    console.log(chalk.bold.cyan(`     ${dashUrl}`))
+    console.log(chalk.gray(`     默认模型: ${OPENCLAW_DEFAULT_MODEL}`))
+
+    return {
+      file: CONFIG_FILE,
+      hot: false,
+      dashboardUrl: dashUrl,
+      gatewayPort,
+      launchCmd: getLaunchCommand(gatewayPort),
+    }
+  },
+
+  reset() {
+    try { fs.unlinkSync(CONFIG_FILE) } catch {}
+  },
+
+  getConfigPath() { return CONFIG_FILE },
+  getGatewayPort() { return getConfiguredGatewayPort() },
+  getPrimaryModel() { return getConfiguredPrimaryModel() },
+  getPortListeners(port = getConfiguredGatewayPort()) { return listPortListeners(port) },
+  get hint() {
+    return `Gateway 已启动，默认模型为 ${getConfiguredPrimaryModel() || OPENCLAW_DEFAULT_MODEL}`
+  },
+  get launchCmd() {
+    return getLaunchCommand(getConfiguredGatewayPort())
+  },
+  get launchNote() {
+    return `🌐 打开浏览器: http://127.0.0.1:${getConfiguredGatewayPort()}/`
+  },
+  installCmd: 'npm install -g openclaw@latest',
+  docsUrl: 'https://docs.openclaw.ai',
+}