# 快速开始
本指南带你在 5 分钟内完成 iLink Hub 的安装、启动和客户端接入。
> **路径说明**：默认数据库为**当前工作目录**下的 `./ilink-hub.db`（可用 `DATABASE_URL` 覆盖）。与 AI 客户端相关的 URL 一般为 `http://<hub 主机>:8765`，管理面板为 `http://<hub 主机>:8765/hub/ui`。
## 前提条件
- 一个已开通 iLink API 的微信账号（ClawBot）
- macOS / Linux / Windows 机器（可访问外网）
- 可选：Docker（最简单的部署方式）
## 第一步：安装 iLink Hub
根据你的系统选择一种安装方式：
::: code-group
```bash [Homebrew（macOS 推荐）]
brew tap jeffkit/tap
brew install ilink-hub
```
```bash [macOS Apple Silicon (M 系列)]
curl -Lo ilink-hub https://github.com/jeffkit/ilink-hub/releases/latest/download/ilink-hub-macos-aarch64
chmod +x ilink-hub
sudo mv ilink-hub /usr/local/bin/
```
```bash [macOS Intel]
curl -Lo ilink-hub https://github.com/jeffkit/ilink-hub/releases/latest/download/ilink-hub-macos-x86_64
chmod +x ilink-hub
sudo mv ilink-hub /usr/local/bin/
```
```bash [Linux x86_64]
curl -Lo ilink-hub https://github.com/jeffkit/ilink-hub/releases/latest/download/ilink-hub-linux-x86_64
chmod +x ilink-hub
sudo mv ilink-hub /usr/local/bin/
```
```bash [Cargo（需要 Rust）]
cargo install ilink-hub
```
:::
> **Windows 用户**：从 [Releases 页面](https://github.com/jeffkit/ilink-hub/releases) 下载 `ilink-hub-windows-x86_64.exe`。
验证安装成功：
```bash
ilink-hub --version
```
## 第二步：启动 Hub（首次会自动出码登录）
直接启动即可，**不必**先单独执行 `ilink-hub login`：
```bash
ilink-hub serve --addr 0.0.0.0:8765
```
启动时 Hub 会按顺序解析真实 iLink Token：`ILINK_TOKEN` / `--token` → 数据库中已保存的凭证 → 若仍没有或已失效，则**在当前终端打印二维码**，用**已开通 iLink API 的微信**扫码后 Token 会写入数据库，随后服务继续运行。
```
首次启动需要绑定微信机器人，请扫描下方二维码登录。
（终端中的二维码块字符）
…
iLink login successful, token saved
```
若你只想更新 Token、不想拉起 HTTP 服务，可改用独立子命令（见 [QR 码登录](./login.md)）。
服务启动后，你会看到类似输出：
```
INFO ilink_hub: iLink Hub listening
INFO ilink_hub: … Admin / pairing …
```
::: tip 后台运行
使用 `nohup ilink-hub serve --addr 0.0.0.0:8765 &` 或者 systemd/screen 在后台保持运行。
:::
::: tip 本机 Hub + 手机扫码
若 Hub 跑在本机、需要手机扫配对页，默认会走 **ilinkhub.ai** 中继，无需先跑隧道。详见 [手机扫码配对](./pairing-tunnel.md)。
:::
## 第三步：打开 Web 管理面板
在浏览器中访问：
```
http://localhost:8765/hub/ui
```
你会看到 iLink Hub 的管理界面，可以在这里注册客户端并复制配置。
## 第四步：注册 AI 客户端
每个需要接入的 AI 后端都需要注册一次，获取一个专属的虚拟 Token。
**通过 CLI 注册：**
```bash
ilink-hub register \
--hub-url http://your-hub.example.com:8765 \
--name mac-home \
--label "Mac 本机"
```
**或通过 Web UI 注册**（在 `/hub/ui` 页面点击「注册新客户端」）
注册成功后会输出：
```
✓ 客户端注册成功！
客户端名称：mac-home
虚拟 Token：vhub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
请将以下配置添加到你的 AI 客户端：
WEIXIN_BASE_URL=http://your-hub.example.com:8765
WEIXIN_TOKEN=vhub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
## 第五步：配置 AI 客户端
将上一步获得的配置填入你的 AI 客户端：
::: code-group
```toml [Recursive (~/.recursive/config.toml)]
[weixin]
base_url = "http://your-hub.example.com:8765"
token = "vhub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```
```bash [环境变量（通用）]
export WEIXIN_BASE_URL=http://your-hub.example.com:8765
export WEIXIN_TOKEN=vhub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
```json [OpenClaw (~/.openclaw/openclaw.json)]
{
"channels": {
"weixin": {
"base_url": "http://your-hub.example.com:8765",
"token": "vhub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
```
:::
## 完成！测试一下
在微信中发送 `/status`，如果 Hub 正常运行，你会收到类似回复：
```
Hub 状态：在线
已注册客户端：2
在线客户端：1（mac-home）
```
::: tip 想立刻接本机命令行？
跟做 [本地 CLI Bridge：5 分钟上手](/bridge/quick-try)（用 `echo` 走通 Hub → Token → 回微信），无需先装 Recursive / OpenClaw。
:::
---
## 下一步
- [了解微信命令](/reference/commands) — 学习 `/list`、`/use` 等命令
- [本地 CLI Bridge：5 分钟上手](/bridge/quick-try) — 用虚拟 Token 把微信文本交给本机 `echo` / Claude / Codex 等
- [Docker 部署](/deployment/docker) — 更稳定的生产环境部署方式
- [安全建议](/deployment/security) — 如何保护你的 Hub 实例