关键词:自主编码代理 · AI 自主构建 Web 应用 · Codex CLI 自主构建 · 双代理编码循环 · feature_list.json 自动迭代 · 停滞检测修复 · autonomous-coding 中文版 · Codex CLI autonomous coding fork
Keywords: autonomous coding agent · autonomous web app builder · Codex CLI autonomous coding fork · two-agent coding loop · feature_list.json autonomous build · stagnation detection coding agent · alternative to Devin · alternative to SWE-agent
基于 Codex CLI 的自主编码代理,可自动构建完整 Web 应用。这是 Anthropic 官方 quickstart autonomous-coding 的衍生分叉,把 agent 后端从 Anthropic SDK 切到 Codex CLI(Claude 路径仍可选);加上停滞检测 + 修复代理、断点续跑、多凭证解析、Bash 白名单。
⚠️ 安全提示 — Codex 后端默认走「高权限」自主模式为了让无人值守的自主编码循环可以推进,Codex 后端在
codex exec调用上固定加了--dangerously-bypass-approvals-and-sandbox,允许 Codex CLI 在工作目录执行任意 shell 命令、读写任意文件、访问任意网络。使用前提:只在受信任的 generations/ 子目录下、用受信任的 prompt 启动。不要把这个工具指向系统目录、不要用陌生人发来的
app_spec.txt。如果你需要更严格的命令白名单和文件系统沙箱,请改用 Claude 后端(--backend claude),由security.py强制白名单。
本项目源自 Anthropic 的 quickstart 示例 autonomous-coding：
需要对照原始实现、查看英文说明或跟踪上游更新时，请以该上游为准。
git remote add upstream https://github.com/anthropics/claude-quickstarts.git
git fetch upstream- 技能驱动 - 在 Claude Code 中输入
/autonomous即可启动 - Codex 执行 - 所有编码工作由 Codex CLI 循环完成
- 双代理模式 - 初始化代理 + 编码代理协作
- 自动持久化 - 进度保存，可随时中断继续
方式 A：交互式创建（推荐）
/create-spec
AI 会引导你完成需求收集，自动生成 prompts/app_spec.txt。
方式 B：手动编辑
直接编辑 prompts/app_spec.txt，写清楚你想要的应用。
方式 A：Claude 技能（推荐）
/autonomous my_project
方式 B：命令行
python3 autonomous_agent_demo.py --project-dir generations/my_projectnpm install -g @openai/codex
pip install -r requirements.txt推荐 Python 3.11+；3.10 及以下会自动使用
tomli兼容解析 toml。
venv/bin/python -m compileall -q -x "venv|generations" .
venv/bin/python -m unittest discover -v -s tests
venv/bin/python test_security.pyCodex CLI 支持多种认证方式，按优先级顺序：
- 环境变量 -
OPENAI_API_KEY - auth.json -
~/.codex/auth.json - 第三方渠道 -
~/.codex/config.toml（如 yunyi）
如果使用第三方激活渠道（如 yunyi），在 ~/.codex/config.toml 中配置：
model_provider = "yunyi"
model = "gpt-5.2"
[model_providers.yunyi]
name = "yunyi"
base_url = "https://yunyi.cfd/codex"
wire_api = "responses"
experimental_bearer_token = "YOUR_TOKEN"程序会自动检测并加载第三方凭证，无需设置环境变量。
| 参数 | 说明 | 默认值 |
|---|---|---|
--project-dir |
项目目录 | generations/autonomous_demo_project |
--max-iterations |
最大迭代次数 | 无限制 |
--model |
模型名称 | gpt-5.2-codex |
-
初始化代理（会话 1）： 读取
app_spec.txt，创建包含 200 个测试用例的feature_list.json，设置项目结构，并初始化 git。 -
编码代理（会话 2+）： 从上次会话中断处继续，逐个实现特性，并在
feature_list.json中标记为通过。
- 每个会话都使用全新的上下文窗口
- 进度通过
feature_list.json与 git 提交持久化 - 代理在会话间自动继续（3 秒延迟）
- 按
Ctrl+C可暂停；再次运行相同命令可继续
本演示采用纵深防御安全策略（见 security.py 和 client.py）：
- OS 级沙箱： Bash 命令在隔离环境中运行
- 文件系统限制： 文件操作仅限项目目录
- Bash 允许列表： 仅允许特定命令：
- 文件检查：
ls、cat、head、tail、wc、grep - Node.js：
npm、node - 版本控制：
git - 进程管理：
ps、lsof、sleep、pkill（仅限开发进程）
- 文件检查：
补充规则：
- 禁止命令替换与进程替换（如
`...`、$(...)、<(...)）以防绕过白名单 rm仅允许安全的相对路径删除（禁止/、~、..等）
不在允许列表中的命令会被安全钩子阻止。
注意：Codex 后端默认使用
--dangerously-bypass-approvals-and-sandbox（高权限）。如需更严格的沙箱与白名单，请使用 Claude 后端。
autonomous-coding/
├── autonomous_agent_demo.py # 主入口
├── agent.py # Agent 会话逻辑
├── base_client.py # 抽象客户端接口
├── claude_client.py # Claude SDK 后端
├── codex_client.py # Codex CLI 后端
├── client_factory.py # 客户端工厂
├── security.py # Bash 命令白名单验证
├── progress.py # 进度追踪工具
├── prompts.py # Prompt 加载工具
├── prompts/
│ ├── app_spec.txt # 应用规格说明
│ ├── initializer_prompt.md # 初始化会话 Prompt
│ └── coding_prompt.md # 编码会话 Prompt
├── requirements.txt # Python 依赖
└── .env.example # 环境变量模板
运行后，你的项目目录将包含：
generations/my_project/
├── feature_list.json # Test cases (source of truth)
├── app_spec.txt # Copied specification
├── init.sh # Environment setup script
├── claude-progress.txt # Session progress notes
├── .claude_settings.json # Security settings
└── [application files] # Generated application code
代理完成（或暂停）后，你可以运行生成的应用：
cd generations/my_project
# Run the setup script created by the agent
./init.sh
# Or manually (typical for Node.js apps):
npm install
npm run dev应用访问地址以终端输出或 init.sh 为准（Vite 项目常见是 http://localhost:5173）。
| 选项 | 描述 | 默认值 |
|---|---|---|
--backend |
后端类型 | codex |
--project-dir |
项目目录 | generations/autonomous_demo_project |
--max-iterations |
最大代理迭代次数 | 无限制 |
--model |
模型名称 | Codex: gpt-5.2-codex，Claude: claude-opus-4-5-20251101 |
编辑 prompts/app_spec.txt 以指定要构建的不同应用。
编辑 prompts/initializer_prompt.md，将“200 个特性”的要求改为较小数量以加快演示。
编辑 security.py，在 ALLOWED_COMMANDS 中添加或移除命令。
当测试通过时，代理可以向 N8N webhook 发送进度通知。这对于监控长时间运行的代理会话很有用。
在 .env 文件中添加 webhook URL：
PROGRESS_N8N_WEBHOOK_URL=https://your-n8n-instance.com/webhook/your-webhook-id当测试进度增加时，代理会发送一个 POST 请求，JSON 结构如下（按 N8N 的期望包装为数组）：
[
{
"event": "test_progress",
"passing": 45,
"total": 200,
"percentage": 22.5,
"previous_passing": 42,
"tests_completed_this_session": 3,
"completed_tests": [
"[Authentication] User can log in with valid credentials",
"[Dashboard] Display user profile information",
"[API] GET /users endpoint returns user list"
],
"project": "my_project",
"timestamp": "2025-01-15T14:30:00.000Z"
}
]| 字段 | 类型 | 描述 |
|---|---|---|
event |
string | 始终为 "test_progress" |
passing |
number | 当前通过的测试数量 |
total |
number | 测试总数 |
percentage |
number | 完成百分比（0-100） |
previous_passing |
number | 本次更新前通过的测试数量 |
tests_completed_this_session |
number | 自上次通知以来完成的测试数量 |
completed_tests |
array | 新通过测试的描述 |
project |
string | 项目名称（来自 --project-dir 参数） |
timestamp |
string | ISO 8601 时间戳（UTC） |
- 通知仅在进度增加时发送（不会每次检查都发送）
- 如果未配置 webhook URL，不会发送通知（静默跳过）
- webhook 调用失败会记录日志，但不会停止代理
"首次运行看起来卡住了"
这是正常现象。初始化代理正在生成 200 个详细测试用例，需要较长时间。观察 [Tool: ...] 输出以确认代理正在工作。
"命令被安全钩子阻止"
代理尝试运行不在允许列表中的命令。安全系统按预期工作。如有需要，在 security.py 的 ALLOWED_COMMANDS 中添加该命令。
"Codex 后端不可用" 检查凭证配置：
python3 -c "from codex_client import CodexAgentClient; print(CodexAgentClient.get_credential_info())"应返回 {'source': 'config.toml', 'provider': 'yunyi'} 或类似信息。
"API key 未设置" 请确认以下任一配置：
- 环境变量
OPENAI_API_KEY ~/.codex/config.toml中的第三方渠道配置.env文件中的ANTHROPIC_API_KEY（Claude 后端）
代理具备三层自动闭环能力，无需人工干预即可完成任务：
- 完成检测：当
feature_list.json中所有测试通过时自动停止 - 初始化自愈：若初始化未生成测试清单，自动重试（最多 2 次）
- 停滞检测：连续 5 轮无进展时进入修复模式，修复 2 轮仍无效则停止
- 首次运行耗时：初始化代理生成 200 个测试用例需 10-20 分钟
- 应用类型：目前仅针对 Node.js/Web 应用优化
- 命令白名单：Bash 命令受
security.py白名单限制 - 上下文窗口：每个会话使用全新上下文，不保留历史对话
- 进度依赖：依赖
feature_list.json跟踪进度，删除该文件会重置进度
本项目基于 MIT License 开源。原始代码源自 Anthropic 的 quickstart 示例， 版权归原始作者和贡献者所有。