Codex 智能体管理台

Codex 智能体管理台是一个本机 localhost 工具，用中文浏览和维护 Codex agent 配置、项目配置、运行线程、动态工作流证据，并对单个 agent TOML 执行受控写回。

项目由 Go 后端和 Vue 3 + Vite 前端组成。后端默认只读取当前用户的 CODEX_HOME，前端通过集中 API client 调用后端端点，并把来源、置信度、状态和写回结果转换为中文展示。

启动后端

默认配置：

CODEX_HOME: 未设置时使用当前用户主目录下的 .codex
HTTP 地址：127.0.0.1:18083
工作区根目录：后端进程当前目录，用于读取 task_plan.md 等计划证据

启动命令：

go run ./cmd/codex-agent-manager

健康检查：

curl http://127.0.0.1:18083/api/health

如需指向测试用 Codex home，可在启动前设置 CODEX_HOME。

启动前端

前端位于 web/，默认 dev 地址为 127.0.0.1:13083，Vite 代理本机后端 API。

cd web
pnpm install
pnpm dev

打开 http://127.0.0.1:13083/ 查看工作台。

Docker 启动

构建镜像：

docker build -t codex-agent-manager:local .

启动容器，并把本机 Codex 配置和当前项目目录挂载进去：

docker run --rm \
  --name codex-agent-manager \
  -p 0.0.0.0:18083:18083 \
  -e CODEX_HOME=/codex-home \
  -e WORKSPACE_ROOT=/Users/yoilun/Code/codex-agent-manager \
  -v /Users/yoilun/.codex:/codex-home \
  -v /Users/yoilun/Code/codex-agent-manager:/Users/yoilun/Code/codex-agent-manager:ro \
  codex-agent-manager:local

然后打开 http://127.0.0.1:18083/。Docker 镜像内由 Go 后端同时提供 API 和前端静态页面，不需要再单独启动 Vite。

如果要让局域网内其他设备访问，保持上面的 0.0.0.0:18083:18083 端口映射，然后在同一局域网的设备上打开：

http://你的电脑局域网IP:18083/

在 macOS 上可用下面命令查看当前 Wi-Fi/LAN IP：

ipconfig getifaddr en0

也可以使用 Compose：

docker compose up --build

如需改挂载路径，可在启动前设置本机环境变量：

CODEX_HOME=/path/to/.codex \
CODEX_AGENT_MANAGER_PROJECT=/path/to/codex-agent-manager \
docker compose up --build

验证命令

后端和整体检查：

go test ./...
go test -count=1 ./...
git diff --check

前端检查：

cd web
pnpm test
pnpm build

浏览器视觉验证已在 2026-05-25 使用本机 Chrome 访问 http://127.0.0.1:13083/ 完成，覆盖项目视图、工作流视图、智能体视图、草稿和设置页。内置浏览器插件若返回 Browser is not available: iab，可改用 Chrome 做只读页面核验，并在 progress.md 记录 fallback。

API 概览

GET /api/health: 健康检查，返回 { "status": "ok" }
GET /api/agents: 只读列出 CODEX_HOME/agents/*.toml 直属文件；坏 TOML 作为 invalid 条目返回
POST /api/agents/{id}/validate: 校验单个 agent TOML 草稿，返回 diff、字段变化、目标路径和当前 sha256 hash；不写文件
POST /api/agents/{id}/write: 使用 expectedHash 写回单个已有 agent TOML；写回前重新校验、创建备份并做原子替换
GET /api/projects: 只读解析 .codex/config.toml 中的项目配置
GET /api/runtime/threads: 只读读取 Codex SQLite 运行线程、spawn edges 和 goals，并返回来源证据
GET /api/workflow/events: 从运行线程、goals、spawn edges 和计划文件生成动态工作流事件、交接边和阶段状态

前端 API client 位于 web/src/api/client.js，中文 normalizer 位于 web/src/api/normalizers.js。

安全边界

不读取或展示 .codex/auth.json
不写入 Codex SQLite
项目配置只读解析 .codex/config.toml，默认不写配置文件
agent 写回仅限 CODEX_HOME/agents/{id}.toml 的已有直属普通文件
agent id 只允许字母、数字、下划线和连字符，不能包含路径、扩展名或子目录
拒绝 agents 目录 symlink、目标叶子 symlink、非普通文件和路径穿越
写回请求体限制为 1 MiB，拒绝无效 JSON 和 trailing JSON
错误响应对路径和系统错误做中文安全映射，避免泄漏敏感路径细节

写回流程

用户在智能体视图编辑单个 agent TOML 草稿。
前端调用 POST /api/agents/{id}/validate，后端读取当前目标文件、校验草稿、生成 diff 和 currentHash。
只有校验通过且存在 currentHash 时，前端才允许发起写回，并要求用户确认。
前端调用 POST /api/agents/{id}/write，携带同一份草稿和 expectedHash。
后端重新校验 TOML、重新读取目标文件并比较 hash；不匹配则返回冲突，不写文件。
后端在目标旁创建 *.bak-<timestamp> 备份；备份成功后才通过同目录临时文件和 rename 原子替换目标。
写回的读取、备份、临时文件和 rename 绑定到已打开的 agents dirfd，并在关键步骤复核目录身份和目标文件 hash。

5.0 KiB Raw Blame History Unescape Escape