DarwinRelay

将 ChatGPT 变成你 Mac 上的本地代理。

DarwinRelay 是一个源码优先的 macOS MCP 运行时，为 ChatGPT 和其他 MCP 客户端提供对你日常使用的 Mac 的结构化访问：shell 和文件、真实 PTY、长时间运行的任务、后台 Chrome、原生桌面控制，以及持久化的 Codex 历史记录。

把 ChatGPT 本身当作一个本地编码代理来使用：让它检查代码仓库、复现故障、修改代码、运行测试，并在你的机器上验证结果——无需在对话与 macOS 之间再插入另一个编码模型。

[!CAUTION] DarwinRelay 有意设计为功能强大。它不是沙箱，也不实现文件系统或 shell 命令白名单。已连接的客户端可以以运行桥接进程的 macOS 用户的有效权限执行操作。在连接客户端或将运行时暴露到 localhost 之外之前，请阅读 SECURITY.md。

将 ChatGPT 用作本地代理

一个典型的开发任务可以这样简单地开始：

Use DarwinRelay and work on ~/Projects/myapp.

Find why authentication is failing. Reproduce the problem, fix the underlying
cause, run the relevant tests, and verify the result locally.

当 ChatGPT 暴露 DarwinRelay 的完整工具面时，同一个对话就可以将任务贯穿整个本地闭环：

understand → inspect → reproduce → modify → execute → verify → iterate

DarwinRelay 不要求使用 Codex 来完成该工作流。ChatGPT 是推理客户端；DarwinRelay 是你 Mac 上的执行运行时。

ChatGPT 可用性

ChatGPT 的自定义 MCP 可用性由 OpenAI 控制，并且可以独立于 DarwinRelay 发生变化。套餐、工作区、发布和 UI 行为可能与当前文档不同，因此请以你账户中显示的工具面为准，确定该 ChatGPT 会话可以使用哪些功能。设置连接时，请参阅当前的 OpenAI 开发者模式和 MCP 应用文档。

DarwinRelay 本身保持 MCP 客户端中立，也可以被其他支持所需 MCP 工具面的客户端使用。

这里所说的"本地代理"描述的是工作流，而不是 ChatGPT 单独的 Agent 模式产品功能。OpenAI 目前表示 Agent 模式不使用自定义应用；请在普通的 ChatGPT 对话中选中自定义应用后使用 DarwinRelay。

Related MCP server: OmniCommanderMCP

它能做什么？

• Shell 和文件 — 运行命令、检查或修改文件、应用补丁，以及管理本地进程。

• 真实 PTY — 交互式 shell、REPL、SSH、sudo 提示符、TUI 和长时间运行的终端程序。

• 任务与进程生命周期 — 启动超出单次工具调用的工作，稍后检查它，并在关闭时回收它。

• 原生计算机使用 — 语义化 Accessibility 查询/操作、窗口、对话框、文件面板、截图、OCR、键盘/鼠标回退，以及视觉等待。

• 后台浏览器自动化 — 一个专用的 Chrome 配置文件和扩展拥有的标签页池，可以导航、检查、填写和点击，而不会频繁抢占焦点。

• Codex 历史 — 读取持久化的 Codex 线程，而无需恢复它们或启动另一个模型轮次。

• 经过认证的 MCP 传输 — 本地使用 stdio，或在你控制的隧道后面使用附带的 HTTP/OAuth 前端。

• 故障关闭生命周期控制 — 显式全访问解锁、审计元数据、进程回收、单例菜单所有权，以及支持回滚的应用更新。

开发者工作流

第一个有用的 DarwinRelay 工作流不应需要浏览器自动化、原生 UI 权限或 Codex 历史。

ChatGPT
  ↓
DarwinRelay
  ↓
local repository
  ↓
read files / run commands / edit code / run tests
  ↓
verify the result on the same Mac

一旦核心编码闭环正常工作，仅在任务需要时才添加能力：

