用 Docker 隔离运行 Codex：从镜像构建到项目挂载的完整实践（TaoToken 统一 Key 接入版）

1. 为什么要把 Codex CLI 塞进 Docker 里跑Codex CLI 是一个能在终端里直接读写代码、执行命令、跑测试的 coding agent。它最大的价值在于能动手——不只是给你建议而是真的去改文件、装依赖、跑构建。但恰恰是这种能力让运行边界变得格外重要。我试过直接在宿主机上跑它结果一次实验性重构把本机的 Node 版本从 20 升到了 22另一个项目的构建当场挂掉排查了半小时才反应过来是环境被改了。所以核心问题不是Codex 好不好用而是让它在哪里用、能看到什么、能改什么。Docker 隔离运行 Codex CLI 解决的正是这件事宿主机只保存代码容器负责跑 Codex 和它需要的一切工具链。Codex 只能看到你明确挂载进去的目录容器删掉就回到干净状态本机的 Python、JDK、Node 版本完全不受影响。这套方案适合几类人同时维护多个项目的开发者每个项目的依赖版本不一样需要分析第三方代码或临时实验的场景不想让陌生依赖污染本机以及想把 Codex 接进 CI 或自动化流程的团队需要可重建、可丢弃的运行环境。整体结构很清晰宿主机 ├── /path/to/my-project # 真实项目代码唯一暴露给容器的目录 └── Docker └── codex-runner 容器 ├── /workspace # 挂载宿主机项目目录 ├── codex CLI # 容器内安装 ├── node/python/git # 容器内工具链 └── ~/.codex # 配置与登录缓存可选挂载持久化关键点在于Codex 的视野被限制在/workspace和容器内部宿主机上其他目录它根本看不到。这比单纯依赖 Codex 自身的 sandbox 更硬——sandbox 是进程级约束Docker 是文件系统级隔离两层叠加才稳妥。接下来我会从镜像构建开始一步步交付可复制的 Dockerfile、compose 骨架、配置片段以及接入 TaoToken 统一 Key 通道的完整做法。你跟着敲就能跑起来。2. TaoToken 统一 Key 接入的前置准备在动手写 Dockerfile 之前先把 Key 和通道这件事理清楚否则后面容器里跑起来会卡在认证上。Codex CLI 支持多种认证方式但在容器化、自动化场景下用统一的 API 通道比交互式登录更可控——尤其是当你要在多个项目、多个容器之间复用同一套凭据时。TaoToken 在这里扮演的角色是统一入口你拿到一个 Key配好 Base URLCodex CLI 就能通过它调用模型不用在每个容器里单独做浏览器授权。这对 Docker 场景特别友好因为容器里没有浏览器设备码登录虽然能用但每次重建容器都要重来一遍很烦。先做三件事。第一拿到 API Key。访问 https://taotoken.net/api-keys 创建注意这个 Key 只在创建时完整显示一次复制好存到安全的地方。不要写进 Dockerfile不要提交到 Git后面我们会用运行时环境变量注入。第二确认 Base URL。TaoToken 的 API 端点是https://taotoken.net/api这个地址在配置 Codex 的config.toml时会用到。注意它不带任何查询参数就是干净的 API 根路径。第三想清楚配置放哪。Codex CLI 读取配置的位置由CODEX_HOME环境变量决定默认是~/.codex。在容器里这个目录对应/home/codex/.codex。你有两个选择一是每次容器启动时通过环境变量注入 Key配置不持久化二是把配置目录挂载出来宿主机上维护一份config.toml容器复用。我推荐第二种因为配置集中管理改一次所有容器都生效。如果你还没决定用哪种模型可以先到 https://taotoken.net/models 看看当前可用的模型列表把 Model ID 记下来后面写进配置。模型对话页面在 https://taotoken.net/chat可以用来快速验证 Key 是否有效不用等容器构建完才发现 Key 有问题。这里有个容易踩的坑很多人习惯把 Key 直接写进config.toml然后提交到仓库这是大忌。正确做法是config.toml里只写非敏感的配置项Key 通过环境变量OPENAI_API_KEY传入Codex CLI 会自动读取。这样配置文件可以安全地版本管理Key 留在运行环境里。准备好 Key、Base URL、Model ID 这三样就可以进入镜像构建了。3. 可复制的 Dockerfile 与 config.toml 配置这一节是整篇的核心所有片段都可以直接复制使用。先建目录mkdir -p codex-docker-runner cd codex-docker-runner目录结构规划如下codex-docker-runner ├── Dockerfile ├── docker-compose.yml ├── config.toml # Codex 配置挂载进容器 └── codex-home/ # 持久化登录缓存加入 .gitignore先把codex-home/排除出版本控制echo codex-home/ .gitignore3.1 Dockerfile基于 Ubuntu 24.04装齐常用工具链用 npm 安装 Codex CLI创建非 root 用户避免文件权限混乱FROM ubuntu:24.04 ARG DEBIAN_FRONTENDnoninteractive RUN apt-get update apt-get install -y --no-install-recommends \ ca-certificates \ curl \ git \ bash \ sudo \ python3 \ python3-pip \ python3-venv \ build-essential \ ripgrep \ jq \ vim \ less \ bubblewrap \ rm -rf /var/lib/apt/lists/* RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \ apt-get update \ apt-get install -y --no-install-recommends nodejs \ npm install -g openai/codex \ npm cache clean --force \ rm -rf /var/lib/apt/lists/* RUN useradd -m -s /bin/bash codex \ echo codex ALL(ALL) NOPASSWD:ALL /etc/sudoers.d/codex \ chmod 0440 /etc/sudoers.d/codex USER codex WORKDIR /workspace ENV CODEX_HOME/home/codex/.codex CMD [bash]构建镜像docker build -t local/codex-runner:latest .验证 Codex 装好了docker run --rm local/codex-runner:latest codex --version3.2 config.toml 配置片段在codex-docker-runner/下创建config.toml这是 Codex CLI 读取的配置文件。注意这里不写 KeyKey 走环境变量# config.toml model gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key OPENAI_API_KEY wire_api responses几个关键字段说明base_url指向 TaoToken 的 API 根路径env_key告诉 Codex 从哪个环境变量读 Key这里用OPENAI_API_KEYwire_api指定协议类型按你实际使用的模型和通道要求填写。model字段填你在模型列表里选定的 Model ID。如果你用的是 Claude Code 风格的接入配置结构类似但字段名可能不同参考 https://taotoken.net/doc 里的对应说明。3.3 docker-compose.yml 骨架services: codex-runner: image: local/codex-runner:latest container_name: codex-runner-demo working_dir: /workspace tty: true stdin_open: true volumes: - /Users/you/projects/demo-app:/workspace - ./config.toml:/home/codex/.codex/config.toml:ro - ./codex-home:/home/codex/.codex environment: - TERMxterm-256color - OPENAI_API_KEY${OPENAI_API_KEY}注意config.toml用只读挂载:ro防止容器内意外修改codex-home可读写用于持久化登录状态。OPENAI_API_KEY从宿主机环境变量透传启动前先export OPENAI_API_KEY你的Key。三件套齐了Base URL 是https://taotoken.net/apiKey 走OPENAI_API_KEY环境变量Model ID 写在config.toml的model字段。这三样缺一不可后面排障也围绕它们展开。4. 容器内验证请求与成功结果配置写好了现在启动容器验证整条链路通不通。这一步很关键因为 Docker 网络、环境变量透传、配置文件挂载任何一个环节出问题都会在调用模型时才暴露。先导出 Keyexport OPENAI_API_KEY你的TaoTokenKey启动容器docker compose run --rm codex-runner进入容器后先确认环境pwd ls codex --version echo $OPENAI_API_KEY | head -c 8pwd应该输出/workspacels能看到你挂载的项目文件codex --version打印版本号最后一行确认 Key 已经透传进来只显示前 8 位避免泄露。接着验证配置文件被正确读取cat /home/codex/.codex/config.toml应该能看到你写的base_url和model字段。现在做一次最小化的模型调用验证。在容器里直接跑codex exec 用一句话说明当前目录下有哪些文件如果一切正常Codex 会读取/workspace下的文件列表并返回描述。这一步成功意味着容器网络能访问 TaoToken API、Key 认证通过、模型 ID 有效、配置文件解析正确。你也可以用更直接的方式验证 API 通道在容器里用 curl 打一次curl -s https://taotoken.net/api/models \ -H Authorization: Bearer $OPENAI_API_KEY | jq .data[].id | head返回模型列表说明 Key 和网络都没问题。如果这一步失败但codex exec能跑那问题在 Codex 的配置解析如果两步都失败问题在 Key 或网络。验证通过后日常使用就简单了。写一个run-codex.sh脚本#!/usr/bin/env bash set -euo pipefail PROJECT_DIR${1:-$PWD} CONTAINER_NAMEcodex-runner-$(basename $PROJECT_DIR) docker run --rm -it \ --name $CONTAINER_NAME \ -v $PROJECT_DIR:/workspace \ -v $(pwd)/config.toml:/home/codex/.codex/config.toml:ro \ -v $HOME/.codex-docker-home:/home/codex/.codex \ -e OPENAI_API_KEY \ -w /workspace \ local/codex-runner:latest \ codex --sandbox workspace-write --ask-for-approval on-request赋权后使用chmod x run-codex.sh ./run-codex.sh /path/to/your-project这样每次针对不同项目启动独立容器Codex 只在挂载的项目目录里工作宿主机其他部分完全隔离。实测下来从启动到 Codex 开始响应通常在几秒内比每次配置本机环境快得多。5. 常见报错排查401、local proxy failed、reading choices这一节对照真实报错把最容易卡住的几个问题拆开讲。这些错误我在不同阶段都遇到过按顺序排查基本能定位。5.1 401 Unauthorized最常见表现为codex exec返回 401 或invalid api key。原因通常是 Key 没透传进容器。检查顺序先在宿主机确认环境变量存在echo $OPENAI_API_KEY | head -c 8如果宿主机就是空的说明export没执行或写在了错误的 shell 会话里。docker compose的environment段里写的是${OPENAI_API_KEY}它从宿主机当前 shell 读取所以必须在同一个终端里先 export。如果宿主机有值但容器里没有检查 compose 文件里environment段是否正确引用了变量名以及docker compose run时有没有加-e覆盖。用docker compose run --rm codex-runner env | grep OPENAI确认容器内环境变量。还有一种情况Key 本身失效或额度用尽。到 https://taotoken.net/api-keys 确认 Key 状态或者用 https://taotoken.net/chat 快速测一下这个 Key 能不能正常对话。5.2 local proxy failed / connection refused报错类似local proxy failed或dial tcp: connection refused说明容器内访问不到 TaoToken 的 API 端点。先确认容器网络docker run --rm local/codex-runner:latest curl -sI https://taotoken.net/api如果这条命令超时或拒绝连接检查宿主机的 Docker 网络配置以及是否有防火墙规则拦截了容器出站流量。企业内网环境可能需要配置 Docker 的 DNS 或 HTTP 代理这部分按你所在网络的规范处理。如果 curl 能通但 Codex 报 proxy failed检查config.toml里的base_url是否写成了带路径的形式。正确写法是https://taotoken.net/api不要多加/v1或其他后缀具体路径由 Codex 根据wire_api自动拼接。5.3 reading choices / 响应解析失败报错包含reading choices或unexpected response format通常是wire_api字段和实际通道不匹配。Codex CLI 支持responses和chat两种协议TaoToken 通道用哪种取决于你选的模型。到 https://taotoken.net/doc 查对应模型的接入说明把config.toml里的wire_api改成正确的值。另一个可能是 Model ID 写错了。model字段必须和 TaoToken 模型列表里的 ID 完全一致大小写敏感。用前面 curl 模型列表的命令确认准确的 ID。5.4 OAuth / 登录相关报错如果你选择交互式登录而不是 API Key容器里跑codex login可能报 OAuth 回调失败因为容器没有浏览器。改用设备码方式codex login --device-auth终端会显示一个码和 URL在宿主机浏览器里打开完成授权。授权状态存在CODEX_HOME里如果你挂载了codex-home重建容器后不用重新登录。但要注意codex-home里可能包含auth.json等敏感凭据绝对不要提交到 Git。如果团队协作建议统一用 API Key 方式凭据通过环境变量或 secret 管理不落地到文件。5.5 sandbox 相关报错容器里跑 Codex 时可能遇到bwrap: operation not permitted或 sandbox 初始化失败。这是因为 Docker 默认的 seccomp 配置限制了 bubblewrap 需要的 namespace 操作。两个选择一是给容器加--security-opt seccompunconfined和--cap-add SYS_ADMIN让内层 sandbox 能工作二是承认 Docker 本身就是隔离边界在容器内用codex --sandbox danger-full-access但前提是挂载范围足够小只挂项目目录。我倾向第二种因为 Docker 的文件系统隔离已经比 Codex 内层 sandbox 更硬没必要为了内层 sandbox 放宽容器的安全配置。但如果你挂载了 Docker socket 或 SSH key那隔离意义就大打折扣了这种情况必须保留内层 sandbox。6. 长期编码与 Agent 场景的接入建议如果你只是偶尔用 Codex 做一次性任务前面这套 Docker 方案已经够用。但如果你打算把 Codex 作为日常编码助手或者接进自动化流程长期跑有几个点值得提前规划。第一是凭据管理。API Key 通过环境变量注入适合本地开发但在 CI 或服务器上建议用 secret 管理工具不要把 Key 写进任何会进版本控制的文件。config.toml可以安全提交因为它只包含 Base URL 和 Model ID不含敏感信息。第二是配置复用。把config.toml和run-codex.sh放在一个独立的 runner 仓库里所有项目共用。每个项目只需要在启动时指定路径不用重复配置。这样升级模型或切换通道时改一处就够。第三是 Coding Plan 场景。如果你需要长时间、多轮次的 Agent 编码任务TaoToken 的 Coding Plan 提供了更适合持续调用的通道方案具体可以到 https://taotoken.net/coding-plan 了解。它和按次调用的 API Key 是互补的前者适合交互式探索后者适合稳定的批量任务。第四是 Claude Code 风格的接入。如果你同时用 Claude Code 和 Codex两者的配置结构不同但思路一致都是 Base URL Key Model ID 三件套。Claude Code 的配置参考 https://taotoken.net/claude-code-anthropicCodex 的配置就是本文的config.toml。统一用 TaoToken 作为通道好处是 Key 和模型管理集中在一处不用为每个工具单独申请凭据。最后说一个实际经验容器化运行 Codex 最大的收益不是安全而是可重建。本机环境跑久了总会积累各种临时改动出问题很难回到干净状态。容器删掉重建只要几秒而且每次都是确定性的环境。对于需要反复实验、分析陌生代码、跑一次性任务的场景这种确定性比什么都值钱。日常使用中我建议从最简单的docker run -v 当前项目:/workspace开始跑顺了再补 compose、脚本和网络限制。不要一上来就追求完美配置先把链路跑通再逐步收紧边界。