快速开始

系统要求

要求	最低配置	推荐配置
操作系统	Windows 10 / macOS 12 / Ubuntu 20.04	Windows 11 / macOS 14 / Ubuntu 22.04
内存	4 GB	8 GB+
磁盘空间	500 MB	1 GB+
CPU	2 核	4 核+
Node.js	18+	20+

安装步骤

第一步：安装 CLI Hub

前往下载页面获取适合你操作系统的安装包。

powershellbashbash

::: code-group-item Windows

powershell

# 下载安装程序
Invoke-WebRequest -Uri "https://51clihub.com/download/v1.0.1/windows/cli-hub-win-1.0.1-x64.exe" -OutFile "cli-hub-win-1.0.1-x64.exe"

# 运行安装程序
.\cli-hub-win-1.0.1-x64.exe

::: ::: code-group-item macOS

bash

# Apple Silicon (M1/M2/M3/M4)
curl -O https://51clihub.com/download/v1.0.1/mac/cli-hub-mac-1.0.1-arm64.dmg
open cli-hub-mac-1.0.1-arm64.dmg

# Intel
curl -O https://51clihub.com/download/v1.0.1/mac/cli-hub-mac-1.0.1-x64.dmg
open cli-hub-mac-1.0.1-x64.dmg

# 拖拽到 Applications 文件夹

::: ::: code-group-item Linux

bash

# Ubuntu / Debian
wget https://51clihub.com/download/v1.0.1/linux/cli-hub-linux-1.0.1-amd64.deb
sudo dpkg -i cli-hub-linux-1.0.1-amd64.deb
sudo apt-get install -f

# Fedora / RHEL
wget https://51clihub.com/download/v1.0.1/linux/cli-hub-linux-1.0.1-x86_64.rpm
sudo rpm -i cli-hub-linux-1.0.1-x86_64.rpm

# AppImage（通用）
wget https://51clihub.com/download/v1.0.1/linux/cli-hub-linux-1.0.1-x86_64.AppImage
chmod +x cli-hub-linux-1.0.1-x86_64.AppImage
./cli-hub-linux-1.0.1-x86_64.AppImage

:::

第二步：环境准备

Windows 用户强烈建议使用 WSL2（Ubuntu 24.04）

AI 编程 CLI 工具（Claude Code、Codex CLI、OpenCode 等）均为终端程序，在 Windows 原生环境下运行容易出现权限问题和兼容性问题。强烈建议 Windows 用户安装 WSL2（Ubuntu 24.04），在 Linux 子系统中安装和使用所有 AI CLI 工具。

优势：

✅ 权限更容易控制 — Linux 文件权限模型比 Windows 更适合 CLI 工具的文件读写操作
✅ 兼容性更好 — 绝大多数 AI CLI 工具优先支持 Linux/macOS，WSL2 提供完整 Linux 环境
✅ 无缝访问 Windows 文件 — 通过 /mnt/c/、/mnt/d/ 等路径直接访问 Windows 磁盘文件
✅ 包管理更方便 — 使用 apt / npm 直接安装，无需处理 Windows 特有的路径和权限问题

WSL2 + Ubuntu 24.04 安装方法：

powershell

# 在 Windows PowerShell（管理员）中执行
wsl --install -d Ubuntu-24.04

# 如果 Ubuntu-24.04 不在列表中，先更新 WSL
wsl --update
# 然后查看可用发行版
wsl --list --online
# 安装 Ubuntu 24.04
wsl --install -d Ubuntu-24.04

# 安装完成后重启电脑，设置用户名和密码
# 进入 WSL2：
wsl

# 进入 WSL2 后，Windows 磁盘挂载在 /mnt/ 下：
#   C盘 → /mnt/c/
#   D盘 → /mnt/d/
#   例如你的项目在 D:\projects\my-app
#   在 WSL2 中访问路径为 /mnt/d/projects/my-app

访问 Windows 磁盘文件

WSL2 中所有 Windows 磁盘自动挂载到 /mnt/ 下，你可以像访问本地文件一样访问：

cd /mnt/c/Users/你的用户名/projects — 访问 C 盘项目
cd /mnt/d/workspace/my-app — 访问 D 盘项目
所有 CLI 工具在 WSL2 中运行时可直接读写这些文件

:::

安装 Node.js

AI 编程 CLI 工具依赖 Node.js 运行环境。请先安装 Node.js 20+：

