rCodex | Docker 新手部署

YOU WILL GET

完成后你会得到什么

一个运行中的 Gateway 容器、一个持久化数据目录 `gateway-data/`，以及一个可以被 Android App 用 `http://服务器IP:8787` 登录的远程开发入口。

默认端口 `8787`

推荐镜像 `rcodexlab/rcodex-gateway:latest`

推荐策略 直接使用 `latest` 获取当前稳定 Gateway，后续升级时重新 pull 镜像即可。

QUICK START

最小步骤

STEP 1

检查 Docker 和 Codex 登录态

执行 `docker version`、`docker compose version`、`codex --version`、`ls ~/.codex`。

STEP 2

准备工作区

例如创建 `/data`，并保证宿主机用户对它有读写权限。

STEP 3

创建部署目录

例如 `~/rcodex-deploy`，其中包含 `docker-compose.yml`、`.env` 和 `gateway-data/`。

STEP 4

修改 `.env`

重点改 Codex 登录态路径、工作区路径、账号密码和 `GATEWAY_AUTH_TOKEN`。

STEP 5

启动 Gateway

执行 `docker compose pull` 和 `docker compose up -d`。

STEP 6

验证并登录 App

确认 `/healthz` 和 `/rcodex/version.json` 可访问，然后在手机 App 里登录。

FILES

先创建这几个文件和目录

下面给出的是可以直接复制的最小部署目录。你只需要把其中的用户名、工作区路径、账号密码和 token 换成自己的值。

目录结构

rcodex-deploy/
├── .env
├── docker-compose.yml
└── gateway-data/

创建命令

mkdir -p ~/rcodex-deploy/gateway-data
cd ~/rcodex-deploy
touch .env docker-compose.yml

.ENV

完整 `.env` 文件内容

# Gateway 镜像。官网部署默认跟随当前稳定版 latest。
RCODEX_GATEWAY_IMAGE=rcodexlab/rcodex-gateway:latest
RCODEX_CONTAINER_NAME=rcodex-gateway

# 宿主机登录态目录。必须换成你机器上真实存在的绝对路径。
RCODEX_CODEX_HOME_HOST_PATH=/home/你的用户名/.codex
RCODEX_CLAUDE_HOME_HOST_PATH=/home/你的用户名/.claude

# 宿主机工作区和容器内工作区。Linux 新手建议先保持 `/data`。
RCODEX_WORKSPACE_HOST_PATH=/data
RCODEX_WORKSPACE_CONTAINER_PATH=/data
RCODEX_GATEWAY_DATA_HOST_PATH=./gateway-data

# Gateway 基础配置。
GATEWAY_PORT=8787
GATEWAY_NAME=rcodex-gateway
GATEWAY_VERSION=latest
GATEWAY_ALLOWED_PATHS=/data
GATEWAY_UPDATE_MANIFEST_URL=http://code.rcodex.org/rcodex/version.json
CODEX_APP_SERVER_PORT=8899

# App 模型选择列表。留空也可以，Gateway 会尝试读取服务器 Codex 实际可用模型。
CODEX_AVAILABLE_MODELS=

# Claude Code 默认关闭；确认宿主机 Claude 可用后再打开。
GATEWAY_ENABLE_CLAUDE_CODE=false
CLAUDE_COMMAND=claude
CLAUDE_DEFAULT_MODEL=
CLAUDE_AVAILABLE_MODELS=
CLAUDE_PERMISSION_MODE=default
CLAUDE_AUTO_APPROVE=false

# 登录认证。请务必改成自己的账号、强密码和长随机 token。
GATEWAY_AUTH_USERNAME=你的登录账号
GATEWAY_AUTH_PASSWORD=你的登录密码
GATEWAY_AUTH_TOKEN=换成一串很长的随机字符串

COMPOSE

完整 `docker-compose.yml` 文件内容

services:
  gateway:
    image: ${RCODEX_GATEWAY_IMAGE}
    container_name: ${RCODEX_CONTAINER_NAME}
    restart: unless-stopped
    ports:
      - "${GATEWAY_PORT}:${GATEWAY_PORT}"
    environment:
      GATEWAY_HOST: 0.0.0.0
      GATEWAY_PORT: ${GATEWAY_PORT}
      GATEWAY_NAME: ${GATEWAY_NAME}
      GATEWAY_VERSION: ${GATEWAY_VERSION}
      GATEWAY_DATA_DIR: /app/data
      GATEWAY_ALLOWED_PATHS: ${GATEWAY_ALLOWED_PATHS}
      GATEWAY_UPDATE_MANIFEST_URL: ${GATEWAY_UPDATE_MANIFEST_URL}
      GATEWAY_AUTH_USERNAME: ${GATEWAY_AUTH_USERNAME}
      GATEWAY_AUTH_PASSWORD: ${GATEWAY_AUTH_PASSWORD}
      GATEWAY_AUTH_TOKEN: ${GATEWAY_AUTH_TOKEN}
      CODEX_COMMAND: codex
      CODEX_APP_SERVER_PORT: ${CODEX_APP_SERVER_PORT}
      CODEX_AVAILABLE_MODELS: ${CODEX_AVAILABLE_MODELS}
      GATEWAY_ENABLE_CLAUDE_CODE: ${GATEWAY_ENABLE_CLAUDE_CODE}
      CLAUDE_COMMAND: ${CLAUDE_COMMAND}
      CLAUDE_HOME: /root/.claude
      CLAUDE_DEFAULT_MODEL: ${CLAUDE_DEFAULT_MODEL}
      CLAUDE_AVAILABLE_MODELS: ${CLAUDE_AVAILABLE_MODELS}
      CLAUDE_PERMISSION_MODE: ${CLAUDE_PERMISSION_MODE}
      CLAUDE_AUTO_APPROVE: ${CLAUDE_AUTO_APPROVE}
    volumes:
      - ${RCODEX_GATEWAY_DATA_HOST_PATH}:/app/data
      - ${RCODEX_CODEX_HOME_HOST_PATH}:/root/.codex
      - ${RCODEX_CLAUDE_HOME_HOST_PATH}:/root/.claude
      - ${RCODEX_WORKSPACE_HOST_PATH}:${RCODEX_WORKSPACE_CONTAINER_PATH}
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:${GATEWAY_PORT}/healthz"]
      interval: 15s
      timeout: 5s
      retries: 5

COMMON ERRORS

新手最容易犯的几个错误

工作区宿主机路径与容器路径混淆

App 里看到的是容器内路径，不是宿主机路径。

容器路径没有使用绝对路径

`RCODEX_WORKSPACE_CONTAINER_PATH` 和 `GATEWAY_ALLOWED_PATHS` 必须写成 `/data`、`/workspace` 这种绝对路径，不要写 `./data`。

Codex 没登录但以为是 Gateway 故障

很多“会话创建失败”其实都是宿主机 `.codex` 没挂对或没登录。