Codexbox

docker-codexbox

在 aicodebox 容器中运行 OpenAI Codex CLI。提供精简和预装工具链的镜像，支持六种使用方式：交互式 Shell、单次执行、兼容 OpenAI 的端点、MCP 服务、Telegram 机器人，以及可按任意计划运行 codex 的 cron 调度器。

你与 codexbox 对话。codexbox 与 codex 对话。codex 与 OpenAI 对话——或者与你的 ChatGPT 订阅对话。没人关心中间环节。

目录

• 快速开始
• 使用 codexbox 包装器
• 镜像变体
• 模式
  • API 模式
  • Telegram 模式
  • Cron 模式
  • MCP 模式
• 配置
• 身份验证
• Agent 集成
• 开发
• 测试
• 许可证

快速开始

唯一的前提是已安装并运行 Docker。

一行安装命令

安装程序会拉取所选镜像，创建持久化的 Codex 和 SSH 目录，下载包装器，并将 codexbox 安装到你的 PATH 中。

# minimal image — default
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/master/install.sh | bash

# full image — every development tool pre-installed
export CODEXBOX_FULL=1 && curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/master/install.sh | bash

# custom command name
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-codexbox/master/install.sh | bash -s -- codex

使用 CODEXBOX_FULL=1 安装会将 latest-full 写入包装器，因此这个选择会一直保留；你不必再次导出该变量。CODEXBOX_FULL 必须为 bash 设置，而不只是为 curl 设置，因此上面采用了 export … && 的形式。

本地检出

在本仓库的检出目录中，构建对应的镜像并安装本地包装器，无需拉取已发布的 codexbox 镜像：

make install       # minimal image
make install-full  # full image

# install only the local wrapper; do not build or pull
make install-wrapper
CODEXBOX_FULL=1 make install-wrapper  # full image

这些目标会设置 CODEXBOX_SRC_LOCAL=true。make install 和 make install-full 会先构建镜像；make install-wrapper 只会针对所选的现有镜像安装本地 wrapper.sh。如果镜像不存在，该命令会失败，而不会回退到 docker pull。

远程安装程序会从对应的发布标签下载 wrapper.sh。自动化程序可以设置 CODEXBOX_INSTALL_DIR、CODEXBOX_BIN_NAME 和 AICODEBOX_MANAGED_INSTALL=1，以便安装到其他命令目录，并且不提示替换现有 SSH 密钥。

使用 codexbox 包装器

包装器会将当前目录挂载为工作区，持久化 ~/.codex（因此重新创建容器后仍可保持登录状态），转发身份验证信息和已配置的环境变量，并管理每个目录对应的容器。

export OPENAI_API_KEY=sk-...         # or use a subscription: `codexbox login --device-auth`

codexbox                             # interactive TUI — continues the last session for THIS dir
codexbox --no-continue               # same, but starts a brand-new session instead
codexbox exec "fix the failing test in ./app"   # one-shot codex exec, output to your terminal
echo "summarize README.md" | codexbox exec -     # prompt via stdin
codexbox login --device-auth         # ChatGPT-subscription OAuth login (persists in ~/.codex)
codexbox login status                # which auth mode is active
codexbox --version                   # passthrough to `codex --version`
codexbox stop                        # stop this dir's running container(s)
codexbox clear-session               # drop codex's saved sessions (keeps auth + config)

包装器会将 "$@" 原样传递给镜像，因此任何 codex 子命令都可使用（例如 codexbox mcp ...、codexbox doctor 等）。绕过沙盒的标志会在容器内部注入——你无需手动传入。

裸交互式 TUI 默认会继续当前目录最近的一次会话（与 claudebox 的默认行为类似）——codex 自带的 resume --last 会根据当前工作目录限定查找范围；如果没有可恢复的会话，则会自动启动新会话，因此在全新的工作区中使用也很安全。传入 --no-continue 可强制启动新会话。

当一个容器需要启动另一个容器时，请将 codexbox、claudebox 和 pibox 安装到同一个命令目录中，通常是 /usr/local/bin。包装器会在该目录中查找其他包装器文件，并以只读方式将它们挂载到容器中。其他包装器随后会通过主机 Docker 守护进程运行，并挂载各自的主机数据目录。Codexbox 不会直接挂载另一个 Agent 的主目录。

Agent 使用和嵌套启动