• 为交互式调试器、REPL、SSH 会话或 TUI 使用 PTY；

• 为 Web 工作流使用后台 Chrome；

• 当 ChatGPT 需要操作真实的 macOS 应用时，授予原生桌面权限；

• 当你希望 ChatGPT 检查或继续之前的 Codex 工作时，使用 Codex 历史。

参见 examples/README.md 获取可直接复制粘贴的工作流。

超越编码

DarwinRelay 可以在一个执行闭环中组合本地代码、进程、浏览器状态和原生 macOS UI。例如，一个桌面应用调试任务可以如下所示：

launch the app
→ reproduce the issue through the real UI
→ inspect logs and code
→ fix the implementation
→ restart the app
→ repeat the UI flow
→ verify the fix

原生桌面层优先使用 Accessibility，并在需要时回退到 ScreenCaptureKit/Vision 和合成输入。浏览器层默认使用专用的本地 Chrome 配置文件，而不是静默接管你的日常配置文件。

已经在使用 Codex？

DarwinRelay 可以读取持久化的 Codex 历史，而无需启动另一个 Codex 模型轮次。这使得 Codex 成为一个有用的连续性来源，而不是必需的中间环节：

Find the latest Codex thread for this project.
Summarize the objective, branch, changed files, current errors, and unfinished step.
Then inspect the live repository and continue the work from ChatGPT.

快速开始

DarwinRelay 目前是源码优先 / 自行构建的。GitHub Releases 不提供预构建的 .app 或 .dmg，当前产品模式也不需要付费的 Apple Developer Program 会员资格。

1. 系统要求

核心自构建：

• macOS 13 或更高版本；

• Node.js 18 或更高版本（CI 中使用 Node.js 22）；

• 用于菜单应用和原生辅助程序的 Xcode Command Line Tools / swiftc。

要通过菜单应用的 HTTP/Server URL 路径使用 ChatGPT，还需安装 cloudflared，并确保它在你的登录 shell PATH 中可用。

可选能力：

• Accessibility、屏幕录制和输入/发布事件权限 — 仅用于原生桌面控制；

• 完全磁盘访问 — 仅当任务需要访问 macOS 受保护的文件系统位置时；

• Google Chrome — 仅用于受管理的 chrome_* 后台工作区；

• Codex CLI/历史 — 仅用于 codex_thread_* 连续性工具。

2. 选择安装路径

选项 A — 使用本地编码代理安装

已经在使用 Codex、Claude Code 或其他具有 shell/文件系统访问权限的本地编码代理？让它为你执行自构建：

Install DarwinRelay on this Mac from:
https://github.com/dcierra/darwinrelay

Read AGENTS.md and the installation documentation first.

Install or verify the required dependencies, then build and install DarwinRelay
using the documented source-first/self-build path. Configure everything that
can be configured without weakening the project's security model.

Do not bypass macOS security controls. Do not use my personal Chrome profile.

When macOS requires Accessibility, Screen Recording, Input/Post Events, Full
Disk Access, Keychain access, or another user-consent step, stop and tell me
exactly what I need to approve manually.

After installation, verify that DarwinRelay starts correctly and report what
remains to connect it to my MCP client.

代理应遵循仓库而不是猜测。如果此路径暴露了模糊的依赖、构建步骤或权限交接问题，那是 DarwinRelay 脚本/文档中需要修复的上车缺陷，而不是用更长的提示词来掩盖的问题。

选项 B — 手动安装

git clone https://github.com/dcierra/darwinrelay.git
cd darwinrelay
npm run check
./menubar/build.sh
open /Applications/DarwinRelay.app

构建脚本会在可能的情况下将本地构建的菜单应用安装到 /Applications（回退到 ~/Applications）。请保留 DarwinRelay 检出目录在原位： 自构建应用有意从该源码包解析其运行时。

