Remodex

关注 X

通过你的 iPhone 控制 Codex。Remodex 是一款本地优先的开源桥接工具及 iOS 应用，它将 Codex 运行时保留在你的 Mac 上，并允许你的手机通过配对的安全会话进行连接。

应用核心功能

• iPhone 与 Mac 之间的端到端加密配对和聊天
• 快速模式以降低回合延迟
• 计划模式用于在执行前进行结构化规划
• 使用 /subagents 命令从 iPhone 创建子代理
• 在不重新开始的情况下引导正在进行的运行
• 在当前回合仍在运行时排队后续提示
• 回合结束或需要关注时的应用内通知
• 通过手机执行 Git 操作，包括提交、推送、拉取和分支切换
• 推理控制以调整 Codex 的思考程度
• 访问控制，支持按需访问或完全访问
• 可从相机或相册添加照片附件
• 一次性 QR 码引导，配合受信任的 Mac 自动重连
• 仅限 macOS 的后台桥接服务，通过 launchd 实现
• 在 Codex 于 Mac 上运行时，手机可进行实时流式传输
• 与 Mac 上的 Codex 共享线程历史记录

该仓库坚持本地优先和自托管友好原则：iOS 应用源码未嵌入公共托管端点，传输层对任何希望自行搭建环境的人都可检查。

目前，后台守护进程/受信任自动重连流程仅适用于 macOS。其他操作系统上的自托管中继设置仍然有效，但它们目前使用前台桥接流程，而非 macOS 的 launchd 服务路径。

如需清晰了解公开仓库的分发模式，请阅读 SELF_HOSTING_MODEL.md。

该项目尚处于非常早期阶段，可能存在诸多 bug。

我目前暂不接受贡献。若您仍希望提供帮助，请先阅读 CONTRIBUTING.md。

获取应用

该应用已在 App Store 上架。

你可以在 Xcode 中从源码构建 iOS 应用，将自己签名的版本安装到设备上，然后使用应用内的引导流程，扫描 remodex up 生成的 QR 码完成配对。

若在安装应用之前，使用普通相机或 QR 读取器扫描配对 QR 码，设备可能会将 QR 负载视为纯文本，并打开网页搜索，而非执行配对操作。

架构设计

┌──────────────┐       配对会话   ┌───────────────┐       stdin/stdout       ┌─────────────┐
│  Remodex iOS │ ◄────────────────────► │ remodex (Mac) │ ◄──────────────────────► │ codex       │
│  应用         │    WebSocket 桥接    │ 桥接          │    JSON-RPC              │ 应用服务器  │
└──────────────┘                        └───────────────┘                          └─────────────┘
                                               │                                         │
                                               │  AppleScript 路由反弹                │ JSONL 展示
                                               ▼                                         ▼
                                        ┌─────────────┐                           ┌─────────────┐
                                        │  Codex.app  │ ◄─── 从磁盘读取 ──────── │  ~/.codex/  │
                                        │  (桌面)  │      导航时的数据文件     │  会话数据   │
                                        └─────────────┘                           └─────────────┘

1. 在你的 Mac 上运行 remodex up
2. 在 macOS 上，Remodex 会安装并启动一个轻量级的后台桥接服务，并打印出用于首次配对或恢复的 QR 码。
3. 使用 Remodex iOS 应用扫描一次该 QR 码，以信任该 Mac。
4. 完成首次握手后，iPhone 可通过配置的中继解析 Mac 的实时会话，并自动重新连接。
5. 你的手机通过桥接向 Codex 发送指令，并实时接收响应。
6. 桥接负责处理 Git 操作以及在 Mac 上的本地会话持久化。
7. Codex.app 可以从磁盘读取相同的线程历史记录，但除非启用可选的刷新 workaround，否则它并非真正的实时镜像。

仓库结构

本仓库包含本地桥接、iOS 应用目标及其测试：

