Codex Agent Loop 架构解析：感知-决策-行动-记忆

Agent Loop 是什么

传统 AI 助手的工作模式是"一问一答"：用户输入 → 模型生成回答 → 结束。而 Agent Loop 是一个自主执行循环，模型会持续感知环境、做出决策、执行行动，直到任务完成。

用户: "把项目里所有的 console.log 替换为 logger.info"

传统 AI:
→ 生成一段 sed 命令给用户复制粘贴

Codex Agent Loop:
→ 循环1: 扫描项目，找到 47 个含 console.log 的文件
→ 循环2: 逐文件替换，记录修改
→ 循环3: 运行测试，发现 2 个测试失败
→ 循环4: 分析失败原因，修复测试
→ 循环5: 再次运行测试，全部通过
→ 循环6: 生成 git commit
→ 输出: 修改了 47 个文件，替换了 132 处，测试全部通过

四阶段执行循环

1. 感知（Perceive）

感知阶段收集完成任务所需的所有上下文信息：

# 伪代码：感知阶段
def perceive(task: str) -> Environment:
    env = Environment()
    
    # 解析任务意图
    env.intent = parse_intent(task)
    
    # 读取文件系统状态
    env.files = scan_workspace()
    
    # 检查运行环境
    env.runtime = detect_runtime()  # Node.js? Python? Docker?
    
    # 获取 Git 状态
    env.git = get_git_status()
    
    # 检查网络连通性
    env.network = check_network()
    
    return env

感知的具体内容：

感知项	示例	用途
文件结构	`src/`, `tests/`, `package.json`	确定项目类型和结构
运行时	Node.js v22, Python 3.12	选择正确的命令和语法
Git 状态	branch: main, 3 modified files	避免冲突，创建分支
依赖版本	React 19, Next.js 15	使用正确的 API
网络状态	GitHub 可达, npm 可达	判断能否安装包

2. 规划（Plan）

规划阶段将任务分解为可执行的子任务序列：

# 伪代码：规划阶段
def plan(task: str, env: Environment) -> list[Action]:
    actions = []
    
    # 示例任务："给项目添加单元测试"
    if not has_test_framework(env):
        actions.append(Action(
            tool="shell",
            command="npm install -D vitest @testing-library/react"
        ))
        actions.append(Action(
            tool="file_write",
            path="vitest.config.ts",
            content=generate_vitest_config(env)
        ))
    
    # 分析源文件，生成测试计划
    source_files = find_untested_files(env)
    for f in source_files:
        actions.append(Action(
            tool="code_agent",
            prompt=f"为 {f.path} 生成单元测试",
            context=f.read()
        ))
    
    # 运行测试
    actions.append(Action(
        tool="shell",
        command="npm test"
    ))
    
    return actions

规划算法的关键特性：

拓扑排序：确保依赖关系正确（先安装依赖，再写代码）
并行识别：独立任务可并行执行
条件分支：根据执行结果选择不同路径
回滚点：关键步骤前创建检查点

3. 行动（Act）

行动阶段执行规划中的每个 Action：

# 伪代码：行动阶段
def act(action: Action, context: Context) -> Result:
    if action.tool == "shell":
        result = execute_shell(action.command, timeout=30)
        return Result(
            success=result.exit_code == 0,
            output=result.stdout,
            error=result.stderr
        )
    
    elif action.tool == "file_write":
        write_file(action.path, action.content)
        return Result(success=True)
    
    elif action.tool == "code_agent":
        # 递归调用 Agent Loop 处理子任务
        return run_agent_loop(action.prompt, context)
    
    elif action.tool == "browser":
        return browser_action(action)
    
    elif action.tool == "api_call":
        return http_request(action.method, action.url, action.body)

工具调用链示例：

任务: "抓取 GitHub trending 页面并保存为 Markdown"

Action 1: browser.open("https://github.com/trending")
  → Result: page loaded, 25 repositories found

Action 2: browser.extract("repo names, descriptions, stars")
  → Result: [{name: "repo1", desc: "...", stars: 1234}, ...]

Action 3: file_write("trending.md", format_as_markdown(data))
  → Result: file written to /workspace/trending.md

Action 4: shell("wc -l trending.md")
  → Result: 127 lines

4. 观察（Observe）

观察阶段收集执行结果并决定下一步：

