Codex Web

v1.0.0-alpha — 自托管的 Codex 网页版：给 Codex CLI / app-server 套一个零依赖的 Web 界面，支持多模型提供商、文件上传、项目（工作区）管理、内置资源管理器与快速预览。

Codex Web 在服务器上启动官方 codex app-server（stdio JSON-RPC，稳定通道），再把协议桥接成浏览器可用的 HTTP + SSE。所有模型调用都发生在你自己的服务器上，会话、上传文件、项目文件都在你控制的目录里。

功能

网页聊天界面：流式回复、Markdown 渲染（代码块带复制按钮）、推理过程折叠、工具活动卡片；
多提供商切换：OpenAI / DeepSeek / 自定义（Base URL + API Key + 模型名），部署时可用环境变量配置，也可启动后在页面「设置」里配置/切换；
权限快速切换：完全访问 / 工作区写入 / 只读（对应桌面端逻辑，随会话记忆）；
项目（工作区）= 文件夹聚合会话：新建项目自动建目录，侧栏空项目也可见；会话历史按项目分组、可搜索、可归档/重命名/批量删除；
文件上传：一键上传到当前项目 .codex-uploads/<时间戳>/，图片以 localImage 交给支持视觉的模型；
资源管理器：右侧抽屉浏览/下载项目文件，md / 代码 / json / 图片 / PDF 快速预览；
亮暗主题切换（Apple 风格设计参考），默认跟随系统偏好；
账号无关：配置的是你自己的 API Key，不需要 ChatGPT 登录。

快速开始（Docker）

方式一：官方镜像快速部署（推荐 · 适合 NAS / 新手）

不需要克隆源码、不需要本地构建，只要服务器能 docker pull 就行。

在任意目录新建 docker-compose.yml，内容如下：

services:
  codex-web:
    image: byversion/codex-web:1.0.0-alpha
    container_name: codex-web
    ports:
      - "10020:13020"
    environment:
      CODEX_WEB_HOST: "0.0.0.0"
      CODEX_WEB_PORT: "13020"
      CODEX_PROJECTS_ROOT: "/workspace"
      CODEX_DEFAULT_CWD: "/workspace"
      # 可选：部署时直接填好提供商配置；留空也可，稍后在页面「设置」里填
      CODEX_PROVIDER: "deepseek"
      CODEX_BASE_URL: "https://api.deepseek.com/"
      CODEX_API_KEY: "sk-..."
      CODEX_MODEL: "deepseek-v4-flash"
    volumes:
      - codex-home:/home/codex/.codex   # codex 配置 / 会话历史
      - ./workspace:/workspace          # 项目（工作区）文件
    restart: unless-stopped

volumes:
  codex-home:

启动：
```
docker compose up -d
```
打开 http://<NAS IP>:10020。
- 如果你在 docker-compose.yml 里填了环境变量，启动即可用；
- 没填的话：左下角 ⚙ 设置 → 模型提供商，选 OpenAI / DeepSeek / 自定义，填 Base URL、API Key、模型名，点「保存并应用」，无需重启容器。

以后升级镜像：docker compose pull && docker compose up -d。

方式二：本地构建（开发者）

从源码构建，适合想改代码、调试，或网络环境访问不了 Docker Hub 的场景。

git clone https://github.com/by-2020-github/codex-web-nas.git codex-web
cd codex-web
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

构建不需要访问 chatgpt.com / releases.openai.com——Codex CLI 安装包已内置在 vendor/codex/（见下文「离线安装包」）。改完代码后重新执行上面同一条命令即可重建。

离线安装包（内置）

仓库 vendor/codex/ 已内置 Codex CLI v0.149.0 的 Linux 安装包（x86_64 / ARM64 各一份）、沙箱组件 bwrap 与 Code Mode 宿主进程 codex-code-mode-host，并附 SHA-256 校验和：

vendor/codex/
├── CHECKSUMS.txt
├── codex-x86_64-unknown-linux-musl.tar.gz      # ~95 MB
├── codex-aarch64-unknown-linux-musl.tar.gz     # ~88 MB
├── bwrap-x86_64-unknown-linux-musl.tar.gz
├── bwrap-aarch64-unknown-linux-musl.tar.gz
├── codex-code-mode-host-x86_64-unknown-linux-musl.tar.gz   # ~20 MB
└── codex-code-mode-host-aarch64-unknown-linux-musl.tar.gz  # ~19 MB

Dockerfile 按目标架构自动选用对应安装包（以构建容器内 uname -m 为准），构建时先用 CHECKSUMS.txt 校验完整性，全程不访问外网；
非 Docker 的 Linux 主机部署可直接离线安装：
```
bash scripts/install-codex-offline.sh
```
安装到 ~/.local/bin/（codex + bwrap + codex-code-mode-host），无需外网。

