rCodex

macOS guide

在 macOS 上部署

Gateway 通过 npm 安装，并使用当前用户的 LaunchAgent 常驻。Codex CLI、Xcode、签名环境和工作区都继续留在 Mac 上。

部署总览WindowsmacOSLinux
推荐终端Terminal 或 iTerm后台运行当前用户 LaunchAgent默认端口8787

01 / Prepare

检查 macOS 环境。

所有命令使用准备长期运行 Gateway 的 macOS 用户执行。

node --version
npm --version
codex --version
which codex
  • Node.js 需要 22 或更高版本。
  • Codex CLI 已在当前用户下登录。
  • 手机与 Mac 网络互通。
  • 已经确定允许访问的项目目录。

02 / Install

一条命令安装并启动 Gateway。

脚本会自动准备用户目录 Node.js 22、npm、Gateway 配置和 LaunchAgent。

1

执行安装脚本

curl -fsSL https://dl.rcodex.org/rcodex/install.sh | sh

安装到当前用户目录，不需要 Homebrew 或 sudo；已有配置和数据保持不变。

2

重新打开终端

首次安装后如果当前 Shell 还找不到命令，打开一个新终端再检查服务。

rcodex-gateway service status

03 / Configure

确认关键配置。

默认配置位于当前用户的 rCodex 目录。下面展示常见的工作区与端口设置。

GATEWAY_HOST=0.0.0.0
GATEWAY_PORT=8787
GATEWAY_ALLOWED_PATHS=/Users/你的用户名/Projects
GATEWAY_DATA_DIR=/Users/你的用户名/.rcodex/gateway/data
CODEX_COMMAND=codex

Homebrew 与 PATH

如果 LaunchAgent 找不到 Node.js 或 Codex，请确保配置使用可解析的绝对路径，尤其是 Apple Silicon 的 `/opt/homebrew/bin`。

原生开发工具

npm 原生运行可以继续使用 Mac 上已经安装的 Xcode、CocoaPods、签名证书和其他命令行工具。

04 / Service

安装当前用户 LaunchAgent。

Gateway 随用户登录启动，并继续使用该用户的 Codex 配置与工作区权限。

rcodex-gateway service install
rcodex-gateway service start
rcodex-gateway service status

常用服务命令

rcodex-gateway service restart
rcodex-gateway service stop
rcodex-gateway service uninstall
前台调试

需要查看即时日志时可以运行 `rcodex-gateway start`。关闭终端会停止前台进程，日常使用仍建议安装 LaunchAgent。

05 / Connect

让手机访问 Gateway。

1

查看局域网地址

Wi-Fi 通常使用 `en0`，其他网络接口可能不同。

ipconfig getifaddr en0
2

确认本机可以访问

curl http://127.0.0.1:8787/health
3

在 App 登录

使用 Gateway Console 二维码，或手动填写地址。

http://Mac局域网IP:8787

06 / Troubleshooting

macOS 常见问题。

终端可用，但 LaunchAgent 找不到命令

LaunchAgent 不一定继承交互式 Shell 的 PATH。将 Node.js 或 Codex 的绝对路径写入配置，并重启服务。

App 能登录但看不到目录

检查 `GATEWAY_ALLOWED_PATHS` 是否包含目标目录，并确认 macOS 隐私权限没有阻止当前进程访问。

手机无法访问 Mac

确认两台设备在可互访网络中，使用正确的局域网 IP，并检查 macOS 防火墙是否允许 Node.js 接收连接。

如何升级

执行 `rcodex-gateway service update`，命令会更新当前 npm 安装目录并刷新、重启和检查 LaunchAgent。