已安装的包装器是用户和 Agent 的常规接口。Agent 应在指定工作区中运行 codexbox，而不是自行拼装新的 docker run 命令。包装器会保留工作区路径、Codex 状态、SSH 状态、镜像选择，以及每个工作区的容器生命周期。

codexbox exec "inspect this workspace and report the failing tests"
CODEXBOX_FULL=1 codexbox exec "run the full test suite"
printf '%s\n' "summarize README.md" | codexbox exec -

当一个容器需要启动另一个容器时，请在同一命令目录中安装 codexbox、claudebox 和 pibox。运行中的容器可以直接调用同级命令。 父包装器会传递主机启动上下文，并且只挂载同级包装器文件。不要设置 AICODEBOX_HOST_*、复制包装器或手动挂载其他容器的状态目录。

包装器不会自行转发 SSH Agent。若要让容器使用你的 Agent，请挂载其套接字，并将 SSH_AUTH_SOCK 指向该套接字：

CODEXBOX_MOUNT_SSH="$SSH_AUTH_SOCK:/ssh-agent:ro" CODEXBOX_ENV_SSH_AUTH_SOCK=/ssh-agent codexbox

该 Agent 中加载的每个密钥都可以在容器内使用。

手动使用 Docker

仅在明确要求部署容器时才使用原始 Docker。 包装器是交互式、一次性和本地服务使用的常规方式。 模式一节包含相关部署命令和配置。

镜像变体

• psyb0t/codexbox:latest 是默认的精简镜像：包含 Codex、Node.js、Python、uv、Docker、Git、jq 和 curl。
• psyb0t/codexbox:latest-full 基于共享的 aicodebox:latest-full 基础镜像，并添加 Codexbox 的适配器、入口点、身份验证和配置。

CODEXBOX_FULL 是二元选项：安装程序默认使用精简版，0 表示精简版，1 表示完整版。运行时未设置该值时，会保留已安装的镜像选择。任何其他值都会导致失败。安装程序会将解析后的镜像写入已安装的包装器，因此无需每次运行时都导出该变量，选择也会保留。运行时设置 CODEXBOX_FULL=0 或 CODEXBOX_FULL=1 可临时强制使用某个变体；CODEXBOX_IMAGE 始终是优先级最高的显式覆盖项。

完整版镜像新增：

• Go 1.27.2，包含 gopls、Delve、golangci-lint、staticcheck、gofumpt 以及测试和代码生成辅助工具
• Python 3.14.8，包含 pytest、Black、Flake8、mypy、Pyright、Poetry、Pipenv 以及常用 HTTP 和解析库
• JavaScript 和 TypeScript 的 lint、格式化、进程、框架、API 测试、静态服务器、Lighthouse 和 Storybook CLI
• GitHub CLI、Terraform、kubectl 和 Helm
• 构建工具、CMake、ClangFormat、Valgrind、GDB、strace 和 ltrace
• PostgreSQL、MySQL、SQLite 和 Redis 客户端
• Vim、Nano、tmux、htop、归档工具、网络诊断工具、ripgrep、fd、bat、eza、shellcheck 和 shfmt

完整版变体继承共享的 Aicodebox 完整镜像。Aicodebox 负责共享工具链的版本固定、锁定文件和供应链检查。Codexbox 只添加 其 Agent 软件包和启动层。

**许可说明：**精简镜像的许可清晰——仅包含基于 aicodebox 基础镜像的 Apache-2.0 许可 Codex。完整版镜像还捆绑了 HashiCorp Terraform，其许可为 BUSL-1.1（可获取源码、限制竞争），并非 OSI 认可的开源许可证。如果这会影响你的使用场景，请使用精简镜像，或在使用 latest-full 前自行查看 BUSL-1.1 条款。 完整明细见 THIRD_PARTY.md。

Wrapper 环境变量

在主机上设置 CODEXBOX_GIT_NAME 和 CODEXBOX_GIT_EMAIL，以便在启动钩子运行前配置运行时用户的全局 Git 身份。直接部署容器时也接受相同的变量名。容器内非空的 AICODEBOX_GIT_NAME 和 AICODEBOX_GIT_EMAIL 优先级更高；通过 wrapper 使用时，将这些共享值设为 AICODEBOX_ENV_AICODEBOX_GIT_NAME 和 AICODEBOX_ENV_AICODEBOX_GIT_EMAIL。设置为空时会保留现有的 Git 配置。拒绝多行值。