├── phodex-bridge/                # `remodex` 使用的 Node.js 桥接包
│   ├── bin/                      # CLI 入口
│   └── src/                      # 桥接运行时、Git/工作区处理器、刷新辅助工具
├── CodexMobile/                  # Xcode 项目根目录
│   ├── CodexMobile/              # 应用源码目标
│   │   ├── Services/             # 连接、同步、事件接收、Git 和持久化逻辑
│   │   ├── Views/                # SwiftUI 界面及时间线/侧边栏组件
│   │   ├── Models/               # RPC、线程、消息和 UI 模型
│   │   └── Assets.xcassets/      # 应用图标和 UI 资源
│   ├── CodexMobileTests/         # 单元测试
│   ├── CodexMobileUITests/       # UI 测试
│   └── BuildSupport/             # Info.plist、xcconfig 默认值及本地覆盖模板

先决条件

• Node.js v18+
• 已安装并位于 PATH 中的 Codex CLI
• Codex 桌面应用（可选——用于在 Mac 上查看线程）
• 在扫描配对 QR 码之前，已将签名的 Remodex iOS 版本安装到你的 iPhone 或 iPad 上
• macOS（用于桌面刷新功能——核心桥接可在任何操作系统上运行）
• Xcode 16+（仅当你需要从源码构建 iOS 应用时）

安装桥接

_{请使用 @latest 从 npm 安装，以获得最新的桥接修复。}

如果你计划使用 macOS 菜单栏伴侣程序，remodex 必须全局安装，并且在你的登录 shell 的 PATH 中可用。

npm install -g remodex@latest

若要更新现有的全局安装：

npm install -g remodex@latest

如果你想简单试用 Remodex，可以直接从 npm 安装并运行，无需克隆此仓库。

快速入门

安装桥接后，运行以下命令：

remodex up

首次连接时，打开 Remodex 应用，按照引导流程操作，然后扫描应用内部显示的 QR 码。

首次扫描之后：

• iPhone 会将 Mac 保存为受信任的设备
• Mac 上的桥接会将自身身份本地保存
• 应用会在后续启动时自动尝试受信任的重连
• QR 码仍将作为恢复路径，以防信任关系发生变化或中继无法解析实时会话。

目前，基于守护进程的受信任重连路径仅适用于 macOS。如果你在 Linux 或 Windows 上进行自托管，配对仍然有效，但桥接将在前台运行，除非你设置自己的特定于操作系统的服务封装。

本地运行

git clone https://github.com/Emanuele-web04/remodex.git
cd remodex
./run-local-remodex.sh

该启动脚本会启动一个本地中继服务，将桥接指向 ws://<your-host>:9000/relay，并打印用于 iPhone 应用配对的二维码。

对于 iPhone 的自托管场景，推荐使用 Tailscale 或其他稳定的私有网络。虽然在同一 Wi‑Fi 下通过 ws://<lan-ip> 进行局域网配对仍可用于本地测试，但在某些 iOS 设备上，即使中继和 Wi‑Fi 状态良好，这种方式也可能不够稳定。

选项：

• ./run-local-remodex.sh --hostname <lan-hostname-or-ip>
• ./run-local-remodex.sh --bind-host 127.0.0.1 --port 9100

如果您的 iPhone 是通过局域网配对，请确保使用的主机名或 IP 地址是手机能够实际访问到的。

自定义中继端点

有关完整的公开自托管教程，请参阅 Docs/self-hosting.md。

如果您希望 npm 桥接指向您自己的部署而非包的默认设置，可以显式覆盖 REMODEX_RELAY：

REMODEX_RELAY="ws://localhost:9000/relay" remodex up

对于自托管的 iPhone 使用场景，建议使用可通过 Tailscale 或其他稳定私有网络访问的中继 URL。请将普通的本地 ws://192.168.x.x 配对视为一种尽力而为的方式，而不是 iOS 生产环境中的推荐路径。

常见的私有部署方案如下：

1. 在您的 Mac、小型服务器或您控制的 VPS 上运行中继服务。
2. 将该机器接入 Tailscale 网络。
3. 设置 REMODEX_RELAY 为 Tailscale 可访问的 ws:// 或 wss:// 中继 URL。
4. 使用二维码完成首次配对。
5. 之后让 iPhone 通过该中继重新连接到同一台受信任的 Mac。