构建在可用时使用持久的本地代码签名身份，否则回退到临时签名。临时构建无需付费的 Apple Developer 会员资格即可工作，但 macOS TCC 授权在重新构建后可能需要重新授予，因为指定要求可能会改变。

要进行无安装副作用的编译/签名冒烟测试，请使用：

DARWINRELAY_APP_OUTPUT=/tmp/DarwinRelay.app ./menubar/build.sh --build-only

更新 DarwinRelay

./scripts/update.sh 从 DarwinRelay v0.6.5 开始包含。如果现有安装位于 v0.6.4 或更早版本，请使用上述安装步骤执行最后一次源码优先的手动升级/重装到 v0.6.5；从 v0.6.5 开始，使用更新程序进行版本间更新。

从 DarwinRelay v0.6.9 开始，菜单栏还提供 Update DarwinRelay…。它会要求显式确认，在独立的 Terminal 窗口中打开相同的规范更新程序，并在应用重启时显示进度。没有静默或自动更新路径。

你可以直接从普通的本地 Terminal/iTerm 会话（或另一个独立的本地 shell）运行相同的更新程序，而不是通过即将重启的 DarwinRelay MCP 连接：

cd /path/to/darwinrelay
./scripts/update.sh

这将更新到最新的稳定版 vMAJOR.MINOR.PATCH 版本。要选择特定的已发布版本：

./scripts/update.sh v0.6.5

更新程序将 Git 检出和 /Applications/DarwinRelay.app 视为一个事务。它验证规范的 GitHub 源，要求干净的检出并固定到精确的稳定版本标签，检查源码完整性，拒绝移动的标签和降级，以相同的签名身份原子安装新应用，刷新自动启动，故障关闭重启，并要求真实的 MCP 医生返回 CORE VERDICT: READY。如果激活失败，它会尝试恢复之前的检出和保留的回滚应用。

它刻意不使用 git pull、git reset --hard 或删除本地工作。脏的/开发检出会被拒绝；请将开发更改保留在另一个分支/worktree 中，而不是将生产安装用作编码检出。

由于后台 Chrome 扩展是从此检出以未打包方式加载的，更改其 manifest/源码的版本可能需要从 Chrome 扩展页面在专用的 DarwinRelay 配置文件中手动执行一次 Reload。更新程序会在扩展版本更改时报告此情况；切勿替换为个人配置文件。

对于项目维护者，更新程序/生命周期更改还有额外的预发布门禁：在创建公开标签之前，确切的未标记候选版本会在真实 Mac 上使用 scripts/test-update-candidate.sh 进行测试。这刻意与面向用户的更新程序分开，因此任意提交永远不会成为正常的更新目标。

3. 连接 ChatGPT

打开 DR 菜单栏项目并按下 Start。当 MCP 传输运行时，选择 Copy ChatGPT Setup 并按照 docs/CHATGPT.md 操作。

第一个编码工作流不需要 Chrome、Codex 历史、Accessibility、屏幕录制或输入权限。当任务实际需要时再配置这些。

4. 在修改任何内容之前先验证

从只读检查开始：

Use DarwinRelay. Call bridge_status first.
Then list ~/Projects/myapp and read its top-level README/package metadata.
Do not modify files or run shell commands yet.

然后，如果 ChatGPT 在你的账户中暴露了 DarwinRelay 的写入/执行工具，请尝试真实工作流：

Use DarwinRelay and work on ~/Projects/myapp.
Run the test suite, find one failing test, fix the underlying issue, rerun the
relevant tests, and verify the result. Do not deploy or force-push anything.

故障排除时，运行：

./scripts/doctor.sh

医生现在会给出阻塞性的 Core / MCP 编码路径判定，与可选的本地桌面、受保护文件系统、后台 Chrome 和 Codex 能力分开。它对所选传输执行真实的本地 initialize → bridge_status 冒烟检查，并为阻塞性失败打印下一步操作。更深入的生命周期/浏览器诊断继续在路线图中演进。

仅源码的本地 MCP 使用