make version V=X.Y.Z 会同步软件包元数据、锁文件、Codex 插件清单和安装器的 wrapper 发布版本引用，但不会提交或打标签。远程安装会下载匹配的发布版 wrapper，除非 CODEXBOX_INSTALL_REF 覆盖它。更新镜像不会更新已安装的 wrapper。

运行 codexbox 前，请在主机上设置以下变量：

变量	默认值	用途
OPENAI_API_KEY	—	API 密钥认证（启动时写入 ~/.codex/auth.json）。订阅登录无需此项。
OPENAI_BASE_URL	—	将 codex 指向兼容 OpenAI 的端点
CODEXBOX_IMAGE	已安装的镜像	覆盖 wrapper 运行的镜像
CODEXBOX_FULL	已安装的选项（初始为 0）	0 强制使用精简版；1 强制使用完整版
CODEXBOX_DATA_DIR	~/.codex	挂载为 CODEX_HOME 的主机目录（认证信息、配置和会话）
CODEXBOX_SSH_DIR	~/.ssh/codexbox	挂载到容器中的 SSH 密钥目录（用于通过 SSH 使用 git）
CODEXBOX_MAX_MEM	10g	每个容器的内存上限
CODEXBOX_CONTAINER_NAME	根据 $PWD 生成	覆盖每个工作区的容器名称
CODEXBOX_ENV_*	—	将任意环境变量传入容器（去掉前缀：CODEXBOX_ENV_FOO=bar → FOO=bar）
CODEXBOX_MOUNT_*	—	挂载额外的主机目录（使用 /host:/container 语法，或仅提供路径以在两端使用相同路径）
AICODEBOX_ENV_*	—	将共享环境变量传入启动的容器，并去掉前缀
AICODEBOX_MOUNT_*	—	将共享主机目录挂载到启动的容器中

AICODEBOX_HOST_* 是供同级 wrapper 使用的带版本嵌套启动上下文。它记录主机绑定源路径，并由 wrapper 自动设置。普通主机启动时请勿设置此变量。

CODEXBOX_MODE_CRON=1 + CODEXBOX_MODE_CRON_FILE=/path/cron.yaml codexbox 会以长时间运行的后台容器启动 cron 调度器。

倾向于不在主机上安装？ wrapper 执行的操作都只是普通的 docker run；请参阅手动使用 Docker和模式。

模式

前台模式（API / Telegram / Cron）互斥，但 CODEXBOX_TELEGRAM_MODE=1 + CODEXBOX_CRON_MODE=1 除外，两者会同时运行（cron 在线程内运行于 telegram 中）。如果同时设置 API 模式和其他模式，则以 API 模式为准。

MCP 模式（CODEXBOX_MCP_MODE=1）独立运行，可与任何正在运行的前台模式共存。在 API 模式下，它挂载在 API 端口的 /mcp/ 路径上；在其他模式下，它作为独立端口上的 sidecar uvicorn 运行。

每种模式都有单独的页面，提供完整的设置说明、环境变量和示例。

API 模式 →

在 :8080 上运行的常驻 FastAPI 服务。支持 Agent 运行（同步、带运行 ID 轮询的异步运行、可取消运行）、工作区文件上传/下载/列出/删除（包含路径遍历检查），以及支持流式传输和由客户端执行工具调用的 OpenAI 兼容 chat/completions 端点。Codex 的原生 --output-schema 为 jsonSchema 提供支持，因此符合架构的输出无需重试。

environment:
  - CODEXBOX_API_MODE=1
  - CODEXBOX_API_MODE_TOKEN=your-secret
  - CODEXBOX_AVAILABLE_MODELS=gpt-5.1-codex,gpt-5.1-codex-mini

Telegram 模式 →

通过 Telegram 与 codex 对话。每个聊天使用隔离的工作区，并支持允许聊天和每个聊天的允许用户门控、文件导入、通过 [SEND_FILE: path] 获取文件，以及可跨重启保留的每聊天 /model、/effort、/system_prompt、/append_system_prompt 覆盖设置。

environment:
  - CODEXBOX_TELEGRAM_MODE=1
  - CODEXBOX_TELEGRAM_MODE_TOKEN=123456:ABC

Cron 模式 →

在 6 字段 croniter 计划上定义的 YAML 定时任务。每次运行都会生成历史记录目录，其中包含 meta.json、stdout.log、stderr.log、result.txt，并提供“上次运行”提示，方便任务引用自身的历史记录。

environment:
  - CODEXBOX_CRON_MODE=1
  - CODEXBOX_CRON_MODE_FILE=/home/aicode/.aicodebox/cron.yaml