如果该中继前端连接的是 Mac 桥接，macOS 守护进程可以保持桥接持续运行，实现无感重连。若您自托管非 macOS 平台的桥接，同样可以使用上述中继路径，但目前尚未内置自动后台服务管理功能。

反向代理子路径同样适用，因此位于 Traefik 后端的托管中继可以与其他 API 共享同一域名：

REMODEX_RELAY="wss://api.example.com/remodex/relay" remodex up

在这种配置下，公共端点可能如下所示：

• wss://api.example.com/remodex/relay
• https://api.example.com/remodex/v1/push/session/register-device
• https://api.example.com/remodex/v1/push/session/notify-completion

请确保代理在转发请求前移除 /remodex 路径，以便中继仍然能够接收 /relay/... 和 /v1/push/... 请求。

如果您将 REMODEX_RELAY 指向您自己的自托管中继，则托管推送功能将不会启用，除非您同时在桥接上设置 REMODEX_PUSH_SERVICE_URL，并在中继上明确开启推送服务。

发布到 npm

已发布的 npm 包可以在打包时通过 prepack 脚本嵌入默认的私有中继配置。

当前包版本为 1.3.4。

要将桥接发布并以 api.phodex.app 作为默认中继：

cd phodex-bridge
npm login
REMODEX_PACKAGE_DEFAULT_RELAY_URL="wss://api.phodex.app/relay" \
npm publish

发布后，用户仍可在运行时通过 REMODEX_RELAY 覆盖打包时的默认值。

您也可以直接从源代码运行桥接：

cd phodex-bridge
npm install
REMODEX_RELAY="ws://localhost:9000/relay" npm start

命令

remodex up

启动 Remodex。

在 macOS 上，remodex up 是后台桥接服务的友好入口：

• 写入 launchd 服务所需的守护进程配置文件。
• 启动或重启后台桥接服务。
• 等待配对载荷并打印用于首次信任或恢复的二维码。
• 即使您随后关闭终端，桥接也会保持运行。

在非 macOS 平台上，remodex up 会在前台运行桥接。

无论在哪种平台上，桥接都会：

• 启动 codex app-server（或连接到现有端点）。
• 将 Mac 桥接连接到配置的中继。
• 双向转发 JSON-RPC 消息。
• 处理来自手机的 Git 命令。
• 保存当前线程状态，以便后续恢复。

remodex start

仅限 macOS。启动后台桥接服务，但不在当前终端等待或打印二维码。若服务已加载，则会就地刷新。

remodex restart

仅限 macOS。显式重启后台桥接服务，不等待或打印二维码。

remodex stop

仅限 macOS。停止后台桥接服务，并清除其临时运行状态。

remodex status

仅限 macOS。打印当前 launchd / 桥接的状态，包括服务是否已加载以及是否存在最近的配对载荷。

remodex run-service

仅限 macOS。由 launchd 使用的内部服务入口点。通常无需手动运行此命令。

remodex --version

打印已安装的 Remodex CLI 版本。

remodex --version
# => 1.3.4

remodex reset-pairing

清除已保存的桥接配对状态，以便下次受信任的连接需要重新进行 QR 引导。 对于本地状态损坏的情况，您通常不再需要此操作：近期的 Remodex 版本会在启动时自动修复无法读取的配对文件或镜像。

remodex reset-pairing
# => [remodex] 已清除已保存的配对状态。请运行 `remodex up` 以再次配对。

remodex resume

在您的 Mac 上重新打开 Codex.app 中的上一个活动线程。

remodex resume
# => [remodex] 已打开上一个活动线程：abc-123（手机）

remodex watch [threadId]

实时跟踪某个线程的事件日志。

remodex watch
# => [14:32:01] 手机：“修复 auth.ts 中的登录 bug。”
# => [14:32:05] Codex：“我来检查 auth.ts 并修复登录问题……”
# => [14:32:18] 任务开始。
# => [14:33:42] 任务完成。

环境变量

REMODEX_RELAY 是可选的，但其默认值取决于您获取 Remodex 的方式：