对于可以连接到本地 stdio 服务器的 MCP 客户端，桥接也可以直接运行而无需菜单应用。必须显式确认完全访问：

export DARWINRELAY_FULL_ACCESS_ACK=I_UNDERSTAND_THIS_GRANTS_FULL_ACCESS
node bridge.mjs

默认运行时状态：

~/Library/Application Support/DarwinRelay
~/Library/Logs/DarwinRelay

使用 DARWINRELAY_DATA_DIR、DARWINRELAY_LOG_DIR、DARWINRELAY_SHELL 和 DARWINRELAY_AUDIT_MODE 等环境变量来隔离开发/测试实例。

工作原理

flowchart LR
    A[MCP client] --> B[DarwinRelay bridge]
    B --> C[Shell / filesystem / jobs]
    B --> D[PTY helper]
    B --> E[Codex persisted history]
    B --> F[MacUIHelper]
    F --> G[Accessibility / ScreenCaptureKit / Vision / CGEvent]
    B --> H[Chrome native host]
    H --> I[DarwinRelay Chrome extension]
    I --> J[Background DR tab pool]

原生桌面辅助程序刻意设计为短生命周期，而不是特权守护进程。菜单应用、MacUIHelper 和虚拟光标使用稳定的代码签名标识，以便在存在持久签名身份时，macOS TCC 授权能够在正常重新构建后存活。

参见 docs/ARCHITECTURE.md 了解组件、数据流和信任边界。

面向 AI 和编码代理

此仓库有意包含面向代理的文档。如果你将仓库交给 Codex、Claude、ChatGPT 或其他编码代理，请首先指向 AGENTS.md。它描述了仓库地图、不变量、开发命令、测试期望、签名/浏览器规则和发布约束。

对于操作已安装的 DarwinRelay 运行时而非修改源码的代理，请使用 docs/AGENT_OPERATIONS.md。它包含完整的工具族地图、首选决策顺序、常见失败状态和安全运行时工作流。

原生桌面控制

DarwinRelay 优先使用语义化 Accessibility 操作，并将视觉/原始输入作为回退。核心能力包括：

• ui_observe、ui_tree、ui_ax_query、ui_ax_at；

• 带指纹的 AX 引用，并具备过期引用检测；

• ui_action、ui_wait_for、ui_assert；

• ui_app_*、ui_window_*、对话框和文件面板；

• ScreenCaptureKit 截图和 Vision OCR；

• 在 macOS 支持的情况下，针对后台 PID 的输入注入，附带语义验证和有界的前台回退；

• ui_sequence，用于确定性的多步骤原生操作突发；

• 一个可点击穿透的虚拟 AI 光标，不会移动物理指针。

控制模型和限制请参阅 docs/DESKTOP_CONTROL.md。

后台 Chrome 工作区

DarwinRelay 使用一个未打包的 Chrome 扩展加 Native Messaging。公共扩展身份是稳定的；预期的扩展 id 是：

pfhahlehpahegefejooendokpkklgmgd

安装程序默认创建或复用名为 DarwinRelay 的已退出登录的本地 Chrome 配置文件。这使代理的浏览状态与日常 Google 配置文件保持分离：

# Recommended/default: dedicated local profile named DarwinRelay
./scripts/install-background-chrome.sh

# Explicit alternatives only when you want them
./scripts/install-background-chrome.sh --profile 'Some Existing Profile'
./scripts/install-background-chrome.sh --use-current-profile

如果 DarwinRelay 配置文件尚不存在，请在运行安装程序前先退出 Chrome 一次，这样 Chrome 就不会并发重写其 Local State；配置文件存在后，正常的重新安装可以在 Chrome 打开时运行。卸载 DarwinRelay 时有意保留该配置文件，因为浏览器配置文件内容属于用户数据。

然后，仅在所选配置文件中，打开 chrome://extensions，启用开发者模式，选择 Load unpacked，并选择本仓库的 chrome-extension/ 目录。你可以向安装程序传递 --open 来完成这一一次性设置步骤。

