文档

Capri 是什么、三个组件怎么分工、单机与多机拓扑如何选择。

一句话

Grok Build 的远程控制台。Agent 仍然跑在你自己的机器上读写代码与执行命令，浏览器只负责跨屏操控与权限审批。

Capri（Capricorn）基于 ACP 协议适配 Grok Build，由一个浏览器前端、一个本机守护节点和一个可选的跨网中继组成。

三个组件

节点二进制已内嵌前端构建产物：单机场景只需启动节点本身，打开 http://localhost:8765 即为完整控制台。

两种拓扑

单机直连（零中继）：

浏览器 ──127.0.0.1:8765──▶ capri-host ──stdio──▶ grok

跨网多机（经 Hub 汇聚，同机自动走直连近路）：

浏览器 ──▶ capri-hub :8787 ──┬─▶ 家里的 Mac（Capri.app）        ──▶ grok
                              ├─▶ 办公室的 PC（Capri.exe）       ──▶ grok
                              └─▶ 服务器上的节点（capri-host）   ──▶ grok

三条核心边界

• 三端版本保持对齐：前端、中继、节点共享同一套 ACP 事件契约，升级或回滚时请保持版本一致。
• 两把 FE_TOKEN 彼此独立：Hub 的 FE_TOKEN 保护公网中继入口，Host 的 FE_TOKEN 保护本机 :8765 接口。Host 默认绑定 127.0.0.1，留空即可本机免鉴权直连。
• 门禁密钥只存浏览器本地：密钥由用户在页面门禁中输入并分槽保存在浏览器 localStorage，不写进前端构建环境变量。

下一步：本机上手。

macOS 菜单栏应用、Windows 托盘应用与命令行二进制的安装、启动与配置。

前置

从 capri-host Releases 选择你的平台安装：桌面端推荐使用图形化应用，Linux 与服务器使用命令行二进制。

一、macOS 应用（推荐，macOS 13+）

下载 Capri-macos.zip（或 Capri-macos.dmg），把 Capri.app 拖进「应用程序」后打开。

1. 屏幕顶部菜单栏会出现摩羯座图标。
2. 首次使用点击摩羯座图标 → 「设置…」（快捷键 ⌘,），按需填写设备显示名、端口、grok 路径或代理，点击 「保存并启动」。
3. 菜单栏顶部状态会显示 Host 已在 :8765 启动。
4. 点击菜单栏里的 「打开界面」，即可在浏览器跳转本地 Web UI（http://localhost:8765）。

菜单栏还直接提供 「阻止电脑休眠」、「登录时启动」、「打开日志」；当访问范围切到「局域网」时，还会多出 「复制局域网地址」 方便手机或平板打开。

首次打开若被 macOS 拦下，可在访达中右键 Capri.app 点「打开」，或在终端运行：

xattr -dr com.apple.quarantine /Applications/Capri.app

二、Windows 应用（推荐）

下载 Capri-windows-amd64.zip（或 Capri-windows-arm64.zip，按系统架构选择），解压后进入 Capri 目录，双击 Capri.exe。

解压后的目录结构：

Capri/
├── Capri.exe            双击运行的就是它：系统托盘图标、对话框、Host 进程的启停与守护
└── bin/
    └── Capri-host.exe   干活的后台引擎（HTTP + grok），由 Capri.exe 自动拉起

注意不要单独双击 bin/Capri-host.exe——引擎是控制台子系统程序，单独双击只会弹出一个黑窗口；由 Capri.exe 启动时会以无窗口方式在后台运行并自动接管日志。请把整个 Capri 目录完整保留在同一处，Capri.exe 会按相对路径寻找 bin/Capri-host.exe。

右键任务栏托盘里的摩羯座图标：

1. 点击 「设置…」 在浏览器中打开图形化设置页面（/settings），配置好后保存。
2. 通过托盘菜单点击 「启动 Host」 或 「重启 Host」 让配置生效。
3. 点击 「打开 Capri 控制台」 进入本地 Web UI。
4. 托盘菜单还支持勾选 「阻止电脑休眠」、「开机自启」，以及查看 「连接与诊断信息…」、「打开日志目录」 和 「编辑原始配置 (config.json)」。

三、命令行二进制与源码构建

适合 Linux、远程服务器、脚本或 systemd 托管。从 Releases 下载对应平台的 Capri-host-*：

chmod +x ./Capri-host   # 按实际文件名
./Capri-host

或者从源码构建运行：

git clone https://github.com/AgentsHarness/capri-host.git
cd capri-host
go run ./cmd/capri-host

浏览器访问 http://localhost:8765。

如果需要自己打包桌面应用（需要先将前端构建产物放入 internal/server/web/dist）：

# 打包 macOS 通用应用（arm64 + amd64）
./packaging/macos/make-app.sh --universal

# 打包 Windows 目录包（Capri/Capri.exe + Capri/bin/Capri-host.exe）
./packaging/windows/make-exes.sh amd64 arm64

四、配置文件与环境变量

图形设置界面写入 ~/.capri-host/config.json；命令行、launchd 与 systemd 传入的环境变量会覆盖其中的同名字段，因此可以临时用 PORT=9000 ./Capri-host 更换端口。完整变量表与优先级见环境变量。

测试或便携安装可设置 CAPRI_HOME 更换配置目录。

接下来

• 想从外网访问、或者把家里和办公室的多台机器接在一起 → 远程与多机
• 想改前端或自己嵌入新界面 → 前端开发
• 开机自启、systemd 托管与日志位置 → 日常运维
• 出问题了 → 排障

起一台中继 Hub，用 macOS / Windows 设置界面或命令行把多台机器接进来。

适用场景

一台公网服务器跑中继（capri-hub），家里、办公室、服务器上各跑一个节点，浏览器从任何地方打开、随时在左上角切换机器。

浏览器 ──▶ capri-hub :8787 ──▶ capri-host × N ──▶ grok

一、起中继（Hub）

你需要一台能被访问的服务器。推荐使用 Docker Compose 部署，或直接下载 Release 二进制运行。

方式 A：Docker Compose（推荐）

cp .env.example .env       # 填入 FE_TOKEN：openssl rand -hex 24
mkdir -p data && sudo chown -R 10001:10001 data
docker compose up -d
docker compose exec capri-hub capri-hub paircode    # ← 查看当前 6 位配对码

多架构镜像位于 ghcr.io/agentsharness/capri-hub。

方式 B：裸二进制

FE_TOKEN=$(openssl rand -hex 24) ./capri-hub

• HTTP 监听 :8787，节点主通道 QUIC UDP :8788
• 安全组放行 UDP :8788 更稳；不放行会自动回退 WebSocket，功能不受影响
• 生产务必设置 FE_TOKEN（浏览器门禁）；加上 REQUIRE_FE_TOKEN=1 可在未配密钥时拒绝启动

查看与轮换配对码

配对码为 6 位数字，15 分钟有效、过期自动轮换。除了在前端左上角点「添加 Host」查看外，也可以在服务器上随时操作：

capri-hub paircode           # 查看当前有效配对码
capri-hub paircode -rotate   # 立即换一个新码（旧码失效）
capri-hub paircode -json     # JSON 输出供脚本使用

或调用 HTTP 接口（设置了 FE_TOKEN 时需带 Bearer 头）：

curl -H "Authorization: Bearer $FE_TOKEN" http://127.0.0.1:8787/api/pairing
curl -X POST -H "Authorization: Bearer $FE_TOKEN" http://127.0.0.1:8787/api/pairing/rotate

二、把节点接进来

macOS 应用与 Windows 应用

无需手写环境变量：

1. macOS（Capri.app）：点击菜单栏摩羯图标 → 「设置…」，在 「Hub」 分组填入 Hub URL 与 6 位 配对码，点击 「立即配对」（或底部 「保存并启动」）。配对成功后界面会显示 已连接 · QUIC（或 WS），菜单栏也会出现 「打开 Hub 控制台」。后续可在设置窗随时点击「更换配对…」「立即重连」或「断开 Hub」。
2. Windows（Capri.exe）：右键系统托盘摩羯图标 → 「设置…」 打开网页设置界面，填入 Hub URL 与 配对码 并保存，即可在线完成配对或重启 Host 生效。

桌面应用会把 hub_url 保存在 ~/.capri-host/config.json，配对换回的长期凭据保存在 ~/.capri-host/hub.json。

命令行二进制（Linux / 服务器）

HUB_URL=https://your-hub \
HUB_PAIR_CODE=XXXXXX \
HOST_ID=server-1 \
HOST_NAME="家里的服务器" \
nohup ./Capri-host >> capri-host.log 2>&1 & echo $! > capri-host.pid

要点：

• 每台机器给一个不同的 HOST_ID（桌面应用会自动生成本机标识），这是多机之间的区分依据。
• 配对成功后长期 token 写进 ~/.capri-host/hub.json（与 HUB_URL 地址绑定），之后重启只需保留 HUB_URL，不再需要一次性配对码。
• 若更换了 HUB_URL 地址，需要重新配对一次以生成对应新地址的凭据。

三、两把 FE_TOKEN 与本机直连

Hub 和每台 Host 各有一把 FE_TOKEN，它们保护的对象不同，不要求同值：

• 经 Hub 中继的请求由 Host 进程自己向 Hub 出示配对凭据，浏览器只向 Hub 出示 Hub 那把 FE_TOKEN；
• 浏览器直连本机端口（当页面发现你选中的 Host 就跑在当前这台电脑上时，会默认直连 127.0.0.1:8765，省去一跳中继延迟，Hub 维护时本机也照常可用），出示的才是 这台 Host 自己的 FE_TOKEN。

因此最省心的典型配法是：

• 只在 Hub 上设置 FE_TOKEN；
• 每台 Host 保持默认回环监听（BIND=127.0.0.1 / 访问范围选「仅本机」），且 Host 的 FE_TOKEN 留空——回环 + 无密钥 = 本机直连免鉴权，浏览器全程只需输入一次 Hub 密钥。
• 如果也给 Host 设了密钥，页面会先拿 Hub 那把试探一次本机（GET /api/probe）：两把同值就直接连通，不同值才弹一次「这台 Host 的钥匙」（按机器独立保存在浏览器本地，输错或拒填也只会让那一台退回走 Hub 中继，不影响 Hub 登录）。

一次请求从浏览器到 Agent 走过的每一段，以及桌面端双进程与本机直连机制。

分层