bashbashpowershell

::: code-group-item Windows (WSL2) / Linux

bash

# 使用 nvm 安装（推荐，可管理多版本）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc

# 设置国内镜像加速
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

# 安装 Node.js 22 LTS
nvm install 22
nvm use 22

# 验证安装
node -v
npm -v

# 设置 npm 国内镜像
npm config set registry https://registry.npmmirror.com

Windows 用户

请先安装 WSL2（Ubuntu 24.04），在 WSL2 中执行以上命令。通过 /mnt/c/、/mnt/d/ 访问 Windows 磁盘文件。

::: ::: code-group-item macOS

bash

# 使用 Homebrew 安装
brew install node@22

# 或使用 nvm 安装（推荐，可管理多版本）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.zshrc

# 设置国内镜像加速
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

# 安装 Node.js 22 LTS
nvm install 22
nvm use 22

# 验证安装
node -v
npm -v

# 设置 npm 国内镜像
npm config set registry https://registry.npmmirror.com

::: ::: code-group-item Windows（不推荐，建议用 WSL2）

powershell

# 方式一：使用 winget 安装
winget install OpenJS.NodeJS.LTS

# 方式二：从官网下载安装包
# 访问 https://nodejs.org/ 下载 LTS 版本安装包

# 验证安装
node -v
npm -v

# 设置 npm 国内镜像
npm config set registry https://registry.npmmirror.com

WARNING

Windows 原生 Node.js 环境容易与 CLI 工具产生兼容性问题，强烈建议改用 WSL2（Ubuntu 24.04）安装。

:::

国内镜像加速说明

中国大陆用户建议配置以下镜像源，大幅提升下载速度：

工具	镜像源	配置方式
Node.js（nvm）	`https://npmmirror.com/mirrors/node`	`export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node`
npm	`https://registry.npmmirror.com`	`npm config set registry https://registry.npmmirror.com`
pip	`https://pypi.tuna.tsinghua.edu.cn/simple`	`pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple`
Homebrew	清华镜像	参考 https://mirrors.tuna.tsinghua.edu.cn/help/homebrew/

建议将 nvm 镜像配置写入 shell 配置文件（~/.bashrc 或 ~/.zshrc）使其永久生效：

bash

echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.bashrc

安装 Git

大部分 AI CLI 工具需要 Git 来进行代码操作：

bashbashbashpowershell

::: code-group-item Windows (WSL2) / Linux (Debian/Ubuntu)

bash

sudo apt update && sudo apt install -y git
git --version

::: ::: code-group-item Linux (Fedora/RHEL)

bash

sudo dnf install -y git
git --version

::: ::: code-group-item macOS

bash

# macOS 通常自带 Git，如需更新
brew install git
git --version

::: ::: code-group-item Windows（不推荐，建议用 WSL2）

powershell

# 安装 Git for Windows（必装，包含 Git Bash 和 SSH）
winget install Git.Git

# 或从 https://git-scm.com/ 下载安装包
git --version

WARNING

建议改用 WSL2（Ubuntu 24.04），在 WSL2 中通过 sudo apt install git 安装 Git，兼容性更好。

:::

第三步：安装 AI 编程 CLI（前置条件）

CLI Hub 需要 AI 编程 CLI 工具作为后端。请至少安装一个：

TIP

所有 CLI 的详细安装文档请参考左侧"前置条件 — 安装 AI 编程工具"部分。

::: code-group-item Claude Code（推荐）

bash

# macOS / Linux / WSL2（推荐）
curl -fsSL https://claude.ai/install.sh | bash

# 或使用 npm（国内镜像加速）
npm install -g @anthropic-ai/claude-code

# 需要 Claude Pro / Max / Team 订阅

Windows 用户请使用 WSL2 安装

Claude Code 在 Windows 原生环境下容易遇到权限和兼容性问题，强烈建议在 WSL2（Ubuntu 24.04）中安装使用：

powershell

# 1. 先安装 WSL2 + Ubuntu 24.04（PowerShell 管理员）
wsl --install -d Ubuntu-24.04

# 2. 进入 WSL2
wsl

# 3. 在 WSL2 中安装 Claude Code
curl -fsSL https://claude.ai/install.sh | bash

# 4. 访问 Windows 磁盘文件
cd /mnt/d/projects/my-app
claude

