From 452816aee3e491f68759bcb3a6ded4e06d7f80d1 Mon Sep 17 00:00:00 2001
From: "zhang,zhao" <905781330@qq.com>
Date: Tue, 14 Jul 2026 11:25:39 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E8=A1=A5=E5=85=85?=
 =?UTF-8?q?=20Docker=20Codex=20CLI=20=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                     |  8 +++
 .../plans/2026-07-14-docker-codex-cli.md      | 66 +++++++++++++++++++
 .../2026-07-14-docker-codex-cli-design.md     |  4 +-
 3 files changed, 76 insertions(+), 2 deletions(-)
 create mode 100644 docs/superpowers/plans/2026-07-14-docker-codex-cli.md

diff --git a/README.md b/README.md
index f930347..ae1c990 100644
--- a/README.md
+++ b/README.md
@@ -161,6 +161,14 @@ docker compose up --build
 # 打开 http://localhost:3018
 ```
 
+Docker 镜像内置固定版本的 **Codex CLI**，Compose 会将主机 `${HOME}/.codex` 只读挂载到容器，因此主机需先完成 Codex 登录。需要覆盖镜像内版本时可设置构建参数：
+
+```bash
+CODEX_CLI_VERSION=0.144.3 docker compose up --build
+```
+
+> Codex CLI 模式允许 TickFlow 容器读取本机 Codex 登录凭据，仅应在受信任的本机环境启用。凭据目录以只读方式挂载，不会写入镜像。
+
 镜像已内置 **stock-sdk** 数据源插件(Node 运行时 + 依赖),开箱即用。
 
 > 📖 Docker 进阶、GitHub Actions 自构建、老 CPU 兼容、访问密码设置等见 [docs/deployment.md](./docs/deployment.md)。
diff --git a/docs/superpowers/plans/2026-07-14-docker-codex-cli.md b/docs/superpowers/plans/2026-07-14-docker-codex-cli.md
new file mode 100644
index 0000000..544d12f
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-14-docker-codex-cli.md
@@ -0,0 +1,66 @@
+# Docker Codex CLI Support Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make Docker deployments detect and execute the host-authenticated Codex CLI without putting credentials into the image.
+
+**Architecture:** Install a pinned `@openai/codex` package in a dedicated Node builder stage, extract its platform-native Linux binary, and copy only that binary into the runtime image. Mount `${HOME}/.codex` read-only so the existing backend can copy authentication into its per-request temporary Codex home.
+
+**Tech Stack:** Docker multi-stage builds, Docker Compose, `@openai/codex`, FastAPI, pytest
+
+---
+
+### Task 1: Establish baseline and impact
+
+**Files:** No changes.
+
+- [x] Confirm host `codex --version` reports `0.144.3`.
+- [x] Confirm the old container cannot resolve `codex`.
+- [x] Run GitNexus impact on `_resolve_command`; avoid changing the HIGH-risk backend symbol chain.
+- [x] Run `uv run pytest tests/test_ai_provider.py -q`; expect 15 passing tests.
+
+### Task 2: Package Codex in Docker
+
+**Files:**
+- Modify: `Dockerfile`
+
+- [x] Add `CODEX_CLI_VERSION=0.144.3` as a reproducible build argument.
+- [x] Install `@openai/codex` in `codex-builder` and locate `*/vendor/*/bin/codex`.
+- [x] Copy the native binary to `/opt/codex-native` and verify its version in the builder.
+- [x] Copy only `/opt/codex-native` to runtime `/usr/local/bin/codex` and verify it there.
+- [x] Keep runtime Node.js conditional on stock-sdk because the extracted Codex binary is self-contained.
+
+### Task 3: Reuse host authentication safely
+
+**Files:**
+- Modify: `docker-compose.yml`
+
+- [x] Pass `CODEX_CLI_VERSION` through Compose.
+- [x] Mount `${HOME}/.codex:/root/.codex:ro`.
+- [x] Run `docker compose config` and confirm the version and read-only mount.
+
+### Task 4: Document behavior
+
+**Files:**
+- Modify: `README.md`
+- Create: `docs/superpowers/plans/2026-07-14-docker-codex-cli.md`
+
+- [x] Document the pinned version, version override, host login requirement, and credential security boundary.
+- [ ] Run `git diff --check`.
+- [ ] Run `gitnexus detect-changes` before the documentation commit.
+
+### Task 5: End-to-end verification and PR
+
+**Files:** No changes.
+
+- [x] Build the Codex builder stage and verify `codex-cli 0.144.3`.
+- [x] Copy the extracted binary into the current TickFlow runtime image and verify it executes without Node.js.
+- [ ] Recreate the app with the Codex-enabled image and existing data.
+- [ ] Verify `/api/settings` reports Codex configured.
+- [ ] POST `/api/strategies/ai/test` and expect `{"ok":true}` with `OK`.
+- [ ] Re-run provider tests and inspect final Git/GitNexus scope.
+- [ ] Push `codex/docker-codex-cli` and open a Draft PR against `main`.
+
+### Known external build issue
+
+A cold full-image build currently reaches the Codex stages successfully, then fails in the pre-existing backend dependency layer because `backend/uv.lock` contains direct Tsinghua mirror wheel URLs returning HTTP 403. This PR does not rewrite the lockfile or mix that unrelated dependency-source problem into the Codex fix; runtime compatibility is verified separately against the existing TickFlow image.
diff --git a/docs/superpowers/specs/2026-07-14-docker-codex-cli-design.md b/docs/superpowers/specs/2026-07-14-docker-codex-cli-design.md
index 2a57121..c7e8099 100644
--- a/docs/superpowers/specs/2026-07-14-docker-codex-cli-design.md
+++ b/docs/superpowers/specs/2026-07-14-docker-codex-cli-design.md
@@ -22,9 +22,9 @@ TickFlow 的 Docker 服务运行在独立容器中。即使 macOS 主机已经
 
 ### 镜像构建
 
-Dockerfile 新增独立的 `codex-builder` 阶段，使用 Node bookworm 镜像安装固定版本的 `@openai/codex`。版本由 `CODEX_CLI_VERSION` 构建参数控制，并提供项目验证过的默认值。
+Dockerfile 新增独立的 `codex-builder` 阶段，使用 Node bookworm 镜像安装固定版本的 `@openai/codex`，再从官方包中提取当前构建平台的 Linux 原生二进制。版本由 `CODEX_CLI_VERSION` 构建参数控制，并提供项目验证过的默认值。
 
-运行阶段从构建阶段复制 Codex 包，并在 `/usr/local/bin/codex` 提供入口。运行镜像继续使用已有的 Debian Node.js 运行时，不额外保留 npm，从而减少运行层体积和可变依赖。
+运行阶段只把提取后的原生二进制复制到 `/usr/local/bin/codex`，不复制 npm 包，也不要求为了 Codex 常驻安装 Node.js。这样保留多架构构建能力，同时减少运行层体积和可变依赖。
 
 ### 凭据挂载