MCP 模式 →

通过可流式传输的 HTTP 暴露 run_prompt 和受工作区限制的文件工具，让其他 Agent 能够将 codex 作为工具驱动。可与任何前台模式共存：在 API 模式下挂载于 API 端口的 /mcp/ 路径，其他模式下则在独立端口的根路径提供服务。它与 codex 自带的 MCP 客户端／服务端支持不同，codexbox 不会接入后者。

environment:
  - CODEXBOX_MCP_MODE=1
  - CODEXBOX_MCP_MODE_TOKEN=your-secret

配置

命名约定：CODEXBOX_<MODE>_MODE=1 是开关标志，CODEXBOX_<MODE>_MODE_<KNOB>=... 是其配置。未限定模式的变量（工作区、容器名称、可用模型）使用不带前缀的名称。

此镜像基于 aicodebox 构建，因此等效的 AICODEBOX_* 名称也有效——当只设置 CODEXBOX_X 时，入口点会将其转换为 AICODEBOX_X。如果两者都设置，则以 AICODEBOX_* 为准。

模式标志

变量	默认值	作用
CODEXBOX_API_MODE	0	启动 HTTP API 服务（前台运行）
CODEXBOX_TELEGRAM_MODE	0	启动 Telegram 机器人（前台运行）
CODEXBOX_CRON_MODE	0	启动 cron 调度器（前台运行；同时启用 Telegram 时在线程中运行）
CODEXBOX_MCP_MODE	0	暴露 MCP——在 API 模式下挂载于 /mcp/，其他模式下作为旁路服务运行

各模式的专属配置项（端口、令牌、配置路径、历史记录目录）请参阅对应页面：api.md、telegram.md、cron.md、mcp.md。

工作区与运行时

变量	默认值	作用
CODEXBOX_WORKSPACE	/workspace	容器内的工作区根目录
CODEXBOX_CONTAINER_NAME	aicodebox	用于限定每个容器的状态文件（身份验证等）
CODEXBOX_AVAILABLE_MODELS	—	API 模式必需。 以 CSV 格式列出由 /openai/v1/models 返回并显示在 Telegram /model 选择器中的模型。未设置时，API 模式会拒绝启动；Telegram /model 选择器则会退化为提示“设置此环境变量”的回复。
CODEXBOX_AVAILABLE_EFFORTS	none,minimal,low,medium,high,xhigh,max	覆盖 Telegram /effort 选择器显示的工作量／推理级别列表（以逗号分隔）
CODEXBOX_MODEL	—	调用方未指定模型时，传递给 codex（-m/--model）的默认模型

初始化脚本与用户 bin 目录

$HOME/.aicodebox/bin 位于 PATH 的最前面，适用于 codex 本身、初始化脚本和 docker exec shell。可将自定义脚本放在此处。