# 伪代码：观察阶段
def observe(result: Result, plan: list, context: Context) -> NextStep:
    context.add_observation(result)
    
    if result.success:
        # 成功，执行下一步
        if plan.has_next():
            return NextStep.CONTINUE
        else:
            return NextStep.COMPLETE
    else:
        # 失败，进入错误修复
        if should_retry(result.error):
            return NextStep.RETRY_WITH_FIX
        elif can_skip(result.error):
            return NextStep.SKIP
        else:
            return NextStep.ASK_USER

错误自修复机制

这是 Agent Loop 最有价值的能力。当执行失败时，Codex 不会直接报错，而是自动分析错误并尝试修复：

循环 1: 执行 npm install
  → ERROR: ERESOLVE unable to resolve dependency tree
  → react@19.0.0 conflicts with @types/react@18.2.0

循环 2: 分析错误
  → 依赖版本冲突，@types/react 需要升级到 19.x
  → 执行 npm install @types/react@19 --save-dev

循环 3: 再次执行 npm install
  → SUCCESS

错误修复策略矩阵：

错误类型	修复策略	示例
语法错误	定位行号，修正语法	`SyntaxError: unexpected }`
依赖冲突	升级/降级冲突包	版本不兼容
导入错误	修正 import 路径	`Module not found`
类型错误	添加类型标注或转换	`Type 'string' is not assignable`
权限错误	检查并修改权限	`EACCES permission denied`
网络超时	重试或切换镜像源	`ETIMEDOUT`
运行时错误	分析堆栈，修复逻辑	`TypeError: Cannot read property`

修复深度限制：

{
  "errorHandling": {
    "maxRetries": 3,
    "maxRepairDepth": 5,
    "escalateAfter": 3,
    "strategies": ["retry", "rewrite", "alternative_approach"]
  }
}

上下文管理

Agent Loop 需要管理大量上下文信息，这是工程上最复杂的部分。

上下文类型

类型	内容	生命周期
任务上下文	用户原始指令、分解的子任务	整个会话
环境上下文	文件结构、运行时信息	会话内更新
执行历史	每个 Action 的输入输出	滑动窗口
错误上下文	失败记录、修复尝试	修复完成后清除
用户偏好	编码风格、框架选择	永久（持久化）

上下文窗口策略

当上下文超过模型 token 限制时，Codex 采用分层策略：

Layer 1: 保留 [最近 5 轮交互] + [任务目标] + [当前文件]
         ↓ 超限时
Layer 2: 压缩 [执行历史] 为摘要
         ↓ 超限时
Layer 3: 移除 [已完成的子任务详情]
         ↓ 超限时
Layer 4: 摘要 [环境上下文]
         ↓ 超限时
Layer 5: 请求用户确认是否继续

# 上下文压缩示例
original_context = {
    "task": "重构认证模块",
    "files": ["auth.ts", "auth.test.ts", "middleware.ts", ...],  # 50 files
    "history": [action1, action2, ..., action100],  # 100 actions
    "errors": [error1, error2, error3]
}

# 压缩后
compressed_context = {
    "task": "重构认证模块",
    "files": ["auth.ts", "middleware.ts"],  # 仅保留当前相关
    "history": "已完成: 安装依赖, 修改 auth.ts, 运行测试(2失败)",  # 摘要
    "errors": [error3],  # 仅保留未解决的
    "current_step": "修复 auth.test.ts 中的 2 个失败测试"
}

任务规划算法

Codex 使用改进的 ReAct（Reasoning + Acting）算法：

Thought: 用户要求"创建一个 REST API"，我需要：
  1. 确定 API 框架（检测项目中是否已有）
  2. 创建路由结构
  3. 实现 CRUD 逻辑
  4. 添加错误处理
  5. 编写测试
  6. 运行测试验证

Action: 检查 package.json 中的依赖
Observation: 已安装 Express 4.21, 未安装测试框架

Thought: 项目使用 Express，需要安装测试框架。选择 vitest（快速、现代）
Action: npm install -D vitest supertest
Observation: 安装成功

Thought: 现在创建路由。按照 Express 最佳实践，使用 router 模块化
Action: 创建 src/routes/users.js
Observation: 文件已创建

Thought: 接下来实现 CRUD 逻辑
Action: 编写用户 CRUD 代码
...

并行任务执行

独立子任务可以并行执行：

# 伪代码：并行执行
parallel_actions = [
    Action(tool="code_agent", prompt="编写用户模型"),
    Action(tool="code_agent", prompt="编写产品模型"),
    Action(tool="code_agent", prompt="编写订单模型")
]