• 公开的 GitHub 仓库或源码检出保持开源且便于自托管，因此不会内置托管中继。
• 官方发布的软件包在发布时可能会包含一个默认中继。
• 如果您是从源码运行，请假设应使用 ./run-local-remodex.sh 或自行设置 REMODEX_RELAY。

变量	默认值	描述
REMODEX_RELAY	源码检出时为空；已发布软件包中可选	用于 QR 启动、可信会话解析以及手机/Mac 会话路由的会话基础 URL
REMODEX_PUSH_SERVICE_URL	默认禁用	用于托管推送注册/完成的可选 HTTP 基础 URL
REMODEX_CODEX_ENDPOINT	—	连接到现有的 Codex WebSocket，而不是启动本地的 codex app-server
REMODEX_REFRESH_ENABLED	false	当检测到手机活动时自动刷新 Codex.app（设置为 true 则显式启用）
REMODEX_REFRESH_DEBOUNCE_MS	1200	用于合并刷新事件的防抖窗口（毫秒）
REMODEX_REFRESH_COMMAND	—	替换内置 AppleScript 刷新的自定义 Shell 命令
REMODEX_CODEX_BUNDLE_ID	com.openai.codex	Codex 应用程序的 macOS 包 ID
CODEX_HOME	~/.codex	Codex 数据目录（此处用于存储 sessions/ 部署文件）

# 显式启用桌面刷新
REMODEX_REFRESH_ENABLED=true remodex up

# 连接到现有的 Codex 实例
REMODEX_CODEX_ENDPOINT=ws://localhost:8080 remodex up

# 使用自定义的自托管中继端点（`ws://` 未加密）
REMODEX_RELAY="ws://localhost:9000/relay" remodex up

# 仅当您的自托管中继也暴露了配置好的 APNs 推送服务时，才启用托管推送
REMODEX_RELAY="wss://relay.example/relay" \
REMODEX_PUSH_SERVICE_URL="https://relay.example" \
remodex up

在中继/VPS 侧，应将推送功能保持禁用，直到您真正需要它为止。HTTP 推送端点默认关闭，只有在您设置 REMODEX_ENABLE_PUSH_SERVICE=true 时才会开启。

配对与安全性

• Remodex 是“本地优先”：Codex、Git 操作和工作区操作都在您的 Mac 上执行，而 iPhone 则作为配对的远程控制设备。
• 在 iPhone 上，最可靠的自托管设置是通过 Tailscale 可达的中继。在同一 Wi‑Fi 网络上使用 ws:// 进行普通局域网配对，在某些 iOS 设备上可能会失败，因为应用程序的本地网络路由并不总是可靠。
• 配对二维码携带连接 URL、会话 ID 以及用于启动端到端加密的桥接身份密钥。首次成功扫描后，iPhone 会在 Keychain 中存储一条受信任的 Mac 记录，而桥接则会在 Mac 本地持久化其受信任的手机身份。
• 在 macOS 上，桥接可以作为轻量级的 launchd 服务持续运行，这样手机就可以解析 Mac 当前的实时中继会话，并在无需每次重新扫描二维码的情况下重新连接。
• 当信任关系发生变化、桥接身份轮换或中继无法解析当前的实时会话时，二维码仍然是恢复路径。
• 桥接状态以规范形式存储在 ~/.remodex/device-state.json 中，权限仅限于本地访问。在 macOS 上，桥接还会将该状态镜像到 Keychain，作为尽力而为的备份/迁移数据；最近的版本会在启动时自动修复无法读取的本地状态，而无需手动清理。
• CLI 不再在二维码下方以明文打印连接 URL。
• 仅在您希望自托管或针对自己的部署进行本地测试时，才设置 REMODEX_RELAY。
• 对于直接安装或自托管安装，请保持 REMODEX_TRUST_PROXY 未设置。仅当受信任的反向代理（如 Traefik、Nginx 或 Caddy）正在转发中继流量时，才将其打开。
• 传输实现公开在 relay/ 目录中，但您实际部署的主机名和凭据应保持私密。
• 在 iPhone 上，默认的代理权限模式是“按需”。将应用切换为“完全访问”会自动批准代理发出的运行时授权提示。

