Codex WebUI

给 OpenAI Codex CLI 做的 Web 前端。把命令行交互搬到浏览器里，支持多线程并发、文件管理、终端、插件市场等。

后端用 NestJS 通过 stdio JSON-RPC 和 codex app-server 通信，前端 React + Vite，中间用 Socket.IO 实时推送。

English

功能

对话与线程

• 多线程并发运行，互不干扰
• 线程按工作区分组，支持归档、fork、回滚、重命名
• Markdown 渲染 + Shiki 代码高亮
• @ 引用文件、粘贴图片
• 追问（steer）和中断（stop）正在执行的 turn

审批流程

• 命令执行、文件变更的审批卡片，直接在页面上操作
• 支持安全策略切换（sandbox 级别）
• 多设备同时在线时的 CAS 防冲突

文件管理与预览

• 树形文件浏览器，支持拖拽移动
• Monaco Editor 代码编辑 + Git diff 分栏对比
• 文件预览：PDF、图片、视频、音频、字体、二进制（hex dump）
• 压缩包浏览：ZIP / TAR(.gz/.bz2/.xz) / RAR / 7z，无需解压即可预览内容
• Office 文档编辑：DOCX / XLSX / PPTX（通过 OnlyOffice Document Server，可选集成）
• 上传 / 下载 / 重命名 / 复制 / 移动 / 新建目录

终端

• 多 tab 共享终端（node-pty + xterm.js）
• 断线重连，输出不丢失
• headless VT 回放

集成与插件

其他

• JWT + API Key 认证
• 插件/MCP 服务器管理
• 深色/浅色主题，中英文切换
• 响应式布局，手机平板也能用
• Docker 一键部署

技术栈

浏览器
  React 19 · Vite 8 · TanStack (Router + Query + Virtual)
  Zustand · Socket.IO Client · Monaco Editor · xterm.js
  Tailwind CSS 4 · shadcn/ui · Framer Motion · dnd-kit
     ↕  REST + WebSocket
后端
  NestJS 11 · Fastify 5 · Socket.IO · node-pty
  SQLite (better-sqlite3 + Drizzle ORM) · Pino
     ↕  stdio JSON-RPC
  codex app-server（子进程）

快速开始

前置条件

• Node.js >= 20
• pnpm >= 9
• Codex CLI 已安装并可用

Docker 部署（推荐）

直接从 GHCR 拉取镜像，无需本地构建：

# 创建 .env
cat <<EOF > .env
WEBUI_API_KEY=your-secret-key
OPENAI_API_KEY=sk-xxx
EOF

# 启动（自动拉取多架构镜像）
docker compose up -d

或者手动运行：

docker run -d --name codex-webui \
  -p 8172:8172 \
  -e WEBUI_API_KEY=your-secret-key \
  -e OPENAI_API_KEY=sk-xxx \
  -v codex_root:/root \
  -v codex_workspaces:/workspaces \
  ghcr.io/limlll/codex-webui:latest

服务运行在 http://localhost:8172。

/root 卷持久化 codex/claude/MCP 配置及运行时工具链。首次启动自动释放内置 seed。

本地开发

git clone https://github.com/LimLLL/codex-webui.git
cd codex-webui
pnpm install

cp .env.example .env
# 编辑 .env，至少设置 WEBUI_API_KEY

# 启动后端（默认端口 8172）
pnpm start:dev

# 另一个终端，启动前端（端口 5173，自动代理到后端）
cd web && pnpm dev

打开 http://localhost:5173 即可使用。

环境变量

变量	必填	默认值	说明
WEBUI_API_KEY	是	—	登录密钥，同时用于派生 JWT 签名
PORT	否	8172	后端监听端口
OPENAI_API_KEY	否	—	Codex 使用 OpenAI API 时的密钥
CODEX_BIN	否	codex	codex CLI 可执行文件路径
CODEX_HOME	否	~/.codex	Codex 主目录
LOG_LEVEL	否	info	Pino 日志级别
WEBUI_DB_PATH	否	CODEX_HOME/codex-webui.sqlite	SQLite 数据库路径

Runtime Settings

security.workspaceRoots、files.uploadMaxBytes、terminal.defaultCwd、terminal.maxSessions、terminal.graceMs、terminal.scrollback 已迁入 SQLite runtime settings，可在 Settings 页面或 /api/settings 修改；同名历史环境变量仍作为 DB 未设置时的 fallback 生效。 Docker Compose 保留 WORKSPACE_ROOTS=/workspaces，用于首次启动时为挂载的 /workspaces 提供 bootstrap fallback。

项目结构

├── src/                  # NestJS 后端
│   ├── codex/            # 进程管理、JSON-RPC 客户端
│   ├── threads/          # 线程 CRUD、WebSocket 网关
│   ├── files/            # 文件操作、路径安全校验
│   ├── terminal/         # 多 tab 终端（node-pty）
│   ├── auth/             # JWT + API Key 认证
│   ├── database/         # SQLite + Drizzle ORM
│   └── ...               # 其他模块
├── web/                  # React 前端
│   └── src/
│       ├── routes/       # TanStack Router 页面
│       ├── components/   # UI 组件
│       ├── stores/       # Zustand 状态管理
│       ├── hooks/        # 自定义 hooks
│       └── generated/    # Hey API SDK（自动生成）
├── Dockerfile            # 多阶段构建 + seed root
└── docker-compose.yml

常用命令

pnpm start:dev          # 后端开发模式
pnpm build              # 编译后端
pnpm test               # 运行测试
pnpm lint               # ESLint 检查
pnpm db:generate        # 生成数据库迁移
pnpm db:migrate         # 执行迁移
cd web && pnpm dev      # 前端开发模式
cd web && pnpm build    # 前端构建（输出到 public/）

HTTPS / 反向代理

Codex WebUI 自身只监听 HTTP（默认 0.0.0.0:8172），生产环境建议用反向代理终止 HTTPS。

注意：WEBUI_API_KEY 在纯 HTTP 下明文传输，公网部署务必启用 HTTPS。

Nginx

server {
    listen 443 ssl http2;
    server_name codex.example.com;

    ssl_certificate     /etc/ssl/certs/codex.pem;
    ssl_certificate_key /etc/ssl/private/codex.key;

    client_max_body_size 200m;  # 匹配文件上传限制

    location / {
        proxy_pass http://127.0.0.1:8172;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;
    }

    # Socket.IO WebSocket 升级
    location /socket.io/ {
        proxy_pass http://127.0.0.1:8172;
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_read_timeout 300s;
    }
}

server {
    listen 80;
    server_name codex.example.com;
    return 301 https://$host$request_uri;
}

Docker Compose 中使用时，proxy_pass 改为 http://codex-webui:8172，并将 ports 改为 expose。

Caddy

Caddy 自动签发 Let's Encrypt 证书，自动处理 WebSocket 升级：

codex.example.com {
    reverse_proxy 127.0.0.1:8172
}

OnlyOffice 注意事项

反向代理下 OnlyOffice 需要知道公开 URL 才能回调保存。代理正确传递 X-Forwarded-Proto / X-Forwarded-Host 即可自动检测；也可在 Settings → General 显式设置 general.publicBaseUrl。

License

AGPL-3.0