$HOME/.aicodebox/init.d/*.sh 每个容器运行一次，在镜像自带的 /aicodebox-init.d/*.sh 之后，以拥有免密码 sudo 权限的 aicode 身份运行。脚本失败时会记录日志，其余脚本仍会继续运行。挂载 $HOME/.aicodebox，即可提供上述任一目录。即使 $HOME/.aicodebox 曾被使用过，新容器也会再次运行初始化脚本，因此脚本必须能够安全地重复执行。

身份验证

codex 支持两种不同的身份验证模式。请选择一种。

1. API 密钥（按使用量付费）

设置 OPENAI_API_KEY。也可选择设置 OPENAI_BASE_URL，将请求指向兼容 OpenAI 的端点，而非默认的 OpenAI API。

docker run --rm \
  -e OPENAI_API_KEY=sk-... \
  -v "$PWD/.codex:/home/aicode/.codex" \
  psyb0t/codexbox:latest \
  exec "say HELLO"

容器启动时会根据 OPENAI_API_KEY 为 codex 写入 $CODEX_HOME/auth.json（底层使用 codex login --with-api-key，并从标准输入读取密钥——codex 的 codex exec 不接受单独设置的 OPENAI_API_KEY 环境变量；必须先执行登录步骤，才能实际写入 auth.json）。每次启动都可以安全地执行此写入操作：它只会写入 apikey 模式的身份验证信息，不会触碰已有的 ChatGPT 订阅登录信息（见下文）。

2. ChatGPT 订阅（Plus / Pro / Team）

完全不需要 API 密钥——codex 会改为通过你的 ChatGPT 订阅计费。这需要一次交互式 OAuth 登录，并且必须绑定挂载 ~/.codex（→ 容器中的 /home/aicode/.codex），这样容器重新创建后登录状态才能保留：

docker run -it \
  -v "$HOME/.codex:/home/aicode/.codex" \
  psyb0t/codexbox:latest \
  login --device-auth

这会输出一个 URL 和一个简短代码。在任意浏览器中打开该 URL，输入代码并批准——codex 会将 OAuth 令牌写入 $CODEX_HOME/auth.json（auth_mode 是 OAuth/chatgpt 变体，而非 apikey）。之后每次使用同一个绑定挂载的 ~/.codex 执行 docker run，都会复用该登录并通过订阅计费，无需 OPENAI_API_KEY：

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（旗舰型号；账户默认模型）。ChatGPT 账户会拒绝 *-codex / *-codex-mini 标识（400“not supported”）。
• 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 中通过 thinking 字段提供，在 Telegram 中通过 /effort 命令提供——形式与其他 aicodebox 子项相同。

系统提示词与工具控制

规范的 /run 参数均受支持——codex 只是以不同于 pi/claude 的方式提供这些功能：

• systemPrompt → 替换内置系统提示词（-c instructions=…）。
• appendSystemPrompt → 附加一条 developer 角色消息（-c developer_instructions=…）。
• noTools → 移除 shell/exec 和网页搜索工具，并以只读模式运行沙盒，让 Agent 只回答、不执行操作。（codex 会保留无法通过配置移除的 apply_patch / update_plan 工具规格，但只读模式会使它们失效——这是 codex 最接近 pi/claude --no-tools 的功能。）
• toolsAllowlist → 不支持：codex 没有基于名称的内置工具允许列表（仅支持按 MCP 服务设置 enabled_tools）。此参数会被忽略，并显示警告。
• 会话：不带 resume 和 noContinue 的调用会继续使用固定到规范工作区的顶层 Codex exec 会话。首次调用会启动一个持久的根会话；后续调用会恢复其确切 ID，因此较新的子 Agent 部署不会抢占续接会话。现有工作区会自动迁移到最新的顶层 exec 部署。resume 会指定并重新固定某个会话 ID；noContinue 则会以临时方式运行，不更改固定的会话。

Agent 集成

技能适用于任何能读取 .agents/skills/ 的 Agent（例如 peen），并可原生集成到以下客户端中。

Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install codexbox@psyb0t

Claude Code 会提示输入 codexbox URL；如果服务器上设置了 API/MCP 令牌，还会提示输入对应的 bearer 令牌——敏感值会存储在你的操作系统钥匙串中。

Codex

codex plugin marketplace add psyb0t/agents
codex plugin add codexbox@psyb0t

通过市场安装后，可使用 $codexbox:codexbox 调用此技能。Codex 也会自动发现此技能，无需安装；只要代码仓库中包含 .agents/skills/，即可直接使用 $codexbox 调用。

OpenClaw

此技能会在每次发布时发布到 ClawHub：

openclaw skills install @psyb0t/codexbox

对于支持本地 stdio 的 MCP 客户端，@psyb0t/codexbox 插件会连接到正在运行的 box 的 /mcp 端点：

openclaw plugins install clawhub:@psyb0t/codexbox

然后设置 CODEXBOX_URL（如果启动服务时设置了 CODEXBOX_MCP_MODE_TOKEN，也要设置该变量）。

开发

需要将 psyb0t/docker-aicodebox 检出到此代码仓库旁边（../docker-aicodebox）。

make help        # list targets
make build-base  # build aicodebox-base from ../docker-aicodebox
make build       # build codexbox:local on top of it
make build-full  # build + tag the full toolchain variant
make build-all   # build both variants
make test        # run the full e2e suite (needs .env.test)
make test-image-select # hermetic installer/wrapper variant regression
make test-full-image   # build full and check every advertised tool
make clean       # remove built images

测试

端到端测试会构建镜像，并通过真实的 OpenAI/codex 端点运行测试。Telegram 测试会使用 psyb0t/telethon-plus 作为真实的 MTProto userbot。

cp .env.test.example .env.test
$EDITOR .env.test   # fill in OPENAI_API_KEY and optionally Telegram creds
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。想怎么做就怎么做。

发布的镜像中捆绑的第三方组件（Codex，以及仅限完整镜像包含的 Terraform、gh、kubectl、Helm、golangci-lint）均保留各自的许可证；详见 THIRD_PARTY.md。