安全与隐私

Remodex 现在在配对的 iPhone 和您 Mac 上运行的桥接之间使用经过身份验证的端到端加密通道。传输层仍然承载 WebSocket 流量，但在安全会话建立后，它将不再获取提示、工具调用、Codex 响应、Git 输出或工作区 RPC 负载的明文内容。

安全通道的构建步骤如下：

1. 桥接在 Mac 上生成并持久化一对长期使用的设备身份密钥。
2. 配对二维码共享连接 URL、会话 ID、桥接设备 ID、桥接身份公钥以及一个短期的有效期窗口。
3. 在配对过程中，iPhone 和桥接交换新的 X25519 临时密钥和随机数。
4. 桥接使用其 Ed25519 身份密钥对握手记录进行签名，iPhone 则使用来自二维码或先前受信任的 Mac 记录的公钥验证该签名。
5. iPhone 使用其自身的 Ed25519 身份密钥对客户端认证记录进行签名，桥接在接受会话之前会验证该签名。
6. 双方使用 HKDF-SHA256 导出方向性的 AES-256-GCM 密钥，然后使用带有单调计数器的加密信封封装应用消息，以防止重放攻击。

隐私注意事项：

• 传输层仍然可以看到连接元数据以及用于建立加密会话的明文安全控制消息，包括会话 ID、设备 ID、公钥、随机数和握手结果代码。
• 在安全握手成功之后，传输层将看不到解密后的应用负载。
• 重新扫描二维码可以自动替换先前受信任的 iPhone。请仅在您有意手动清除记忆中的配对状态时，才使用 remodex reset-pairing。
• 在 iPhone 上，设备端的消息历史也会使用基于 Keychain 的 AES 密钥进行静态加密。

Git 集成