通过 /mnt/磁盘号/ 路径访问 Windows 文件，如 /mnt/c/、/mnt/d/。

推荐理由：Anthropic 官方出品，功能最完善，智能体工作流成熟。

详细文档 → Claude Code 安装与使用 ::: ::: code-group-item Codex CLI

bash

# npm 安装（国内镜像加速）
npm install -g @openai/codex

# 或 macOS Homebrew
brew install --cask codex

# 需要 OpenAI API Key 或 ChatGPT Plus 订阅

Windows 用户请使用 WSL2 安装

Codex CLI 在 Windows 原生环境下兼容性不佳，强烈建议在 WSL2（Ubuntu 24.04）中安装使用：

powershell

# 1. 先安装 WSL2 + Ubuntu 24.04（PowerShell 管理员）
wsl --install -d Ubuntu-24.04

# 2. 进入 WSL2
wsl

# 3. 在 WSL2 中安装 Codex CLI
npm install -g @openai/codex

# 4. 访问 Windows 磁盘文件
cd /mnt/d/projects/my-app
codex

通过 /mnt/磁盘号/ 路径访问 Windows 文件，如 /mnt/c/、/mnt/d/。

最新版本不支持国内大模型

Codex 最新版本已切换到 Responses API，不再支持 Chat/Completions API（wire_api = "chat"），因此无法接入国内大模型服务商（如阿里云百炼 Coding Plan、通义千问等）。

如需使用国内大模型，请安装旧版本：

bash

npm install -g @openai/codex@0.80.0

并配置 ~/.codex/config.toml：

toml

model_provider = "dashscope_coding"
model = "qwen3.6-plus"

[model_providers.dashscope_coding]
name = "dashscope_coding"
base_url = "https://coding.dashscope.aliyuncs.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

旧版与最新版区别

特性	旧版 (0.80.0)	最新版
API 协议	Chat/Completions API	Responses API
`wire_api = "chat"`	支持	不支持
国内大模型接入	支持（百炼 Coding Plan 等）	不支持
安装命令	`npm install -g @openai/codex@0.80.0`	`npm install -g @openai/codex`

启动旧版 Codex 时，务必选择**"跳过更新"**，否则会自动升级到不支持国内大模型的新版本
使用百炼 Coding Plan 时，必须使用套餐专属 API Key，不能用百炼通用 API Key（sk-xxx 格式）
详见阿里云百炼 Codex 接入指南 :::

推荐理由：OpenAI 出品，内置沙箱安全机制，适合注重安全性的场景。

详细文档 → Codex CLI 安装与使用 ::: ::: code-group-item OpenCode

bash

# 安装脚本
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

# 或 Homebrew
brew install opencode-ai/tap/opencode

# 支持多种 AI 提供商的 API Key

Windows 用户请使用 WSL2 安装

OpenCode 官方不支持 Windows，必须通过 WSL2（Ubuntu 24.04）安装使用：

powershell

# 1. 先安装 WSL2 + Ubuntu 24.04（PowerShell 管理员）
wsl --install -d Ubuntu-24.04

# 2. 进入 WSL2
wsl

# 3. 在 WSL2 中安装 OpenCode
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

# 4. 访问 Windows 磁盘文件
cd /mnt/d/projects/my-app
opencode

通过 /mnt/磁盘号/ 路径访问 Windows 文件，如 /mnt/c/、/mnt/d/。

推荐理由：开源免费，支持 10+ 模型提供商，灵活切换。

详细文档 → OpenCode 安装与使用 ::: ::: code-group-item OpenClaw

bash

# npm 安装（国内镜像加速）
npm install -g openclaw@latest

# 安装后运行引导
openclaw onboard --install-daemon

# 支持 25+ AI 提供商和 20+ 消息通道

Windows 用户请使用 WSL2 安装

OpenClaw 在 Windows 原生环境下运行需要 WSL2，强烈建议在 WSL2（Ubuntu 24.04）中安装使用：

powershell

# 1. 先安装 WSL2 + Ubuntu 24.04（PowerShell 管理员）
wsl --install -d Ubuntu-24.04

# 2. 进入 WSL2
wsl

# 3. 在 WSL2 中安装 OpenClaw
npm install -g openclaw@latest
openclaw onboard --install-daemon

# 4. 访问 Windows 磁盘文件
cd /mnt/d/projects/my-app
openclaw

