🐑 HolySheep CLI

English | 中文

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

🚀 Quick Start · 📦 npm · 🌐 holysheep.ai

🇬🇧 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 — 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 | ~/.claude/settings.json | ✅ Auto | | Codex CLI | ~/.codex/config.toml | ✅ Auto | | Droid CLI | ~/.factory/settings.json | ✅ Auto | | Aider | ~/.aider.conf.yml | ✅ Auto | | Continue.dev | ~/.continue/config.yaml | ✅ Auto | | OpenCode | ~/.config/opencode/opencode.json | ✅ Auto | | OpenClaw | ~/.openclaw/openclaw.json | ✅ Auto | | Cursor | GUI (encrypted storage) | ⚠️ Manual | | Gemini CLI | Google protocol only | ❌ Not supported |

Quick Start

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

npx @simonyea/holysheep-cli@latest setup

Or install globally:

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 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:

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

# 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, opens http://127.0.0.1:9876/login#apiKey=cr_... — the login page reads the hash, auto-submits, and you land in the AionUi dashboard.
4. Otherwise opens /login and you paste the key manually.

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):

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.

🇨🇳 中文

什么是 HolySheep CLI？

HolySheep CLI（命令 hs）是一个命令行工具，帮你一键配置所有主流 AI 编程助手接入 HolySheep API。

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

支持的工具

| 工具 | 状态 | 说明 | |------|------|------| | Claude Code | ✅ 自动 | Anthropic 官方 CLI | | Codex CLI | ✅ 自动 | OpenAI 官方 CLI | | Droid CLI | ✅ 自动 | Factory AI 终端智能体 | | Aider | ✅ 自动 | AI 结对编程 | | Continue.dev | ✅ 自动 | VS Code/JetBrains 插件 | | OpenCode | ✅ 自动 | 终端 AI 编程助手 | | OpenClaw | ✅ 自动 | AI 智能体网关 + Web 界面 | | Cursor | ⚠️ 手动 | 需在 GUI 中手动配置 | | Gemini CLI | ❌ 不支持 | 仅支持 Google 官方协议 |

快速开始

🔑 第一步：注册获取 API Key → holysheep.ai/register（免费注册，¥10 起充，按量计费）

npx @simonyea/holysheep-cli@latest setup

或全局安装：

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

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

OpenClaw 使用说明

OpenClaw 是一个 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：

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 v1.9.18 源码 fork。 唯一的源码级改造：登录页收 HolySheep API Key，不再是账号密码。AionUi 原来的所有功能（对话、团队、工具、MCP 等）全部保留，只是登录换了种方式。

# 安装 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，浏览器会打开 http://127.0.0.1:9876/login#apiKey=cr_...，登录页读取 hash 自动提交，用户直接进入 AionUi dashboard。
4. 如果没 key，就打开 /login 等手动粘贴。

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

| 文件（在 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）：

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 注册后，在「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