results = await asyncio.gather(*[
    act(action, context) for action in parallel_actions
])

与传统 RPA 对比

维度	传统 RPA (UiPath等)	Codex Agent Loop
任务定义	录制/编写固定流程	自然语言描述
适应性	遇到变化即失败	自动适应环境变化
错误处理	预设异常分支	AI 分析并自修复
维护成本	UI 变化需重新录制	自动适应
智能程度	按规则执行	按理解执行
适用场景	重复标准化流程	复杂非结构化任务
学习曲线	需要专业培训	自然语言即可
部署成本	$$$$	$

示例对比——“每天从三个网站抓取新闻并汇总”：

RPA 方式：

为每个网站录制操作流程（2小时/网站）
编写数据汇总脚本
设置定时任务
网站改版时重新录制（每月维护）

Codex 方式：

输入：“每天从 [网站1], [网站2], [网站3] 抓取科技新闻，汇总成 Markdown 文件发给我”
Codex 自动完成所有步骤
网站改版时 Codex 自动适配

性能优化

缓存策略

{
  "caching": {
    "enabled": true,
    "strategies": {
      "file_hash": true,        // 文件未修改则跳过重新读取
      "tool_result": true,      // 相同输入的工具调用缓存结果
      "model_response": true    // 相同 prompt 的模型响应缓存
    },
    "ttl": 3600
  }
}

提前终止

# 当置信度足够高时提前终止循环
def should_terminate(observations: list) -> bool:
    if all_tests_pass(observations[-1]):
        return True  # 测试全过，无需继续
    if consecutive_failures >= 5:
        return True  # 连续失败，停止避免死循环
    if total_cost > budget_limit:
        return True  # 超出预算
    return False

调试与可观测性

# 启用详细日志
codex --verbose "你的任务"

# 查看执行轨迹
codex --trace "你的任务" 2>&1 | tee trace.log

# 执行轨迹示例
[2026-06-25 10:00:01] PERCEIVE: task="重构 auth 模块"
[2026-06-25 10:00:02] PERCEIVE: detected Next.js 15 project, 23 files
[2026-06-25 10:00:03] PLAN: 5 subtasks identified
[2026-06-25 10:00:04] ACT: subtask 1/5 - create auth/ directory
[2026-06-25 10:00:05] ACT: subtask 2/5 - extract JWT logic to auth/jwt.ts
[2026-06-25 10:00:12] OBSERVE: file created successfully
[2026-06-25 10:00:13] ACT: subtask 3/5 - update imports in 8 files
[2026-06-25 10:00:45] OBSERVE: 8/8 imports updated
[2026-06-25 10:00:46] ACT: subtask 4/5 - run tests
[2026-06-25 10:01:02] OBSERVE: 15/16 tests passed, 1 failed
[2026-06-25 10:01:03] ACT: auto-repair - fix failing test
[2026-06-25 10:01:15] OBSERVE: test fixed, 16/16 passed
[2026-06-25 10:01:16] ACT: subtask 5/5 - git commit
[2026-06-25 10:01:20] COMPLETE: task finished in 79s

总结

Agent Loop 是 Codex 区别于传统 AI 助手的核心架构。它通过"感知-规划-行动-观察"的自主循环，实现了从"给建议"到"做事情"的质变。错误自修复能力让它在面对真实复杂环境时不需要人工干预，而上下文管理策略确保它在长任务中不会迷失方向。

理解 Agent Loop 的工作原理，是高效使用 Codex 的基础——你需要知道它不是在"聊天"，而是在"工作"。

加入讨论

这篇文章有姊妹讨论帖在硅基AGI论坛 — 全球首个碳基硅基认知交流平台。

碳基与硅基的智慧碰撞，认知差异创造无限可能。

Agent Loop 是什么#

四阶段执行循环#

1. 感知（Perceive）#

2. 规划（Plan）#

3. 行动（Act）#

4. 观察（Observe）#

错误自修复机制#

上下文管理#

上下文类型#

上下文窗口策略#

任务规划算法#

并行任务执行#

与传统 RPA 对比#

性能优化#

缓存策略#

提前终止#

调试与可观测性#

总结#

理解 Agent Loop 的工作原理，是高效使用 Codex 的基础——你需要知道它不是在"聊天"，而是在"工作"。#

加入讨论#

📌 相关推荐