# 🐑 HolySheep CLI

<div align="center">

**[English](#english) | [中文](#chinese)**

[![npm version](https://img.shields.io/npm/v/@simonyea/holysheep-cli?color=orange&label=npm)](https://www.npmjs.com/package/@simonyea/holysheep-cli)
[![npm downloads](https://img.shields.io/npm/dm/@simonyea/holysheep-cli?color=blue)](https://www.npmjs.com/package/@simonyea/holysheep-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Register](https://img.shields.io/badge/🔑_Get_API_Key-holysheep.ai-brightgreen)](https://holysheep.ai/register)

<br/>

**One command to configure all AI coding tools with HolySheep API**<br/>
**一条命令，配置所有 AI 编程工具**

<br/>

[🚀 Quick Start](#quick-start) · [📦 npm](https://www.npmjs.com/package/@simonyea/holysheep-cli) · [🌐 holysheep.ai](https://holysheep.ai)

</div>

---

<a name="english"></a>

## 🇬🇧 English

### What is HolySheep CLI?

**HolySheep CLI** (`hs`) is a command-line tool that automatically configures all popular AI coding assistants to use [HolySheep API](https://holysheep.ai) — a relay service for accessing Claude, GPT, and Gemini APIs in China without a VPN.

Instead of manually editing config files for each tool, run one command and you're done.

### Supported Tools

| Tool | Config File | Status |
|------|-------------|--------|
| [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/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 |
| [OpenClaw](https://openclaw.ai) | `~/.openclaw/openclaw.json` | ✅ Auto |
| [Cursor](https://cursor.sh) | GUI (encrypted storage) | ⚠️ Manual |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Google protocol only | ❌ Not supported |

### Quick Start

> 🔑 **First, get your free API Key** → [**holysheep.ai/register**](https://holysheep.ai/register) (free signup, pay-as-you-go from ¥10)

```bash
npx @simonyea/holysheep-cli@latest setup
```

Or install globally:

```bash
npm install -g @simonyea/holysheep-cli
hs setup
```

You'll be prompted for your API Key (`cr_xxx`), then select the tools to configure. Done!

### OpenClaw Setup

[OpenClaw](https://openclaw.ai) is a powerful AI agent gateway with a web dashboard. After running `hs setup`:

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 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`.

To restart the gateway later:
```bash
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 |
|---------|-------------|
| `hs setup` | Configure AI tools interactively |
| `hs login` | Save your API Key locally |
| `hs doctor` | Check configuration & connectivity |
| `hs balance` | View account balance |
| `hs tools` | List all supported tools |
| `hs reset` | Remove all HolySheep configuration |

### API Endpoints

| Usage | URL |
|-------|-----|
| Anthropic SDK / Claude Code | `https://api.holysheep.ai` (no `/v1`) |
| OpenAI-compatible / Codex / Aider | `https://api.holysheep.ai/v1` (with `/v1`) |

### `hs web` — real AionUi v1.9.18, HolySheep-powered (2.1.0+)

Starting from **2.1.0**, `hs web` is no longer a legacy workspace — it boots the **real [AionUi](https://github.com/iOfficeAI/AionUi) v1.9.18 source fork**, with one source-level change: the login page accepts a **HolySheep API Key** instead of username/password. The full AionUi UI, conversations, team, tools, MCP, everything — unchanged upstream experience, HolySheep-native auth.

```bash
# Install CLI (still ~100 kB — the 21 MB runtime is fetched on first run)
npm install -g @simonyea/holysheep-cli

# First run: downloads the prebuilt AionUi runtime into ~/.holysheep/aionui-runtime/
hs web --setup-runtime

# Subsequent runs: reuses the cached runtime
hs web
```

**What happens on `hs web`:**

1. Resolves the AionUi runtime from `~/.holysheep/aionui-runtime/` (or the dev `aionui-fork/` checkout when running from source).
2. Spawns the patched `dist-server/server.mjs` via `bun` on port 9876.
3. If `~/.holysheep/config.json` has a key (`sk_...` or legacy `cr_...`), opens a one-time local login link and signs you into the AionUi dashboard without exposing the key in terminal history.
4. Otherwise opens `/login` and you paste the key manually.

**Manual configuration / troubleshooting:**

If `hs setup` or `hs web` cannot save the key, create the config file manually:

```bash
mkdir -p ~/.holysheep
cat > ~/.holysheep/config.json <<'JSON'
{
  "apiKey": "sk_your_key_from_holysheep_ai",
  "savedAt": "manual"
}
JSON
chmod 600 ~/.holysheep/config.json
```

Then verify the key and start the Web UI:

```bash
hs whoami
hs web --setup-runtime
HS_WEB_DEBUG=1 hs web
```

Temporary install while npm registry still shows an older version:

```bash
npm install -g http://103.119.13.5:3000/api/packages/simon/generic/holysheep-cli/2.1.81/simonyea-holysheep-cli-2.1.81.tgz
```

Gitea tarball verification (Range GET returns `206 Partial Content`; full SHA256 is pinned):

```bash
curl -r 0-0 -D - http://103.119.13.5:3000/api/packages/simon/generic/holysheep-cli/2.1.81/simonyea-holysheep-cli-2.1.81.tgz -o /tmp/hs-cli-byte
# Content-Range: bytes 0-0/446671
# sha256: 74fc5dffd72943c07c9087d7fefad49bf1ce806f9e95a27263415030514a3108
```

Windows installer fallback package (unsigned NSIS installer):

```bash
curl -L -o HolySheep-Web-Setup-2.1.81-win-x64.exe \
  http://103.119.13.5:3000/api/packages/simon/generic/holysheep-web/2.1.81/HolySheep-Web-Setup-2.1.81-win-x64.exe
# size: 129738326 bytes
# sha256: 9672223636abc72c296e2dcae713c5f5321d56e46be45c8a4d2563043b1fee18
```

Common errors:

- `API Key must start with sk_ or cr_`: upgrade to `@simonyea/holysheep-cli >= 2.1.81`; older clients accepted only `cr_`.
- `ConnectionRefused` / `ECONNREFUSED` while opening `http://127.0.0.1:9876/`: the local AionUi runtime is not listening yet. Re-run `HS_WEB_DEBUG=1 hs web` to print the runtime log tail; if the cache is stale/corrupt, run `rm -rf ~/.holysheep/aionui-runtime && hs web --setup-runtime`.
- First Windows launch can take up to ~60s while Defender scans `bun.exe` and `server.mjs`; retry once before clearing the cache.

**npm registry publish currently blocked (use the Gitea tarball above):**

`@simonyea/holysheep-cli@2.1.83` was packed and sent to `registry.npmjs.org` with the current canonical token, but npm rejected the PUT because this token does **not** have 2FA bypass enabled. This is no longer the old missing-secret / wrong-scope failure: `npm whoami` succeeds as `simonyea`, and the token has package write permission, but `bypass_2fa=false`.

Local publish attempt (2026-05-23, log `/tmp/holysheep-npm-publish-2.1.83.log`) reached the official registry and failed with:

```text
npm notice package: @simonyea/holysheep-cli@2.1.83
npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access
npm error code E403
npm error 403 403 Forbidden - PUT https://registry.npmjs.org/@simonyea%2fholysheep-cli - Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages.
```

Token diagnostics (masked) confirmed:

```text
npm whoami -> simonyea
permissions: package:write, org:write
scopes: package=null, org=holysheep-ai, org=homiagent
bypass_2fa: false
```

Unblock path: issue a new npm Automation/Granular Access Token at <https://www.npmjs.com/settings/simonyea/tokens> with `Read and write` for `@simonyea/holysheep-cli` **and 2FA bypass enabled**, then update both the Gitea repo secret `NPM_TOKEN` and the local macOS Keychain entry `npm-token-simonyea` so CI and the dev machine stay in sync.

**What got patched (source-level, reviewable):**

| File (in `aionui-fork/`) | Change |
|----|----|
| `src/process/webserver/auth/service/HolySheepAuthService.ts` | New service — validates HS API Key via `GET {HOLYSHEEP_API_BASE}/v1/models`, 5-min TTL cache |
| `src/process/webserver/routes/authRoutes.ts` | `/login` gets a HolySheep branch: `body.apiKey` → HolySheep validate → sign standard AionUi JWT |
| `src/process/webserver/auth/middleware/AuthMiddleware.ts` | `validateLoginInput` skips username/password checks when `apiKey` is present |
| `src/renderer/hooks/context/AuthContext.tsx` | `login()` now accepts `apiKey` and picks payload accordingly |
| `src/renderer/pages/login/index.tsx` | Default mode: single API Key input. Toggle link: _"Sign in with local account"_ — restores upstream username/password flow (**nothing removed**) |

**Runtime resolution order** (first match wins):

1. `~/.holysheep/aionui-runtime/` (installed / cached)
2. `<cli>/src/webui/vendor/aionui/` (developer checkout — not shipped to npm)
3. `<cli>/../aionui-fork/` (git source fork, used when running from the holysheep-cli repo)
4. Download from `DEFAULT_RUNTIME_URL` (or `HOLYSHEEP_AIONUI_RUNTIME_URL`) when `--setup-runtime` is passed

**Prebuilt runtime (baked-in default):**

- URL: `https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.18-holysheep.tar.gz`
- SHA256: `379ae2a523542c0be55a84abbec5cd1db31684300c66db8aa35c4a02d38e9cb1`
- Size: 21 MB (contains `dist-server/` + `out/renderer/` only)

**Rebuild from source** (audit the patches yourself):

```bash
git clone https://github.com/iOfficeAI/AionUi.git aionui-fork
cd aionui-fork && git checkout v1.9.18
bun install
bun run build:server && bun run build:renderer:web
# Point the CLI at your local build:
cd .. && node src/index.js web
```

**Fallback modes:**

- `HOLYSHEEP_WEBUI_LEGACY=1 hs web` — old HolySheep Workspace page (zero-dep node, still ships in npm)
- `hs web --aionui` — force AionUi mode; do **not** auto-fall-back if runtime is missing (fails loudly instead)

**Roadmap:**

- **2.1.0 (this release)** ✓ Real AionUi fork + HolySheep login — done
- **2.2.0 (next)** — Deep integration: HolySheep multi-tool configuration panel embedded in the AionUi sidebar (not a separate legacy page). Manage Claude Code / Cursor / Codex / Aider / continue from within AionUi.

---

<a name="chinese"></a>

## 🇨🇳 中文

### 什么是 HolySheep CLI？

**HolySheep CLI**（命令 `hs`）是一个命令行工具，帮你一键配置所有主流 AI 编程助手接入 [HolySheep API](https://holysheep.ai)。

无需 VPN，无需手动改配置文件，运行一条命令即可接入 Claude、GPT、Gemini。

### 支持的工具

| 工具 | 状态 | 说明 |
|------|------|------|
| [Claude Code](https://docs.anthropic.com/claude-code) | ✅ 自动 | Anthropic 官方 CLI |
| [Codex CLI](https://github.com/openai/codex) | ✅ 自动 | OpenAI 官方 CLI |
| Droid CLI | ✅ 自动 | Factory AI 终端智能体 |
| [Aider](https://aider.chat) | ✅ 自动 | AI 结对编程 |
| [Continue.dev](https://continue.dev) | ✅ 自动 | VS Code/JetBrains 插件 |
| [OpenCode](https://github.com/anomalyco/opencode) | ✅ 自动 | 终端 AI 编程助手 |
| [OpenClaw](https://openclaw.ai) | ✅ 自动 | AI 智能体网关 + Web 界面 |
| [Cursor](https://cursor.sh) | ⚠️ 手动 | 需在 GUI 中手动配置 |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ❌ 不支持 | 仅支持 Google 官方协议 |

### 快速开始

> 🔑 **第一步：注册获取 API Key** → [**holysheep.ai/register**](https://holysheep.ai/register)（免费注册，¥10 起充，按量计费）

```bash
npx @simonyea/holysheep-cli@latest setup
```

或全局安装：

```bash
npm install -g @simonyea/holysheep-cli
hs setup
```

按提示输入 API Key（`cr_xxx`），选择要配置的工具，完成！

### OpenClaw 使用说明

[OpenClaw](https://openclaw.ai) 是一个 AI 智能体网关，提供浏览器 Web 界面，支持聊天、任务、工具调用等功能。

**`hs setup` 配置完成后：**

1. HolySheep 会自动把 OpenClaw 接到 HolySheep API
2. 默认启动在 **`http://127.0.0.1:18789/`**
3. 如果 `18789` 被占用，`hs setup` 会自动切换到下一个可用本地端口
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` 检查版本。

**下次启动 Gateway：**
```bash
openclaw gateway --port <显示的端口>
# 或
npx openclaw gateway --port <显示的端口>
```

如果忘了端口，可以查看 `~/.openclaw/openclaw.json` 里的 `gateway.port`，或直接运行 `hs doctor`。

**默认模型：** `gpt-5.4`（可在 OpenClaw 内切换到 Claude 模型）

### 命令说明

| 命令 | 说明 |
|------|------|
| `hs setup` | 交互式配置 AI 工具 |
| `hs login` | 保存 API Key 到本地 |
| `hs doctor` | 检查配置状态和连通性 |
| `hs balance` | 查看账户余额 |
| `hs tools` | 列出所有支持的工具 |
| `hs reset` | 清除所有 HolySheep 配置 |

### 接入地址

| 用途 | 地址 |
|------|------|
| Anthropic SDK / Claude Code | `https://api.holysheep.ai`（不带 /v1） |
| OpenAI 兼容 / Codex / Aider | `https://api.holysheep.ai/v1`（带 /v1） |

### `hs web` —— 真 AionUi v1.9.18，HolySheep 驱动（2.1.0+）

**从 2.1.0 开始，`hs web` 不再是之前那个仿风格的 HolySheep Workspace 页面，而是真正的 [AionUi](https://github.com/iOfficeAI/AionUi) v1.9.18 源码 fork。** 唯一的源码级改造：登录页收 **HolySheep API Key**，不再是账号密码。AionUi 原来的所有功能（对话、团队、工具、MCP 等）全部保留，只是登录换了种方式。

```bash
# 安装 CLI（npm 包仍然 ~100 kB；21 MB runtime 首次运行再下载）
npm install -g @simonyea/holysheep-cli

# 第一次跑：自动下载预编译 AionUi runtime 到 ~/.holysheep/aionui-runtime/
hs web --setup-runtime

# 后续直接跑，复用缓存
hs web
```

**`hs web` 到底做了什么：**

1. 从 `~/.holysheep/aionui-runtime/`（或开发仓 `aionui-fork/`）找到 runtime。
2. 用 `bun` 直接启动打过补丁的 `dist-server/server.mjs`，端口 `9876`。
3. 如果 `~/.holysheep/config.json` 里有 key（`sk_...` 或历史 `cr_...`），会打开一次性本地登录链接进入 AionUi dashboard，不再把 key 明文放到终端 URL 里。
4. 如果没 key，就打开 `/login` 等手动粘贴。

**手动配置 / 排障：**

如果 `hs setup` 或 `hs web` 无法保存 key，可以手动写配置：

```bash
mkdir -p ~/.holysheep
cat > ~/.holysheep/config.json <<'JSON'
{
  "apiKey": "sk_从_holysheep_ai_复制的_key",
  "savedAt": "manual"
}
JSON
chmod 600 ~/.holysheep/config.json
```

然后验证并启动：

```bash
hs whoami
hs web --setup-runtime
HS_WEB_DEBUG=1 hs web
```

npm registry 还没更新时的临时安装通道：

```bash
npm install -g http://103.119.13.5:3000/api/packages/simon/generic/holysheep-cli/2.1.81/simonyea-holysheep-cli-2.1.81.tgz
```

Gitea tarball 验证方式（Range GET 返回 `206 Partial Content`，完整 SHA256 固定如下）：

```bash
curl -r 0-0 -D - http://103.119.13.5:3000/api/packages/simon/generic/holysheep-cli/2.1.81/simonyea-holysheep-cli-2.1.81.tgz -o /tmp/hs-cli-byte
# Content-Range: bytes 0-0/446671
# sha256: 74fc5dffd72943c07c9087d7fefad49bf1ce806f9e95a27263415030514a3108
```

Windows 安装包兜底下载（未签名 NSIS 安装器）：

```bash
curl -L -o HolySheep-Web-Setup-2.1.81-win-x64.exe \
  http://103.119.13.5:3000/api/packages/simon/generic/holysheep-web/2.1.81/HolySheep-Web-Setup-2.1.81-win-x64.exe
# size: 129738326 bytes
# sha256: 9672223636abc72c296e2dcae713c5f5321d56e46be45c8a4d2563043b1fee18
```

常见错误：

- `API Key must start with sk_ or cr_`：请升级到 `@simonyea/holysheep-cli >= 2.1.81`；旧客户端只接受 `cr_`。
- 打开 `http://127.0.0.1:9876/` 显示 `ConnectionRefused` / `ECONNREFUSED`：本地 AionUi runtime 没监听成功。运行 `HS_WEB_DEBUG=1 hs web` 查看 runtime 日志；如果缓存损坏，执行 `rm -rf ~/.holysheep/aionui-runtime && hs web --setup-runtime` 重建。
- Windows 首次启动可能因 Defender 扫描 `bun.exe` 和 `server.mjs` 慢到 60 秒左右；先重试一次，再清缓存。

**npm registry 暂时无法发布（请用上面的 Gitea tarball 安装）：**

`@simonyea/holysheep-cli@2.1.83` 已经用当前规范 token 打包并发往 `registry.npmjs.org`，但 npm 拒绝 PUT，因为这个 token **没有开启 2FA bypass**。这已经不是上一轮的 secret 缺失 / scope 错误：`npm whoami` 成功返回 `simonyea`，token 也有 package write 权限，但 `bypass_2fa=false`。

本机 publish 尝试（2026-05-23，日志 `/tmp/holysheep-npm-publish-2.1.83.log`）已经触达官方 registry，失败原文：

```text
npm notice package: @simonyea/holysheep-cli@2.1.83
npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access
npm error code E403
npm error 403 403 Forbidden - PUT https://registry.npmjs.org/@simonyea%2fholysheep-cli - Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages.
```

token 诊断（已掩码）确认：

```text
npm whoami -> simonyea
permissions: package:write, org:write
scopes: package=null, org=holysheep-ai, org=homiagent
bypass_2fa: false
```

解锁方式：在 <https://www.npmjs.com/settings/simonyea/tokens> 生成新的 npm Automation / Granular Access Token，给 `@simonyea/holysheep-cli` `Read and write` 权限，并**开启 2FA bypass**；然后同时更新 Gitea repo secret `NPM_TOKEN` 和本机 macOS Keychain entry `npm-token-simonyea`，确保 CI 与开发机的凭证保持一致。

**改了哪些源码（可审计）：**

| 文件（在 `aionui-fork/`） | 改动 |
|----|----|
| `src/process/webserver/auth/service/HolySheepAuthService.ts` | 新 service —— 调 `GET {HOLYSHEEP_API_BASE}/v1/models` 校验 key，5 分钟缓存 |
| `src/process/webserver/routes/authRoutes.ts` | `/login` 增加 HolySheep 分支：`body.apiKey` → 校验 → 签发标准 AionUi JWT |
| `src/process/webserver/auth/middleware/AuthMiddleware.ts` | `validateLoginInput` 在有 `apiKey` 时跳过账号密码校验 |
| `src/renderer/hooks/context/AuthContext.tsx` | `login()` 新增 `apiKey` 参数，按情况选 payload |
| `src/renderer/pages/login/index.tsx` | 默认 HolySheep API Key 单输入框，底部 "Sign in with local account" 链接保留上游账号密码流程（**任何功能都没删**）|

**runtime 查找顺序**（命中即用）：

1. `~/.holysheep/aionui-runtime/`（已安装 / 已缓存）
2. `<cli>/src/webui/vendor/aionui/`（开发者本地构建 —— npm 包不携带）
3. `<cli>/../aionui-fork/`（从 holysheep-cli 仓库直接跑时用 git 源码 fork）
4. 走 `--setup-runtime` 时，从 `DEFAULT_RUNTIME_URL`（或 `HOLYSHEEP_AIONUI_RUNTIME_URL`）下载

**预编译 runtime（内置默认值）：**

- URL: `https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.18-holysheep.tar.gz`
- SHA256: `379ae2a523542c0be55a84abbec5cd1db31684300c66db8aa35c4a02d38e9cb1`
- 大小: 21 MB（只包含 `dist-server/` + `out/renderer/`）

**从源码自己构建**（审计所有 patch）：

```bash
git clone https://github.com/iOfficeAI/AionUi.git aionui-fork
cd aionui-fork && git checkout v1.9.18
bun install
bun run build:server && bun run build:renderer:web
# 用自己 build 的 runtime 启动：
cd .. && node src/index.js web
```

**备用模式：**

- `HOLYSHEEP_WEBUI_LEGACY=1 hs web` —— 老 HolySheep Workspace 页面（零依赖 node，仍然随 npm 包发）
- `hs web --aionui` —— 强制 AionUi 模式；runtime 缺失时**不会自动回退**，直接报错（方便 CI 场景）

**后续规划：**

- **2.1.0（本次发布）** ✓ 真 AionUi fork + HolySheep 登录
- **2.2.0（下一步）** —— 深度集成：在 AionUi 侧栏内嵌 HolySheep 多工具配置面板（不再是独立 legacy 页面）。在 AionUi 界面里直接管理 Claude Code / Cursor / Codex / Aider / continue。

### 常见问题

**Q: API Key 在哪里获取？**  
A: 在 [holysheep.ai](https://holysheep.ai) 注册后，在「API 密钥」页面创建，格式为 `cr_xxx`。

**Q: 支持 Windows 吗？**  
A: 支持，需要 Node.js 16+。如果 `hs` 命令找不到，请重启终端，或直接用 `npx @simonyea/holysheep-cli@latest setup`。

**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` 和端口占用情况。

**Q: 如何恢复原来的配置？**  
A: 运行 `hs reset` 清除所有 HolySheep 相关配置。

**Q: OpenClaw 安装失败？**  
A: OpenClaw 需要 Node.js 20+，运行 `node --version` 确认版本后重试；如果全局安装失败，`hs setup` 也会尽量回退到 `npx openclaw` 继续配置。

---

## Changelog

- **v2.0.2** — `hs web` 现在内置 AionUi runtime（含 darwin-arm64 bun 运行时），不再依赖开发机上的 `/Users/.../AionUi` 源码目录；npm 安装后可直接起 HolySheep 登录版 AionUi
- **v2.0.1** — `hs web` 默认切到 HolySheep 登录版 AionUi runtime；本机检测到 AionUi + bun 时直接接管 WebUI，起不来才回退旧版 shell
- **v2.0.0** — 修复 `hs web` 的关键可用性问题：工具探测改为异步缓存，避免 WebUI 首屏请求卡死；workspace 对话上游请求增加超时保护，防止发送消息时接口悬挂
- **v1.7.135** — Droid CLI 的 GPT-5.4 配置切回官方要求的 `provider=openai + https://api.holysheep.ai/v1`；同时服务端兼容桥接 `gpt-5.4` 的 `/responses` 请求到 `/v1/chat/completions`
- **v1.7.134** — 修复并发配置/Worker 路径下 Droid CLI 的 GPT-5.4 BYOK 配置：GPT 走 `generic-chat-completion-api + https://api.holysheep.ai/v1`，避免误走 Anthropic `/v1/messages`
- **v1.7.53** — 修复 `hs claude` 在绝对 URL 代理路径下未透传 `x-hs-node-proxied` 的问题，避免同一会话里部分 Claude 请求被后端误判为非可信代理请求并随机触发 403
- **v1.7.52** — 将 `hs claude` 重构为本地 API 入口 + CONNECT 兜底代理：Claude Anthropic 请求默认先进入本地 process proxy，再补齐 HolySheep 会话头后转发，降低独立二进制 Claude Code 漏代理导致的 403
- **v1.7.51** — 修复 `hs claude` 在 Claude Code 独立二进制版本上的整进程代理：自动识别脚本入口 / 独立二进制并切换到 `NODE_OPTIONS` 注入或 `HTTP(S)_PROXY` 模式；同时增强 `hs doctor` 的 Claude 代理诊断
- **v1.6.14** — OpenClaw 新增 `gpt-5.3-codex-spark` 模型，通过本地 bridge 路由到 HolySheep `/v1`
- **v1.6.13** — Codex 配置改为直接写 `api_key` 到 config.toml，不再依赖环境变量，修复 Windows 上 setup 后无需重启终端即可使用；同时精简工具列表，只保留 Claude Code / Codex / Droid / OpenClaw
- **v1.6.12** — 修复 OpenClaw Bridge 对 GPT-5.4 的流式响应转换，避免 `holysheep/gpt-5.4` 在 OpenClaw 中报错；同时增强 Dashboard URL 解析，减少安装后浏览器打开黑屏/空白页
- **v1.6.11** — OpenClaw 新增本地 HolySheep Bridge，统一暴露单一 `holysheep` provider 以支持自由切换 GPT / Claude / MiniMax；同时保留用户所选默认模型，不再强制 GPT-5.4 作为 primary
- **v1.6.10** — 将可运行的 OpenClaw runtime（含 npx 回退）视为已安装，避免 Windows/Node 环境下重复提示安装；同时修复 Droid CLI 的 GPT `/v1` 接入地址并同步写入 `~/.factory/config.json`
- **v1.6.9** — 保留 OpenClaw 的 MiniMax 配置，并为 MiniMax 使用独立 provider id，避免与 Claude provider 冲突；在 OpenClaw 2026.3.13 下改为提示精确 `/model` 切换命令，而不是停止配置 MiniMax
- **v1.6.8** — 修复 Codex 重复写入 `config.toml` 导致的 duplicate key，并修复 OpenClaw 在 Windows 下的安装检测；针对 OpenClaw 2026.3.13 的模型路由回归，临时跳过 MiniMax 避免 `model not allowed`
- **v1.6.7** — OpenClaw 配置新增 `MiniMax-M2.7-highspeed`，并补齐节点迁移脚本中的 SSH 代理账号创建逻辑
- **v1.6.6** — 修复 Droid CLI 的 GPT-5.4 配置残留问题，同时同步 `~/.factory/settings.json` 和 `~/.factory/config.json`，统一使用 `openai + https://api.holysheep.ai/v1`
- **v1.6.5** — 修复 HolySheep 对 Droid Responses API 的兼容
- **v1.6.4** — 修复 OpenClaw 的 npx 运行时检测，避免配置后页面仍卡在 Unauthorized / 未连接状态
- **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/
- **v1.4.6** — 基于实测正确配置格式，彻底修复 OpenClaw 401 认证问题
- **v1.3.x** — OpenClaw 一键配置支持，自动写入配置并启动 Gateway

---

## License

MIT
��持，自动写入配置并启动 Gateway

---

## License

MIT