升级内置 Codex 版本：

从 openai/codex releases 下载对应版本的 codex-<arch>-unknown-linux-musl.tar.gz、bwrap-<arch>-unknown-linux-musl.tar.gz 与 codex-code-mode-host-<arch>-unknown-linux-musl.tar.gz，替换 vendor/codex/ 内文件；
重新生成校验和：cd vendor/codex && sha256sum *.tar.gz > CHECKSUMS.txt；
更新 Dockerfile 顶部的 ARG CODEX_VERSION 和 scripts/install-codex-offline.sh 中的默认版本号。

ARM (ARM64) NAS

镜像已发布为 多架构（linux/amd64 + linux/arm64），ARM 架构的 NAS 无需任何特殊操作：

docker compose up -d    # Docker 会自动拉取 arm64 架构的镜像

其他可选方式：

Release 离线镜像包：GitHub Release 提供 codex-web-1.0.0-alpha.arm64.docker.tar.gz，在 ARM 机器上 docker load -i 即可，适合网络受限环境；
源码本地构建：vendor/codex/ 已内置 ARM64 安装包，直接
```
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
```
Dockerfile 会按目标架构自动选用 arm64 的 codex/bwrap 安装包，全程离线。

模型提供商配置

环境变量（启动时）

变量	说明
`CODEX_PROVIDER`	`openai` / `deepseek` / `qwen` / `moonshot` / `zhipu` / `doubao` / `baidu` / `minimax` / `siliconflow` / `openrouter` / `ollama` / `gemini` / `xai` / `custom`（默认自动按 URL 推断）
`CODEX_BASE_URL`	OpenAI 兼容 Base URL，例如 `https://api.deepseek.com/`、`https://dashscope.aliyuncs.com/compatible-mode/v1`
`CODEX_API_KEY`	API Key
`CODEX_MODEL`	模型名，例如 `deepseek-v4-flash`、`gpt-5.6-sol`
`CODEX_MODELS_JSON`	可选：自定义模型目录文件路径（高级用户可覆盖自动生成的 `models.json`）

容器入口会把这些值写入 ~/.codex/config.toml（自动生成 models.json 模型元数据），只改写提供商相关字段，保留你已有的 MCP / skills / 项目信任等配置。

页面内配置 / 多提供商切换

设置弹窗 →「模型提供商」：

下拉选择 OpenAI / DeepSeek / 阿里云百炼 Qwen / Moonshot Kimi / 智谱 GLM / 火山方舟 Doubao / 百度千帆 ERNIE / MiniMax / 硅基流动 / OpenRouter / Ollama（本地）/ Google Gemini / xAI Grok / 自定义（选择预设会自动填 Base URL）；
填 Base URL、API Key、模型名，点「保存并应用」；已配置过时打开设置会自动回显当前配置（API Key 显示脱敏值，不重新填写即可沿用旧 Key）；
支持查询模型列表：填好 Base URL + API Key 后点「获取模型列表」，后端会请求 GET {Base URL}/models 并填充模型下拉（掩码 Key 会自动沿用已保存的真实 Key）；
后端会重写配置并重启 Codex 进程（进行中的任务会中断），模型列表即时刷新；
每次切换都会保留原 config.toml 备份（config.toml.bak-provider）。

内置模型预设（models.json 模板库）

保存配置时会按模型名匹配内置模板（lib/model-templates.js），自动写入准确的上下文窗口、模态、显示名等元数据；未命中的模型使用通用默认值。模板库覆盖 DeepSeek、OpenAI、Qwen、Kimi、GLM、Doubao、ERNIE、MiniMax、SiliconFlow、OpenRouter、Grok、Gemini、Ollama 等常见模型。

提供商 API 差异说明

OpenAI / DeepSeek 使用 wire_api = "responses"；
其余国产/兼容提供商（Qwen、Kimi、GLM、Doubao、ERNIE、MiniMax、SiliconFlow、OpenRouter、Ollama、Gemini、Grok）使用 OpenAI 兼容的 wire_api = "chat"，适配各自的 /chat/completions 接口；
部分厂商（如百度千帆、火山方舟）的模型名是部署时生成的 ID/Endpoint，填「获取模型列表」查到的实际模型名即可。

完整环境变量

