rCodex

Windows guide

在 Windows 上部署

Gateway 通过 npm 安装，并以当前用户的计划任务常驻。这样它可以读取同一用户的 Codex 登录态和工作区权限。

部署总览WindowsmacOSLinux
推荐终端PowerShell后台运行当前用户计划任务默认端口8787

01 / Prepare

检查 Windows 环境。

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

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

02 / Install

安装并初始化 Gateway。

1

安装 npm 包

npm install -g @rcodex-lab/gateway
2

确认命令位置

如果 PowerShell 找不到命令，先查看 npm 全局目录。

npm config get prefix
Get-Command rcodex-gateway
3

生成配置

rcodex-gateway setup

初始化结果包含管理员密码和访问 token，请不要公开分享。

PATH 提示

常见 npm 全局命令目录是 `%APPDATA%\npm`。加入用户 PATH 后，需要重新打开 PowerShell。

03 / Configure

确认关键配置。

`gateway.env` 由 setup 生成。下面只展示最常用的路径与端口项。

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

找不到 Codex

把 `CODEX_COMMAND` 改为 `codex.exe` 的绝对路径。可以先用 `Get-Command codex` 查询。

目录无法访问

确保 `GATEWAY_ALLOWED_PATHS` 包含目标项目，并且当前用户拥有目录权限。

04 / Service

安装当前用户后台服务。

Windows 使用当前用户计划任务，在用户登录后自动启动 Gateway。

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

常用服务命令

rcodex-gateway service restart
rcodex-gateway service stop
rcodex-gateway service uninstall
为什么不是系统服务

使用当前用户计划任务可以继续读取该用户自己的 Codex 配置和登录态，避免切换到其他系统账号后丢失环境。新版启动器以无窗口方式托管 Gateway 和 Codex 进程，不会弹出 CMD 窗口，也不需要管理员权限。

05 / Connect

让手机访问 Gateway。

1

查看局域网地址

ipconfig

找到当前网络适配器的 IPv4 地址。

2

必要时放行端口

使用管理员 PowerShell 创建 TCP 8787 入站规则。

New-NetFirewallRule -DisplayName "rCodex Gateway" -Direction Inbound -Protocol TCP -LocalPort 8787 -Action Allow
3

在 App 登录

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

http://Windows局域网IP:8787

06 / Troubleshooting

Windows 常见问题。

安装成功但命令不存在

将 `npm config get prefix` 对应的全局目录加入用户 PATH，重新打开 PowerShell。

服务已启动，但读取不到 Codex 登录态

确认安装服务、登录 Codex 和运行 Gateway 使用的是同一个 Windows 用户。

本机能打开，手机打不开

确认使用的是 IPv4 局域网地址，并检查 Windows 防火墙、访客网络隔离和路由器 AP 隔离。

如何升级

执行 `rcodex-gateway service update`，命令会更新当前 npm 安装目录、覆盖计划任务定义、重启并检查服务状态。