内容
# docker-codexbox
[](https://hub.docker.com/r/psyb0t/codexbox)
[](http://www.wtfpl.net/)
[OpenAI Codex CLI](https://github.com/openai/codex) 封装在 [aicodebox](https://github.com/psyb0t/docker-aicodebox) 容器中。最小化镜像，预装工具链，提供多种交互方式：交互式 Shell、一次性执行、OpenAI 兼容接口、MCP 服务器、Telegram 机器人和可定制的定时任务调度器。
你可以通过 codexbox 与 codex 交互，codex 通过 codexbox 与 OpenAI 或 ChatGPT 订阅服务交互。
## 目录
- [快速开始](#快速开始)
- [使用 `codexbox` 包装器](#使用-codexbox-包装器)
- [镜像变体](#镜像变体)
- [模式](#模式)
- [API 模式](#API-模式)
- [Telegram 模式](#Telegram-模式)
- [定时任务模式](#定时任务模式)
- [配置](#配置)
- [认证](#认证)
- [开发](#开发)
- [测试](#测试)
- [许可证](#许可证)
## 快速开始
仅需安装并运行 Docker。
### 一键安装
安装脚本会拉取选定的镜像，创建持久化的 Codex 和 SSH 目录，下载包装器，并将 `codexbox` 安装到你的 `PATH` 中。
```bash
# 最小化镜像 - 默认
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/master/install.sh | bash
# 完整镜像 - 预装所有开发工具
export CODEXBOX_FULL=1 && curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/master/install.sh | bash
# 自定义命令名称
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/master/install.sh | bash -s -- codex
```
## 使用 `codexbox` 包装器
包装器会将当前目录挂载为工作空间，持久化 `~/.codex` 目录（以便登录后容器重启后仍可继续会话），转发认证和配置的环境变量，并管理每个目录的容器。
```bash
export OPENAI_API_KEY=sk-... # 或使用订阅：`codexbox login --device-auth`
codexbox # 交互式 TUI - 继续上一次会话
codexbox --no-continue # 相同，但启动全新会话
codexbox exec "修复 ./app 中的测试失败" # 一次性 codex 执行，输出到终端
echo "总结 README.md" | codexbox exec - # 通过 stdin 输入提示
codexbox login --device-auth # ChatGPT 订阅认证登录（持久化在 ~/.codex 中）
codexbox login status # 当前认证模式
codexbox --version # 转发到 `codex --version`
codexbox stop # 停止当前目录的运行容器
codexbox clear-session # 清除 codex 的保存会话（保留认证和配置）
```
## 镜像变体
- `psyb0t/codexbox:latest` 是默认的最小化镜像：Codex、Node.js、Python、`uv`、Docker、Git、`jq` 和 `curl`。
- `psyb0t/codexbox:latest-full` 在最小化镜像的基础上添加了通用开发工具链。
## 模式
### API 模式
`CODEXBOX_API_MODE=1`，在 `:8080` 端口启动 FastAPI 服务器。
### Telegram 模式
`CODEXBOX_TELEGRAM_MODE=1` + `CODEXBOX_TELEGRAM_MODE_TOKEN=<token>`。
### 定时任务模式
`CODEXBOX_CRON_MODE=1` + `CODEXBOX_CRON_MODE_FILE=/path/to/cron.yaml`。
## 配置
命名约定：`CODEXBOX_<MODE>_MODE=1` 是开关，`CODEXBOX_<MODE>_MODE_<KNOB>=...` 是其配置。
## 认证
codex 支持 **两种** 不同的认证模式。
### 1. API 密钥（按需付费）
设置 `OPENAI_API_KEY`。可选地设置 `OPENAI_BASE_URL` 以指向 OpenAI 兼容的端点。
```bash
docker run --rm \
-e OPENAI_API_KEY=sk-... \
-v "$PWD/.codex:/home/aicode/.codex" \
psyb0t/codexbox:latest \
exec "说 HELLO"
```
### 2. ChatGPT 订阅（Plus / Pro / Team）
无需任何 API 密钥 — codex 改为针对您的 ChatGPT 订阅计费。这需要一次性交互式 OAuth 登录，并且 **您必须绑定挂载 `~/.codex`**（→ 容器中的 `/home/aicode/.codex`），以便登录在容器重新创建后仍然有效：
```bash
docker run -it \
-v "$HOME/.codex:/home/aicode/.codex" \
psyb0t/codexbox:latest \
login --device-auth
```
这将打印一个 URL 和一个短代码。在任意浏览器中打开 URL，输入代码，批准 — codex 将 OAuth token 写入 `$CODEX_HOME/auth.json`（`auth_mode` 是 OAuth/ChatGPT 变体，而不是 `apikey`）。后续针对同一个绑定挂载的 `~/.codex` 的 `docker run` 命令将重用登录并针对订阅计费，无需 `OPENAI_API_KEY`：
```bash
docker run --rm \
-v "$HOME/.codex:/home/aicode/.codex" \
psyb0t/codexbox:latest \
exec "say HELLO"
```
**这仅在 `~/.codex` 被绑定挂载时有效。** 如果没有，它将位于临时容器的文件系统中，并在容器被删除时消失 — 您将不得不再次运行 OAuth 流程。如果 `OPENAI_API_KEY` 也在环境中设置，一旦存在订阅登录，它 **不会** 被覆盖 — 现有的 OAuth 登录始终优先于 API 密钥播种步骤。`codex login status`（直接传递）报告当前激活的模式；`codex logout` 清除它。
### 模型与推理努力
Codex **没有固定的默认模型名称** — 可用性由服务器驱动，并取决于您的身份验证方式：
- **ChatGPT 订阅** — GPT-5.6 系列：`gpt-5.6-luna`（最快 + 最便宜 — 适合测试），`gpt-5.6-terra`（平衡），`gpt-5.6-sol`（旗舰；帐户默认值）。`*-codex` / `*-codex-mini` 名称在 ChatGPT 帐户上被 **拒绝**（400 "不支持"）。
- **API 密钥** — API 目录：`gpt-5.1-codex`，`gpt-5-codex`，`gpt-5.1-codex-mini`（小）等。
使用 `-m` / `--model`（传递）或设置 `CODEXBOX_MODEL` / `/run` 和 `/openai/v1/chat/completions` 上的 `model` 字段来传递模型。
推理努力映射到 codex 的 `model_reasoning_effort` 配置键（`-c model_reasoning_effort=<level>`）。级别：`none`，`minimal`，`low`，`medium`，`high`，`xhigh`，`max`（默认 `medium`）。在 API 和 Telegram 中的 `/effort` 命令中作为 `thinking` 字段公开 — 与其他 aicodebox 子节点相同。
### 系统提示与工具控制
规范的 `/run` 旋钮受到尊重 — codex 只需以不同于 pi/claude 的方式公开它们：
- `systemPrompt` → 替换内置系统提示（`-c instructions=…`）。
- `appendSystemPrompt` → 追加开发人员角色消息（`-c developer_instructions=…`）。
- `noTools` → 删除 shell/exec + 网络搜索工具，并以只读方式运行沙箱，以便代理在不执行操作的情况下回答。（codex 保留 `apply_patch`/`update_plan` 工具规范，这些规范无法通过配置删除，但只读方式使它们失效 — codex 接近 pi/claude `--no-tools`。）
- `toolsAllowlist` → **不支持**：codex 没有基于名称的内置工具允许列表（仅每个 MCP 服务器的 `enabled_tools`）。它被忽略并带有警告。
- 会话：调用时既没有 `resume` 也没有 `noContinue`，则继续工作空间中最近的会话（`codex exec resume --last`，当没有要恢复的会话时，它会启动一个新的会话）；`resume` 目标是一个特定的会话 ID；`noContinue` 运行临时会话。
## 开发
需要在此存储库旁边检查 `psyb0t/docker-aicodebox`（`../docker-aicodebox`）。
```bash
make help # 列出目标
make build-base # 从 ../docker-aicodebox 构建 aicodebox-base
make build # 在其基础上构建 codexbox:local
make build-full # 构建并标记完整工具链变体
make build-all # 构建两个变体
make test # 运行完整的端到端测试套件（需要 .env.test）
make test-image-select # 选择性安装程序/包装器变体回归测试
make test-full-image # 构建完整版本并检查每个广告工具
make clean # 删除已构建的镜像
```
## 测试
端到端测试构建镜像并针对真正的 OpenAI/codex 端点运行。Telegram 测试使用 [psyb0t/telethon-plus](https://github.com/psyb0t/docker-telethon) 作为真正的 MTProto 用户机器人。
```bash
cp .env.test.example .env.test
$EDITOR .env.test # 填写 OPENAI_API_KEY 和可选的 Telegram 凭证
make test
```
如果 `AICODEBOX_TELEGRAM_MODE_TOKEN` 为空，则 Telegram 测试会自动跳过。除此之外，只需要 `OPENAI_API_KEY`（如果您还想使用订阅身份验证路径，还需要真正的 ChatGPT 订阅登录）。
`make test-image-select` 不需要凭证或 Docker 守护进程。它证明了 `CODEXBOX_FULL=0|1` 选择、拉取和构建相同的镜像。`make test-full-image` 构建 `latest-full` 并检查其变体标记、Codex、固定的 Go/Python 版本和广告的 CLI 矩阵。
## 许可证
WTFPL — 请参阅 [LICENSE](LICENSE)。随便你怎么搞。