该扩展拥有一个名为 DR 的 Chrome 原生标签组。常规的 chrome_open 调用会租用预先创建的空闲标签，而不是创建任意的前台标签。chrome_close 会将工作区标签归还到池中。

浏览器安全模型

宽松审批是默认设置。通过配置的 chrome_* 工作区进行的常规 HTTP/HTTPS 工作不需要按站点授予终端权限。在菜单应用中启用 Strict approvals 会恢复限定范围的 URL 授权和一次性应用范围的原生变更审批。

通过 shell/AppleScript/JXA 直接进行 Chrome 自动化仍被桥接层阻止，因此常规网页工作保持在受管的后台路径上。当浏览器/操作系统安全界面确实需要时，独立的原生 ui_* 接口仍可与前台 Chrome UI 交互。

一个可选的原始 Browser Harness/CDP 适配器位于 DARWINRELAY_ADVANCED_BROWSER=1 之后。它默认禁用，并在 Strict approvals 下默认失败关闭，因为任意 CDP 无法被合理地归约为 URL 范围。

HTTP / OAuth 传输

mcp-http.mjs 绑定到 loopback，并支持 MCP HTTP 传输，带有静态 bearer token 以及远程 MCP 客户端使用的 OAuth 2.1 流程。Cloudflare 等隧道可以将 loopback 服务通过 HTTPS 发布。

菜单应用是常规 ChatGPT Server URL 路径的首选入口。DEPLOY.md 记录了手动/高级传输设置，包括从上游项目保留的 OpenAI Secure MCP Tunnel 路径。

在未阅读 SECURITY.md 中的远程访问威胁模型之前，不要暴露 HTTP 端点。该前端接受的凭据最终会以你的桌面用户身份门控本地代码执行。

开发

npm run check
npm run test:core
npm run test:desktop
npm run test:lifecycle
# or all groups
npm test

公共 CI 有意暴露单独的检查，而不是一个不透明的 test 任务：

• 静态检查 — 语法/原生构建验证和全历史 gitleaks 扫描；

• 核心与协议测试 — MCP、HTTP/OAuth、PTY、federation、浏览器和对抗性测试；

• 桌面控制测试 — 确定性桌面协议测试加原生 fixture 编译；

• 安装与生命周期测试 — 安装程序、自启动、单例所有权、回滚和卸载行为。

真实的可变 AppKit E2E 需要一台已登录且具有 TCC 权限的 Mac，因此它不被视为在一次性 GitHub 托管的 GUI 会话上可靠。维护者可以在本地运行它：

DARWINRELAY_RUN_NATIVE_DESKTOP_E2E=1 node tests/desktop-control-native.mjs

在提交 pull request 之前，请参阅 CONTRIBUTING.md。当前的开发优先级记录在 ROADMAP.md 中。

安全

重要的边界很简单：DarwinRelay 拥有运行它的 macOS 账户的权限。 诸如解锁文件、Strict approvals、审计元数据、OAuth、后台浏览器路由和进程回收等安全功能可以减少意外或远程滥用；它们不会将任意 shell 访问变成沙箱。

安全报告应使用 GitHub 的私有漏洞报告，而不是公开 issue。请参阅 SECURITY.md。

项目谱系

DarwinRelay 是独立维护的，并且与 Alexander Rådahl Benz 的 Mac Developer Bridge 有显著分歧。继承的上游历史被有意保留，原始 MIT 版权声明保留在 LICENSE 中。确切的谱系和署名政策请参阅 UPSTREAM.md。

公共的 dcierra/darwinrelay 仓库是规范的开发源。开发/发布模型请参阅 docs/DEVELOPMENT_MODEL.md。

DarwinRelay 与 OpenAI、Apple、Google、Cloudflare 或上游维护者没有任何关联或背书关系。

许可证

MIT。请参阅 LICENSE 和 UPSTREAM.md。