浏览器（前端 capri-fe）
   │  HTTP /api/* + 实时事件流（同机优先直连 127.0.0.1:8765）
   ▼
中继 capri-hub :8787         ← 可选；配对、发现、转发
   │  QUIC UDP :8788（自动回退 WebSocket）
   ▼
节点 capri-host :8765        ← 你的机器；界面 + 接口同端口
   │  stdio JSON-RPC（ACP）
   ▼
内核 grok                   ← 真正读文件、跑命令的 Agent 进程

桌面应用的双进程结构

在 macOS 与 Windows 上，Capri 采用「轻量壳进程 + 后台引擎进程」的双进程拆分：

• macOS（Capri.app）：Contents/MacOS/Capri 是原生 SwiftUI 菜单栏进程，负责状态展示、设置窗口、开机自启（ServiceManagement）与系统防休眠（IOKit），并在后台拉起与守护 Contents/MacOS/Capri-host。
• Windows（Capri/ 目录）：Capri.exe 是无控制台窗口的 GUI 托盘进程，负责系统托盘菜单、状态轮询、防休眠与开机自启注册表项，并以无窗口方式拉起 bin/Capri-host.exe、将其标准错误输出接管为轮转日志文件。

壳进程与引擎进程共享 ~/.capri-host/config.json（跨进程文件锁保护）与本地控制端点（/api/hub/state、/api/hub/pair、/api/hub/reuse、/api/hub/disconnect），因此无需重启应用即可在图形界面里完成在线配对、切换连接和修改配置。

每一段做什么

浏览器 → 中继 / 节点

普通 HTTP 接口加一条事件流：请求走 /api/*，实时输出走事件流。

• 单机直连模式：浏览器直接访问 http://localhost:8765，所有请求直达本机节点。
• Hub 模式下的本机近路：即使从公网 Hub 页面进入，只要前端探测到当前选中的节点就在这台电脑的 127.0.0.1:8765 上，也会默认直连本地端口（也可在左上角节点列表的右键菜单中手动切换「直连本机」或「经 Hub 中继」）。

中继 → 节点

一条长连接，默认走 QUIC（UDP :8788），UDP 不通则自动回退 WebSocket。中继在这条连接上只做双向转发：

• 下行：浏览器的指令、权限审批结果
• 上行：会话事件、工具调用、权限请求、后台任务状态

中继本身不执行命令、不落业务数据。它只知道哪台节点在线，不接触你的代码库。

节点 → 内核

节点通过标准输入输出与 grok 进程通信（stdio JSON-RPC，遵循 ACP 协议），负责：

1. 能力协商与事件规整：连接时声明客户端能力，将会话事件、工具输出与审批请求规整为统一前端契约
2. 会话续传与按需补全：恢复会话时不重放全量历史，大体积工具输出后台排队按需补全
3. 服务端裁剪：将回滚（Rewind）后的死分支在服务端直接裁掉，前端无需重复判断

端口一览

配置文件 config.json 与三个组件的全部环境变量、默认值与优先级。

配置优先级

节点支持配置文件与环境变量两种配置方式，优先级从低到高为：

内置默认值  <  ~/.capri-host/config.json  <  环境变量

• 桌面应用（Capri.app / Capri.exe）在图形设置界面保存的项写入 ~/.capri-host/config.json。
• 命令行、launchd、systemd 传入的环境变量会覆盖 ~/.capri-host/config.json 中的同名字段：

PORT=9000 HOST_NAME="我的 Mac" ./Capri-host

全部变量

节点

中继

前端

关键配置速记

• 局域网监听强制鉴权：设 BIND=0.0.0.0（或设置中选「局域网」）时必须同时配置本机 FE_TOKEN，否则节点拒绝启动。
• 代理自动跟随系统：PROXY 与 NO_PROXY 留空时自动读取系统网络代理与排除列表；系统未开代理则直连。
• 配对凭据绑定地址：~/.capri-host/hub.json 中的长期凭据与 HUB_URL 绑定，更换 Hub 地址后需重新配对一次。

本地调试前端、连接中继或节点，以及将构建产物内嵌回桌面应用与节点二进制。

本地启动开发服务器

确保本机已有运行中的节点（:8765）或可访问的中继（:8787）：

pnpm install
pnpm run dev

打开 http://localhost:5173。开发服务器默认将 /api 与 /events 代理至本机 http://localhost:8765。

若需直接联调多机中继：

VITE_PROXY_TARGET=http://your-relay:8787 pnpm run dev

技术栈与常用脚本

React 19 · TypeScript · Vite · Tailwind · Zustand。

pnpm run build   # 类型检查 + 生产打包（输出至 dist/）
pnpm run lint    # 静态检查

将新前端内嵌回节点与桌面应用

capri-host 使用 go:embed 内嵌前端静态产物，更新界面后按三步重新打包：

# 1. 构建前端产物
cd capri-fe && pnpm run build

# 2. 同步至节点的 go:embed 目录
rm -rf ../capri-host/internal/server/web/dist
mkdir -p ../capri-host/internal/server/web
cp -R dist ../capri-host/internal/server/web/dist

# 3. 编译二进制或打包桌面端
cd ../capri-host
go build ./cmd/capri-host                        # 单文件命令行二进制
./packaging/macos/make-app.sh                      # macOS 应用（dist/Capri.app）
./packaging/windows/make-exes.sh amd64 arm64       # Windows 应用（dist/windows/<arch>/Capri/）

macOS / Windows 桌面端自启与防休眠、Linux systemd 服务、日志位置与升级顺序。

开机自启与防止休眠 · 桌面应用（推荐）

在 macOS 与 Windows 上，直接使用桌面应用菜单即可管理生命周期，无需手写系统服务配置：

• macOS（Capri.app）：点击菜单栏摩羯图标，直接勾选 「登录时启动」 与 「阻止电脑休眠」；也可在「设置… → 启动」中开关 「打开应用时启动 Host」。
• Windows（Capri.exe）：右键任务栏托盘摩羯图标，直接勾选 「开机自启」（写入当前用户 Run 注册表项，移动目录后启动会自动修正路径）与 「阻止电脑休眠」（按住系统电源请求，显示器仍可正常息屏）。

后台运行与自启 · Linux / 纯命令行

不装桌面应用或跑在 Linux 服务器上时，可用后台命令或服务单元托管 Capri-host：

nohup ./Capri-host >> capri-host.log 2>&1 & echo $! > capri-host.pid
# 停止：
kill "$(cat capri-host.pid)"

Linux systemd 服务单元

/etc/systemd/system/capri-host.service：

[Unit]
Description=Capri Agent Node
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=your-user
ExecStart=/绝对路径/Capri-host
Restart=always
RestartSec=3
Environment=HOST_ID=srv-1
Environment=HOST_NAME=我的服务器
Environment=HUB_URL=https://your-hub

[Install]
WantedBy=multi-user.target

启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable --now capri-host

日志在哪看

端口与防火墙

升级顺序

事件契约由前端、中继、节点三端共享，升级时保持步调一致：

1. 将中继（capri-hub）、节点（Capri.app / Capri.exe / Capri-host）与前端更新到同一版本
2. 先重启中继，再重启各台节点
3. 刷新浏览器页面

常见现象、原因与处理方式速查表。

常见问题速查

反馈问题时建议附带的信息

若以上方法仍未解决，排查或提交 Issue 时请附上：

1. 三端版本号：macOS 设置窗底部、Windows 托盘「连接与诊断信息…」或命令行启动日志可查看。
2. 运行形态与拓扑：Capri.app、Capri.exe 或命令行二进制；单机直连还是经 Hub 中继。
3. 节点日志前 20 行：macOS 点击菜单栏「打开日志」，Windows 点击托盘「打开日志目录」，Linux 执行 journalctl -u capri-host -n 20。
4. 浏览器控制台报错：开发者工具 Network / Console 中的异常请求状态码。