变量	默认	说明
`CODEX_WEB_HOST`	`127.0.0.1`（Docker 镜像内为 `0.0.0.0`）	后端监听地址
`CODEX_WEB_PORT`	`10020`（Docker 镜像内为 `13020`）	后端监听端口
`CODEX_BIN`	`codex`	codex 可执行文件路径
`CODEX_EXTRA_ARGS`	空	追加到 `app-server` 前的 CLI 参数
`CODEX_DEFAULT_CWD`	`$HOME`（Docker 内为 `/workspace`）	自动新建会话的默认工作目录
`CODEX_PROJECTS_ROOT`	`/workspace`	项目（工作区）根目录
`CODEX_APPROVAL_POLICY`	`never`	新会话默认审批策略（`never` / `untrusted` / `on-request` / `granular`）
`CODEX_SANDBOX`	`danger-full-access`	新会话默认沙箱（`danger-full-access` / `workspace-write` / `read-only`）
`CODEX_MAX_UPLOAD_MB`	`50`	单次上传大小上限
`CODEX_UPLOAD_DIR`	`.codex-uploads`	上传临时目录名（位于项目内）
`CODEX_RPC_TIMEOUT_MS`	`60000`	JSON-RPC 请求超时
`CODEX_HOME`	`~/.codex`	codex 配置目录

架构

浏览器（网页聊天 UI + 资源管理器）
   │  HTTP (JSON API) + SSE（事件流/审批）
   ▼
server.js（Node，零依赖）
   │  stdio JSONL（JSON-RPC 2.0，官方默认传输）
   ▼
codex app-server（官方组件，运行在你的服务器上）
   │
   ▼
你配置的模型提供商（OpenAI / DeepSeek / 自定义）

非 Docker 部署

需要 Node.js ≥ 18 和 Codex CLI：

bash scripts/install-codex-offline.sh   # 离线安装 Codex CLI（也可用官方安装脚本）
node server.js   # 通过环境变量配置 CODEX_BASE_URL / CODEX_API_KEY / CODEX_MODEL

deploy/nas/ 下有本项目开发环境的 systemd 示例（供参考，非 Docker 场景）。

开发与测试

零依赖，无需 npm install：

node test/smoke.js   # 本地端到端测试（使用 mock app-server，不消耗 API）

测试覆盖：初始化握手、会话生命周期、审批流程、文件上传与路径穿越防护、项目/工作区、资源管理器与预览 Content-Type、提供商配置应用。

安全注意事项

Codex 能在你的服务器上执行命令：默认“完全访问”不询问，请确认部署环境可信；
页面右上角“shell 命令”框在沙箱外全权限执行，仅限可信用户；
公网暴露时务必加反向代理 + 认证（Basic Auth / OAuth），不要裸奔；
API Key 明文保存在 ~/.codex/config.toml（挂载卷内），请妥善保护该卷。

沙箱说明：默认「完全访问」模式不需要 bwrap。若要在 Docker 里使用「工作区写入 / 只读」沙箱，需要容器允许 user namespace（security_opt: [seccomp:unconfined]，见 docker-compose.yml 注释），或直接以特权模式运行。

Roadmap（alpha）

多提供商（OpenAI / DeepSeek / 自定义）配置与切换
项目（工作区）管理、会话归档/删除/批量管理
文件上传、资源管理器、快速预览
会话搜索/侧边栏体验打磨
多用户与认证
提供商健康检查与用量统计
完善 models.json 模板库（更多模型预设）

License

GPL-3.0 — GNU General Public License v3.0。

本项目基于 OpenAI Codex（Apache-2.0 / MIT 组件）构建；本项目源码按 GPLv3 发布，使用或分发时请遵守 GPLv3 及上游许可证要求。

Name		Name	Last commit message	Last commit date
deploy/nas		deploy/nas
lib		lib
public		public
scripts		scripts
test		test
vendor/codex		vendor/codex
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.build.yml		docker-compose.build.yml
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
package.json		package.json
server.js		server.js

Navigation Menu

Repository files navigation

Codex Web

功能

快速开始（Docker）

方式一：官方镜像快速部署（推荐 · 适合 NAS / 新手）

方式二：本地构建（开发者）

离线安装包（内置）

ARM (ARM64) NAS

模型提供商配置

环境变量（启动时）

页面内配置 / 多提供商切换

内置模型预设（models.json 模板库）

提供商 API 差异说明

完整环境变量

架构

非 Docker 部署

开发与测试

安全注意事项

Roadmap（alpha）

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Codex Web

功能

快速开始（Docker）

方式一：官方镜像快速部署（推荐 · 适合 NAS / 新手）

方式二：本地构建（开发者）

离线安装包（内置）

ARM (ARM64) NAS

模型提供商配置

环境变量（启动时）

页面内配置 / 多提供商切换

内置模型预设（models.json 模板库）

提供商 API 差异说明

完整环境变量

架构

非 Docker 部署

开发与测试

安全注意事项

Roadmap（alpha）

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages