rCodex

Linux guide

在 Linux 上部署

Gateway 通过 npm 安装，并使用当前用户的 systemd 服务常驻。适合 Ubuntu 工作站、个人开发主机和持续在线的个人服务器。

部署总览WindowsmacOSLinux
推荐终端Bash 或 Zsh后台运行user-level systemd默认端口8787

01 / Prepare

检查 Linux 环境。

所有命令使用准备长期运行 Gateway 的普通用户执行，不要切换到 root 安装后再由其他用户启动。

node --version
npm --version
codex --version
systemctl --user --version
  • Node.js 需要 22 或更高版本；脚本自动安装官方 Node.js 时要求 glibc 2.28 及以上。
  • Codex CLI 已在当前用户下登录。
  • 当前用户可以正常执行 `systemctl --user`。
  • 手机或公网入口能够访问这台 Linux 主机。
  • 已经确定允许访问的项目目录。

02 / Install

一条命令安装并启动 Gateway。

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

1

执行安装脚本

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

全程使用当前普通用户，不需要 sudo；重复执行不会覆盖已有 Gateway 配置和数据。

2

重新打开终端

首次安装后如果当前 Shell 还找不到命令，重新登录或打开一个新终端。

rcodex-gateway service status

03 / Configure

确认关键配置。

下面展示个人 Linux 主机常用的工作区与端口设置。

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

Shell 可用，服务不可用

systemd 用户服务不会完整继承交互式 Shell 环境。必要时把 `CODEX_COMMAND` 写成 `command -v codex` 返回的绝对路径。

目录权限

确保运行 Gateway 的用户可以读取允许目录，并对需要 Codex 修改的工作区拥有写入权限。

04 / Service

安装当前用户 systemd 服务。

Gateway 使用 user-level systemd，保持当前用户的 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
退出登录后继续运行

持续在线的个人服务器可以执行 `sudo loginctl enable-linger "$USER"`，让用户服务在未登录时也能启动。只在确实需要常驻时开启。

05 / Connect

让手机访问 Gateway。

1

查看主机地址

hostname -I

局域网使用时选择手机能够访问的地址。

2

确认本机服务

curl http://127.0.0.1:8787/health
3

必要时放行端口

使用 UFW 的系统可以放行 TCP 8787；其他系统按实际防火墙配置。

sudo ufw allow 8787/tcp
4

在 App 登录

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

http://Linux主机IP:8787
公网访问

不要把无 TLS 的 8787 端口直接暴露到公网。需要远程访问时，请配置可信反向代理、HTTPS 和明确的访问控制。

06 / Troubleshooting

Linux 常见问题。

SSH 断开后 Gateway 停止

确认已经安装并启动 user-level systemd 服务。无人登录时仍需运行的服务器，再检查 linger 是否开启。

终端能找到 Codex，服务找不到

把 `CODEX_COMMAND` 改为 Codex 的绝对路径，然后执行 `rcodex-gateway service restart`。

App 能登录但项目目录不可用

检查允许目录、Linux 文件权限和实际运行 Gateway 的系统用户。

系统提示 glibc 版本过低

官方 Node.js 22 Linux 包要求 glibc 2.28 及以上。建议升级操作系统；也可以先自行准备能正常运行的 Node.js 22，再重新执行安装脚本。

systemd 用户服务不可用

确认系统支持 user-level systemd，并请管理员启用当前用户的 user manager；无人登录也需运行时，再开启 linger。

如何升级

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