从安装，到第一次调用。

开始之前

• 首版目标为 Apple Silicon Mac、macOS 13 或更新版本；最终支持范围以发行说明和安装验收为准。
• 应用包含运行时和连接器，不需要 Node、Xcode 或源码。
• 要从 Codex 对话调用，需事先安装并登录 Codex CLI；当前配置步骤仍需要 Terminal。
• 设备连接无需邀请码。一次性 Agent 配对码用于把客户端连到指定 Agent。

1. 安装并连接此 Mac

1. 从下载页取得测试版 DMG，核对版本、架构与校验和，将 Isometry 拖入 Applications。
2. 从 Applications 打开应用。若提示无法验证开发者或 Apple 无法检查软件，先关闭提示，再进入“系统设置 → 隐私与安全”，找到 Isometry 的拦截提示，由你本人选择“仍要打开”并确认。仅在确认下载来自本站且校验和一致时操作；公司管理的 Mac 可能不允许放行。若提示恶意软件或文件损坏，请停止并联系支持，不要关闭系统防护或运行删除隔离属性的命令。
3. 应用打开后，在设备连接区域连接此 Mac，等待云端显示已连接、Agent 授权已同步。测试者不需要 Relay 管理员令牌。
4. 需要关闭界面后继续运行时，在应用内启用“登录后运行”；若系统要求，到后台项目设置中确认。

安装包可用于真实服务调用，但测试版不保证在所有 Mac 环境中可用。安装说明参考 Apple 官方安全打开应用说明。

Mac 只向云端发起 HTTPS 连接，不需要配置公网端口。关闭界面与退出后台是不同操作；睡眠或离线时不保证任务能够执行。

2. 连接真实服务

进入“密钥保险库”，在“服务目录”点击 Gmail，或搜索 Gmail 后打开服务详情，再点击“连接 Gmail”。在 Google 页面核对账号、Isometry 名称和只读范围，完成授权后回到应用等待连接出现。不要把密码、验证码、OAuth JSON 或 token 发到聊天。

Gmail 只读范围允许读取数据，不允许发送、修改或删除邮件。先从邮箱概况读取开始验证连接；可用操作以应用实际显示为准，每个 Agent 都需单独获准使用该连接；Key 授权涵盖本版本支持的能力，资源范围由服务端凭据决定。

服务详情可搜索操作并展开输入参数定义。“目录可见”“本机可执行”“已实测”分别表示不同状态。其他服务的配置可能只支持本机加密保存，未验证、未开放执行；保存配置不会自动增加 Agent 权限。OAuth 方式未开放时，界面会说明原因。

Cloudflare DNS 只需在 App 内输入用户 API Token，不需要再填 Zone、域名或子域。保存后点击“去授权 Agent”，勾选这个 Key，再配对 Codex。Token 决定可访问资源；若 Token 允许，Agent 也能创建、修改或删除 DNS，请先在 Cloudflare 限制 Token 权限。App 不会把 Token 交给 Agent。下载域名已通过这条真实链路完成配置。

也可以先用不需要凭据的 Hacker News 公开只读操作熟悉授权流程。它不能替代 Gmail 的真实授权验收。

3. 给两个 Agent 分配不同权限

1. 进入“Agent 授权”，创建 A，只勾选指定 Gmail 连接；授权前核对该连接可用的读取能力。
2. 创建 B，只勾选 Hacker News 连接。不选择 Gmail。
3. 核对各自卡片上的 Key／连接和授权版本。旧版部分授权会保留，只有明确点击“按 Key 重新授权”才扩大。空选择意味着零权限，连接成功不会自动授权给 Agent。
4. 在“连接测试”选择对应 Agent 和获准 Action。A 的 profile 输入为 {}；B 的公开条目示例为 {"id":8863}。

第一版按 Key／连接授权，无需逐个选择 Action。一个 Agent 获准读取 Gmail，不代表另一个也有权访问；通用 HTTP 不能绕过逐 Action 检查。

4. 配对 Codex

1. 在目标 Agent 卡片生成远程配对码，核对 Agent 名称。码十分钟有效，只能使用一次。
2. 点击“复制 Codex 接入命令”，在 Terminal 粘贴并运行。命令引用已安装 App 的接入脚本，不应包含配对码或 token。
3. 回到应用复制配对码，在终端的隐藏输入中粘贴并回车。不要把码放进聊天、命令参数或共享文档。
4. 完成后，远程客户端凭据保存在本机 Keychain。重启 Codex 会话以加载 MCP 配置。
5. 先让 B 搜索可用 Action、查看输入说明、读取一次公开 HN 条目，再查询该次执行。A 只进行你明确授权的读取。

同一 Codex 配置中可有多个 Agent 对应的 MCP server，请明确选择正确的 server。对话中写一个 Agent 名称，本身不会改变权限。当前自动接入脚本面向同一台 Mac 的 Codex CLI；其他电脑的凭据安装尚没有完整桌面引导。

5. 查看结果和调用日志

概览统计整个选定时间范围的账本。加载完成前显示进度，不把尚未读取的数据当作零次执行。“已保存连接”只表示本机配置数量，不代表凭据已验证或该服务已完成真实验收。“Agent 已实际调用”来自真实派发并收到 2xx 响应的执行记录；仍需查看提供商业务结果。连接卡片的“调用日志”会直接筛选该 Key。日志可按 Agent、连接、执行状态、Relay 回执和时间筛选；搜索执行 ID，展开查看摘要、授权版本和时间线。“导出当前页摘要”只导出当前一页。

本机收到响应

Mac 收到目标服务或连接器的 HTTP 响应。仍需看 HTTP 来源和业务结果，不表示 Agent 已读取。

Relay 已确认接收

云端接收了结果；不等于客户端已经读取，也不覆盖本机原有的未知结果。

结果或回执未知

先查询原执行、核对目标服务。系统不自动重发操作或完整响应；同一执行有两种未知状态时，待核对只计一次。

已拒绝

可能是本机外发前拒绝，或已同步的云端拒绝。来源在记录中说明；拒绝尝试不等于一次 Mac 已接受执行。

Relay execution ID 与 Mac execution ID 是两套标识。联系支持只提供必要的脱敏 ID 和错误，不附上邮件内容或凭据。

6. 断开连接或撤销 Agent

只停止某个 Agent：在“Agent 授权”撤销它，或取消它使用某个 Key 的权限。后续派发重新检查权限，已经外发的操作无法保证撤回。

停用整个服务连接：在“密钥保险库”点击对应连接的“断开连接”，核对影响后确认。应用先收回全部相关 Agent 权限，再移除本机当前凭据。清理失败时仍阻止旧连接，按提示重试；重新连接不会自动恢复旧权限。

Google 账号侧撤销是另一项操作：使用应用中的第三方访问管理入口，在 Google 账号中移除 Isometry。它可能影响同一 Google 账号的其他 Isometry 连接。本机断开不会自动清除历史日志、备份或客户端已有副本。详见隐私与数据处理说明。

7. 删除此设备的云端数据

1. 进入“设备状态”，展开“管理此设备的云端数据”，阅读范围后点击删除并确认。
2. 应用先暂停云端任务，再请求删除。若提示待确认或身份清理未完成，保持钥匙串可用并按界面重试；不要通过重新启用云端来绕过待确认状态。
3. 确认完成后，旧云端身份及其远程配对凭据退役。需要继续使用时重新连接此 Mac，并为客户端重新配对。

此操作会移除此设备在 Relay 的活动元数据，保留防止旧身份复活的最少安全记录。它不会清除本机服务连接、Agent、日志、备份或客户端已有副本，也不会替你撤销 Google 授权。请按实际目的分别处理这些数据；不确定时先联系支持，勿发送凭据。

遇到问题

等待本机后台

确认钥匙串已解锁，检查系统后台项目，然后在应用内重试启动。不要删除数据库或重新生成主密钥。

在线但无法执行

核对保险库、网络和授权同步；有网络路径不代表 Relay 必然可达。锁屏、睡眠或会话未激活时会暂停新执行。

配对码过期或已使用

在目标 Agent 重新生成。已有 Codex 会话需重启加载配置；移动 App 后先重开应用，让它检查托管 helper 路径。

需要支持

联系 winless@bbd.sh，提供 App 版本、macOS 版本、错误及必要的脱敏执行 ID。不要发送密码、provider key、Agent token 或私人邮件。