安装、连接与授权

1. 启用外部连接

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

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

2. 找到桥接程序

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

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

可以添加别名：

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

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

3. 配置 MCP 客户端

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

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

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

4. 批准访问

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

客户端调用某个 rooqi_request_*_access 工具，首次返回 approvalRequired，RooQi 显示原生窗口。
在窗口中选择一个项目并批准。
客户端再次调用同一工具，返回 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，再重新启用连接。

安装、连接与授权

#1. 启用外部连接

#2. 找到桥接程序

#3. 配置 MCP 客户端

#4. 批准访问

#排查

1. 启用外部连接

2. 找到桥接程序

3. 配置 MCP 客户端

4. 批准访问

排查