通过 /mnt/磁盘号/ 路径访问 Windows 文件，如 /mnt/c/、/mnt/d/。

推荐理由：不仅仅是编码，还是完整的 AI 助手网关，支持多通道接入。

详细文档 → OpenClaw 安装与使用 :::

第四步：启动 CLI Hub

启动应用后，进入设置向导
CLI Hub 会自动扫描系统 PATH，检测已安装的 CLI 工具
如果检测到 CLI，状态会显示为 ✅ 可用；未检测到则显示 ❌ 未安装

WSL2 用户

如果 CLI 安装在 WSL2 中，CLI Hub 会自动检测 WSL2 环境中的 CLI。确保 WSL2 已启动且 CLI 已在 WSL2 的 PATH 中。

第五步：配置模型提供商

在设置 → 模型提供商中，添加你的 API Key：

提供商	环境变量	获取地址
OpenAI	`OPENAI_API_KEY`	https://platform.openai.com/api-keys
Anthropic	`ANTHROPIC_API_KEY`	https://console.anthropic.com/
Google Gemini	`GEMINI_API_KEY`	https://aistudio.google.com/apikey
Groq	`GROQ_API_KEY`	https://console.groq.com/keys
xAI	`XAI_API_KEY`	https://console.x.ai/

配置好后，将模型分配给对应的 CLI：

Claude Code → Anthropic Claude Opus 4.6
Codex CLI → OpenAI GPT-5.4
OpenCode → Google Gemini 2.5

第六步：配置 SSH 远程服务器（可选）

如需在远程服务器上运行 AI CLI：

进入设置 → 服务器管理
点击"添加服务器"
填写 SSH 连接信息：
- 主机地址和端口
- 用户名
- 认证方式（密码 / 私钥 / SSH Agent）
- 跳板机（可选）
点击"测试连接"验证
连接成功后，可在远程服务器上安装和运行 CLI

第七步：开始使用

在左侧面板选择一个 CLI 连接
点击"新建会话"或恢复历史会话
在右侧终端区与 AI 交互
使用文件树浏览项目，一键引用文件到对话

基础使用

界面布局

┌────────────────────────────────────────────────────┐
│  CLI Hub                          — □ ×    │
├──────────┬─────────────────────┬───────────────────┤
│ CLI 连接  │    AI 对话 / 终端    │   文件浏览器       │
│          │                     │                   │
│ ▸ Claude  │  > 帮我重构这个函数  │  📁 src/          │
│   Code   │  > 好的，我来分析... │  ├─ 📄 main.ts    │
│ ▸ Codex  │  > ✏️ 编辑文件...    │  ├─ 📄 utils.ts   │
│   CLI    │  > ✅ 重构完成       │  └─ 📁 components/│
│ ▸ Open   │                     │                   │
│   Code   │  [输入框________]    │   [引用到对话]     │
├──────────┴─────────────────────┴───────────────────┤
│  会话列表  │  模型: Claude Opus 4.6  │  SSH: dev-box │
└────────────────────────────────────────────────────┘

CLI 连接管理

操作	方法
启动 CLI	点击 CLI 名称旁的 ▶ 按钮
停止 CLI	点击 CLI 名称旁的 ■ 按钮
查看日志	右键 CLI → 查看日志
编辑配置	右键 CLI → 设置
新建实例	点击"+"添加新的 CLI 连接

会话操作

操作	快捷键	说明
新建会话	`Ctrl+N`	创建新的对话
保存会话	`Ctrl+S`	保存当前对话上下文
切换会话	`Ctrl+Tab`	在活跃会话间切换
关闭会话	`Ctrl+W`	关闭当前会话标签
搜索历史	`Ctrl+F`	在会话中搜索

文件引用

在右侧文件浏览器中选中文件
点击"引用到对话"按钮，或直接拖拽文件到对话区
在弹出的引用选项中选择：
- 整个文件 — 将全部内容作为上下文
- 行范围 — 指定 L1-L2 行
- 仅路径 — 由 CLI 自行读取文件

模型切换

在对话过程中快速切换模型：

点击底部的模型名称
从下拉菜单中选择新的模型
CLI 会自动使用新模型继续对话

常用配置

应用配置

在 设置 → 通用 中：

