# 安装、连接与授权

> 在 RooQi Mac 版中启用外部连接、配置 MCP 客户端并批准访问。

- Source: https://rooqi.cn/zh-hans/docs/developers/connect/
- Platforms: 仅 Mac（macOS 14 或更高版本）
- Version: RooQi Mac 1.0 测试版本 · 桥接协议 v1
- Status: 预览——尚未公开发布
- Last verified: 2026-10-26，依据 RooQi Mac 源码及其界面文案
- Known limitations: 桥接程序位于 RooQi.app 内，移动 App 后路径会变。更新 RooQi 后请关闭并重新启用连接。客户端配置示例尚未逐一在所有 MCP 客户端上测试。

## 1. 启用外部连接

1. 在 Mac 上打开 **RooQi**，进入**设置 › 外部连接**。
2. 点**启用连接**。
3. 如系统提示，请在**系统设置 › 登录项与扩展**中允许 RooQi 的后台连接服务，然后点**刷新状态**。

**关闭连接**会停止接受新请求；已经受理的操作可能继续完成——关闭连接不等于撤销，RooQi 会在连接状态下列出它们。

## 2. 找到桥接程序

命令行桥接程序随 App 一起提供：

```sh
/Applications/RooQi.app/Contents/Helpers/RooQiBridge.app/Contents/MacOS/rooqi
```

可以添加别名：

```sh
alias rooqi="/Applications/RooQi.app/Contents/Helpers/RooQiBridge.app/Contents/MacOS/rooqi"
rooqi status
```

`rooqi status` 输出一行 JSON；RooQi 就绪时以 `0` 退出。

## 3. 配置 MCP 客户端

用 `mcp` 参数以 **stdio** 方式运行桥接程序。常见配置：

```json
{
  "mcpServers": {
    "rooqi": {
      "command": "/Applications/RooQi.app/Contents/Helpers/RooQiBridge.app/Contents/MacOS/rooqi",
      "args": ["mcp"]
    }
  }
}
```

配置文件位置取决于你使用的客户端。服务名称为 `RooQi`，版本 `0.1.0`，只提供工具（不提供 resources 或 prompts）。

## 4. 批准访问

访问按连接授予，在 RooQi 中完成：

1. 客户端调用某个 `rooqi_request_*_access` 工具，首次返回 `approvalRequired`，RooQi 显示原生窗口。
2. 在窗口中**选择一个项目**并批准。
3. 客户端再次调用同一工具，返回 `ready`。

| 权限 | 请求工具 | 批准窗口说明 |
|---|---|---|
| 读取 | `rooqi_request_read_access` | 只能读取所选项目内已有文稿的已保存文字，不能修改内容；不包含手写、图像或 PDF 原文。 |
| 创建与追加 | `rooqi_request_write_access` | 可新建最多 **10** 份文稿，并读取、追加项目内已有文稿及本次新建的文稿；不会替换旧正文。模型信息由外部请求方声明。 |
| PDF 批注 | `rooqi_request_pdf_annotation_access` | 读取范围内 PDF 的选区文字及页面几何，并新增高亮、下划线或评论；不能修改原 PDF、删除或改写已有批注，也不包含创建/追加权限。 |

每项授权 **15 分钟**有效，仅限本次连接。到期或连接断开后，尚未开始写入的请求会被拒绝；已经保存的结果保留。

## 排查

| 现象 | 检查 |
|---|---|
| `appUnavailable` | 在这台 Mac 上打开 RooQi。 |
| `transportUnavailable` | 在设置 › 外部连接中启用连接，并在登录项与扩展中允许后台服务。 |
| 反复 `approvalRequired` | 在 RooQi 中批准窗口后再次调用。CLI 最多等待 120 秒。 |
| `denied` | 请求在 RooQi 中被拒绝。新建连接后可再次请求。 |
| 更新或移动 RooQi 后 | 先点**关闭连接**，更新或移动 App，再重新**启用连接**。 |