桥接会拦截来自手机的 git/* JSON-RPC 调用，并在本地执行它们：

命令	描述
git/status	分支、跟踪信息、脏状态、文件列表和差异
git/commit	提交暂存的更改，可选附带提交信息
git/push	推送到远程仓库
git/pull	从远程仓库拉取（遇到冲突时自动中止）
git/branches	列出所有分支，并标记当前/默认分支
git/checkout	切换分支
git/createBranch	创建并切换到新分支
git/log	最近的提交历史
git/stash	暂存工作中的更改
git/stashPop	弹出最新的暂存内容
git/resetToRemote	硬重置到远程仓库（需要确认）
git/remoteUrl	获取远程仓库的 URL 以及所有者/仓库名称

工作区集成

该桥接还处理助手回滚流程中的本地工作区范围内的回滚操作：

命令	描述
workspace/revertPatchPreview	检查是否可以在本地仓库中干净地应用反向补丁
workspace/revertPatchApply	在预览成功时，在本地应用反向补丁

Codex 桌面应用集成

Remodex 同时支持 Codex CLI 和 Codex 桌面应用 (Codex.app)。在底层，该桥接会启动一个 codex app-server 进程——这与驱动桌面应用和 IDE 扩展的相同 JSON-RPC 接口。对话会以 JSONL 格式的回滚文件保存在 ~/.codex/sessions 目录下，因此您在手机上开始的对话线程也会出现在桌面应用中。

目前实时功能包括：

• 当桥接会话保持连接时，iPhone 上的对话是实时的。
• Mac 端的 Codex 运行时才是实际执行任务的运行时。

目前尚未完全实现实时功能的是：

• 默认情况下，Codex.app 不会作为第二个实时订阅者来订阅当前的活跃会话。
• 桌面应用会从持久化的会话文件中同步数据，并可通过下面的可选刷新 workaround 来手动触发更新。
• 目前 Codex.app 的 GUI 尚不支持真正的手机到桌面的实时同步。

为了使这一限制更加实用，Remodex 还在 iPhone 应用中提供了一个“移交至 Mac”按钮。当您准备切换设备时，该按钮可以将当前聊天明确地继续在您的 Mac 上，并在 Codex.app 中打开相应的对话线程。

已知限制：当外部 app-server 进程向磁盘写入新数据时，Codex 桌面应用不会实时重新加载。您在手机上创建或更新的对话线程，只有在桌面应用重新挂载该路由后才会显示出来。出于当前深度链接跳转仍会造成干扰的考虑，Remodex 目前默认关闭了桌面刷新功能。如果您仍然希望使用旧的重新挂载 workaround，也可以手动启用它。

# 手动启用旧的深度链接刷新 workaround
REMODEX_REFRESH_ENABLED=true remodex up

这会触发一个防抖后的深度链接跳转（codex://settings → codex://threads/<id>），强制桌面应用重新挂载当前的对话线程，而不会中断任何正在运行的任务。在一轮对话进行中，Remodex 还会监控该线程的持久化回滚文件，并定期进行限流刷新，以便长响应能够在不完全重启应用的情况下在 Mac 上可见。如果本地桌面路径不可用，桥接会在该次运行剩余时间内自动禁用桌面刷新功能，而不是一直无休止地尝试重连。

连接韧性

• 自动重连：如果会话连接断开，桥接会以指数退避策略重新连接（1 秒 → 最大 5 秒）。
• 安全追加：桥接会维护一个有限的本地出站缓冲区，并在安全重连后重新发送丢失的加密消息。
• Codex 持久化：在当前桥接运行期间，Codex 进程会持续存活，即使会话短暂断开也能自动重连。
• 优雅关闭：SIGINT/SIGTERM 会干净地关闭所有连接。

构建 iOS 应用

cd CodexMobile
open CodexMobile.xcodeproj

使用 Xcode 在物理设备或模拟器上构建并运行。该应用使用 SwiftUI，当前项目目标为 iOS 18.6。

贡献

我目前暂不接受贡献。详情请参阅 CONTRIBUTING.md。

常见问题解答

我需要 OpenAI API 密钥吗？ 不需要用于 Remodex 本身。您只需要独立设置并运行 Codex CLI 即可。

这能在 Linux/Windows 上运行吗？ 核心桥接客户端（Codex 转发 + git）可在任何操作系统上运行。但桌面刷新功能（AppleScript）仅适用于 macOS，内置守护进程和可信自动重连服务路径目前也仅限于 macOS。

如果我关闭终端会发生什么？ 在 macOS 上，桥接可以通过 launchd 在后台持续运行，因此关闭终端并不会停止可信重连路径。而在其他操作系统上，前台运行的桥接会在终端关闭时停止。

如何强制进行新的 QR 配对？ 运行 remodex reset-pairing，然后再次使用 remodex up 启动桥接。您只需在有意更换配对的 iPhone 或清除已记住的配对信息时才需要执行此操作。

我可以连接到远程 Codex 实例吗？ 可以——设置 REMODEX_CODEX_ENDPOINT=ws://host:port 即可跳过本地 codex app-server 的启动。

为什么我的手机对话线程不会立即显示在 Codex 桌面应用中？ 桌面应用是从磁盘读取会话数据的（~/.codex/sessions），但它不会在外部进程写入新数据时实时重新加载。您的手机仍然能接收到实时流；只是桌面 GUI 会滞后，除非您手动启用 REMODEX_REFRESH_ENABLED=true 的刷新 workaround。

Remodex 是否支持手机与 Codex.app 之间的真正实时同步？ 不。手机会话是实时的，但 Codex.app 的 GUI 并不是当前活跃会话的真实实时镜像。为此，iPhone 应用中提供了一个“移交至 Mac 应用”按钮，方便您明确地在 Mac 上继续同一对话线程。

我可以自托管中继服务吗？ 可以。这是预期的分叉路径。传输和推送服务的代码位于 relay/ 目录下；您可以将 REMODEX_RELAY 指向您运行的实例。

我可以使用 Tailscale 吗？ 可以。它是推荐的私有网络选项，适合在 iPhone 上进行自托管。将您的中继服务部署在可通过 Tailscale 访问的位置，设置 REMODEX_RELAY 为该中继 URL，通过 QR 码完成一次配对，然后让应用通过同一中继服务与受信任的 Mac 自动重连。

传输层对于敏感工作安全吗？ 它比纯文本代理要安全得多：流量可在传输过程中使用 TLS 加密保护，应用负载在安全握手之后会进行端到端加密，而所有的 Codex 执行仍然发生在您的 Mac 上。不过，传输层仍可能观察到连接元数据和握手控制消息，因此最严格的信任模式是自行运行该服务。

许可证

ISC

Remodex 快速上手指南

Remodex 是一个开源的本地优先桥接工具，允许你通过 iPhone 安全地控制运行在 Mac 上的 OpenAI Codex。它支持端到端加密、Git 操作、子代理调用以及实时流式输出，让移动端编码体验如同本地一般流畅。

环境准备

在开始之前，请确保满足以下系统和软件要求：

• 操作系统：
  • Mac 端：macOS（推荐，支持后台守护进程和自动重连）。Linux/Windows 也可运行桥接服务，但需前台运行且无后台守护支持。
  • 移动端：iPhone 或 iPad (iOS)。
• 核心依赖：
  • Node.js: 版本 v18 或更高。
  • Codex CLI: 必须安装并配置到环境变量 PATH 中。
  • Codex Desktop App (可选): 用于在 Mac 上查看会话历史。
• 开发构建（仅当需要从源码编译 iOS 应用时）：
  • Xcode 16+
  • 有效的 Apple 开发者签名证书（用于真机调试）

注意：目前官方未提供中国镜像源。如遇网络问题，建议配置稳定的全局代理或使用 Tailscale 等内网穿透工具进行连接。

安装步骤

1. 安装 Mac 端桥接服务

通过 npm 全局安装最新的 remodex 包：

npm install -g remodex@latest

如需更新现有版本，再次运行上述命令即可。

2. 安装 iOS 客户端

你有两种选择：

• 方式 A（推荐）：从 App Store 下载 直接在 App Store 搜索 "Remodex" 或访问链接下载安装。

• 方式 B：从源码构建（需签名） 如果你需要自定义功能或测试最新代码：

  git clone https://github.com/Emanuele-web04/remodex.git
  cd remodex
  # 使用 Xcode 打开 CodexMobile/CodexMobile.xcodeproj
  # 配置 Signing & Capabilities，选择你的团队 ID
  # 编译并部署到设备
  

基本使用

第一步：启动 Mac 端服务

在终端运行以下命令启动桥接服务。在 macOS 上，这将注册一个后台守护进程（launchd），即使关闭终端服务也会继续运行：

remodex up

运行后，终端会打印出一个 QR 二维码。

第二步：配对设备

1. 打开 iPhone 上的 Remodex App。
2. 跟随应用内的引导流程，使用应用内的扫描器扫描 Mac 终端上显示的 QR 码。
   • 警告：请勿使用系统自带相机或其他通用扫码工具扫描，否则可能无法触发配对协议。
3. 扫描成功后，iPhone 将该 Mac 标记为受信任设备。

第三步：开始使用

配对完成后，你就可以在 iPhone 上：

• 向 Codex 发送指令并实时查看代码生成流。
• 使用 /subagents 命令调用子代理。
• 执行 Git 操作（commit, push, pull, 切换分支等）。
• 上传照片作为上下文附件。
• 调整推理强度（Reasoning controls）。

后续打开 App 时，它将尝试通过配置的 Relay 自动重连到受信任的 Mac，无需再次扫码（除非信任状态变更）。

进阶：自托管与局域网连接

如果你希望在非公网环境或特定网络下使用（例如通过 Tailscale 组网）：

1. 确保手机和 Mac 在同一稳定网络或通过 Tailscale 互通。
2. 指定 Relay 地址启动服务：

   REMODEX_RELAY="ws://<你的局域网 IP 或 Tailscale IP>:9000/relay" remodex up
   

3. 在 App 中扫描新生成的二维码进行配对。

提示：在 iOS 设备上，纯局域网 (ws://192.168.x.x) 连接有时不稳定，强烈建议使用 Tailscale 等工具提供稳定的私有网络连接。