配置项	说明	默认值
启动时自动连接	应用启动时自动连接上次使用的 CLI	开启
自动保存会话	定期自动保存对话上下文	开启
会话保存间隔	自动保存的时间间隔	5 分钟
默认终端主题	终端的颜色主题	跟随系统
字体大小	终端和代码预览的字体大小	14px
忽略目录	文件树中排除的目录	node_modules, .git, dist

CLI 配置

在 设置 → CLI 管理 中，为每个 CLI 配置参数：

yaml

# Claude Code 配置
claude-code:
  model: claude-opus-4-6          # 默认模型
  autoAccept: false               # 自动接受编辑
  sandbox: true                   # 启用沙箱
  contextWindow: 200000           # 上下文窗口大小

# Codex CLI 配置
codex:
  model: gpt-5.4                  # 默认模型
  sandboxMode: workspace-write    # 沙箱模式
  approvalPolicy: on-request      # 审批策略
  fullAuto: false                 # 全自动模式

# OpenCode 配置
opencode:
  model: claude-3.7-sonnet        # 默认模型
  autoCompact: true               # 自动压缩上下文
  debug: false                    # 调试模式

SSH 配置

在 设置 → 服务器管理 中：

yaml

# SSH 服务器配置
servers:
  - name: dev-box
    host: 192.168.1.100
    port: 22
    user: developer
    auth: privatekey              # password / privatekey / agent
    keyFile: ~/.ssh/id_rsa
    proxyJump: jump-server        # 跳板机（可选）
    remoteCLI:
      - name: claude-code
        path: /usr/local/bin/claude
      - name: codex
        path: /usr/local/bin/codex

故障排查

CLI 未检测到

确认 CLI 已安装且在 PATH 中：which claude / which codex
在 CLI Hub 中手动添加 CLI 路径
重启 CLI Hub

API Key 无效

检查 Key 是否正确，无多余空格
使用"测试连接"功能验证
检查 Key 是否已过期或额度用尽
确认 Key 有权访问指定模型

SSH 连接失败

检查服务器地址和端口
确认认证信息正确
检查跳板机配置
查看应用日志：帮助 → 打开日志目录

会话丢失

检查"自动保存"是否开启
查看历史会话列表
检查磁盘空间是否充足

WSL2 常见问题

WSL2 中访问 Windows 文件慢？

WSL2 跨文件系统（/mnt/c/）访问速度较慢，建议将项目克隆到 WSL2 原生文件系统中（~/projects/），性能可提升 3-5 倍。

WSL2 网络代理问题？

如果 Windows 使用了代理，WSL2 中需要额外配置：

bash

# 获取 Windows 宿主 IP
export WIN_IP=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')

# 设置代理（端口号替换为你自己的）
export http_proxy="http://${WIN_IP}:7890"
export https_proxy="http://${WIN_IP}:7890"

下一步

功能特性 — 深入了解各项功能
Claude Code 安装 — 安装 Anthropic 官方 CLI
Codex CLI 安装 — 安装 OpenAI 编程智能体
OpenCode 安装 — 安装开源多模型 CLI
下载 — 获取最新版本

快速开始 ​

系统要求 ​

安装步骤 ​

第一步：安装 CLI Hub ​

第二步：环境准备 ​

安装 Node.js ​

安装 Git ​

第三步：安装 AI 编程 CLI（前置条件） ​

第四步：启动 CLI Hub ​

第五步：配置模型提供商 ​

第六步：配置 SSH 远程服务器（可选） ​

第七步：开始使用 ​

基础使用 ​

界面布局 ​

CLI 连接管理 ​

会话操作 ​

文件引用 ​

模型切换 ​

常用配置 ​

应用配置 ​

CLI 配置 ​

SSH 配置 ​

故障排查 ​

CLI 未检测到 ​

API Key 无效 ​

SSH 连接失败 ​

会话丢失 ​

WSL2 常见问题 ​

下一步 ​

快速开始

系统要求

安装步骤

第一步：安装 CLI Hub

第二步：环境准备

安装 Node.js

安装 Git

第三步：安装 AI 编程 CLI（前置条件）

第四步：启动 CLI Hub

第五步：配置模型提供商

第六步：配置 SSH 远程服务器（可选）

第七步：开始使用

基础使用

界面布局

CLI 连接管理

会话操作

文件引用

模型切换

常用配置

应用配置

CLI 配置

SSH 配置

故障排查

CLI 未检测到

API Key 无效

SSH 连接失败

会话丢失

WSL2 常见问题

下一步