前置说明：本文是 OpenClaw 实证系列的一篇，假设读者对沙箱、工具策略、执行审批有基本了解。没接触过也不影响阅读，涉及的概念都会在用到时说明清楚。
运行环境：所有实测均在 OpenClaw 2026.7.1-2 上完成，Agent 运行于 Docker 沙箱中，宿主机为 2 核 / 3.8 GB 内存的 Linux 机器。
一个能跑通 Demo 的 Agent，和能连续工作数小时的 Agent，差距不在模型，而在于四类工程能力。
这次我们把 OpenClaw 的各模块组装成一个真正能干活的研究 Agent，让它连续跑了几个小时。期间它经历了外部中止、上下文溢出、工具报错三种事故，最终仍然产出了完整的研究报告。复盘下来，支撑它稳定运行的并非运气，而是一套可拆解、可复用的架构。
核心洞察 ：本文所有结论可以归结为一句话------上下文是工作记忆，工作区是长期记忆。 任务进度必须落盘，否则一次溢出便前功尽弃。一个快速检验标准：把这个 Agent 的会话清空，它还能接着干吗？
全局：两张图看懂 OpenClaw 的可靠性架构
理解这套架构需要两个视角。先看动态视角------一次 Tool Call 在系统里是怎么流转的：
这张图可以拆成三段：
- 决策层：模型决定下一步做什么，旁边挂着三道护栏------上下文预算、工具循环检测、模型回退；
- 执行层：一次 Tool Call 只有三种出路------成功、错误、长任务，每种走不同的处理路径；
- 持久层：所有进度沉淀到工作区，构成唯一一条能穿越失败的回环。
这条链路的官方定义见 Agent loop · 智能体循环，其中也说明了运行如何按会话串行、以及提前结束的几种情形。
再看静态视角------可靠性由哪些层构成，以及每层能不能被强制：
| 层级 | 管什么 | 实现手段 | 能否强制 |
|---|---|---|---|
| ① 模型 / 供应商 | 模型调用本身能否成功 | SDK 重试、凭证轮换、模型 fallback | 部分可配 |
| ② Agent 决策 | 失败之后怎么办 | 错误分类、有限重试、换策略、幂等判断 | 靠模型自觉 |
| ③ 工具执行 | 命令怎么跑、跑多久 | 退出码、超时、后台、进程生命周期 | 配置可管 |
| ④ 上下文 | 别把窗口撑爆 | 输出限界、pruning、compaction、checkpoint | 配置 + 规则 |
| ⑤ 运行时 | 并发与恢复 | 队列、并发上限、循环检测、重启恢复 | 配置可管 |
| ⑥ 运维观测 | 出事之后能排查 | status、doctor、logs、transcript、trajectory | 工具可查 |
这张表最关键的信息是最右一列：六层中只有第②层（Agent 决策）依赖模型自觉，也就是唯一需要靠 AGENTS.md 来规范的一层。其余五层都可以通过配置或命令强制执行。
这条分界能挡住一类常见的设计错误------用提示词去做本该由配置做的事 。"不要删库"写在提示词里拦不住任何事；把 exec 从工具清单中移除，才是真正地移除。
下面按四类核心能力逐一展开。但在那之前，得先把地基说清楚：状态到底放在哪。
一、地基：状态放在哪，决定它能不能从失败里爬起来
搭建长期 Agent，首先要建立的直觉是------Run、Session Context、Workspace 是三条互不相干的生命周期。
| 概念 | 含义 | 特征 |
|---|---|---|
| Run | 一次执行的完整过程 | 可能被中止、超时或报错，结束后可重来 |
| Session Context | 模型本轮实际看到的对话内容 | 会增长，会溢出，会被裁剪 |
| Workspace | 磁盘上的文件目录 | 跨 Run、跨 Session 持久存在 |
一次任务里，三条线各走各的
一次研究任务的实际经过是：
- 第一次 Run ：被外部中止（
externalAbort=true）； - 第二次 Run ：撞上
Context overflow: prompt too large for the model； - 执行
/new开启新会话：任务继续，最终完成。
关键在于新会话并未从零开始 ------它开场的第一件事是读取工作区中的 reports/ 和 notes/，把上一轮做到哪里读回来，然后接着往下做。整个过程中，三个目录一直安静地躺在磁盘上，没有因为任何一次失败而消失。
结论：上下文可以丢，工作区不能丢
由此得出两条可直接应用的结论：
text
Run 挂了 ≠ Agent 状态全丢了
Context 爆了 ≠ 数据丢了这也解释了为什么"把上下文窗口做得更大"并非长任务的正解：窗口再大也有限，而且更大的窗口意味着更慢、更贵。真正的解法是让任务状态根本不依赖窗口。
二、长任务：别让一条命令卡死整个 Run
对应六层模型中的第③层（工具执行）。
最直接的问题是：一个 git clone 运行十分钟，整个 Run 就在那里干等着。
三种执行形态：前台等结果、超时被杀、后台交给 process
OpenClaw 的 exec 提供了三种执行形态（参数定义见 Exec tool · 执行工具），实测将它们放在同一个任务中跑了一遍：
表1 · 三种执行形态对比
| 形态 | 参数 | 实际结果 | 适用场景 |
|---|---|---|---|
| 前台 | 直接执行 sleep 2 |
同步返回，获取输出 | 短命令，需要立即知道结果 |
| 超时 | timeout=2，命令需运行 8 秒 |
2 秒后被终止，后续命令未执行 | 有明确时间上限的命令 |
| 后台 | yieldMs=1000 |
返回"仍在运行"及会话名，用 process poll 获取结果 |
长时间运行的任务 |
实测输出
text
# A. 前台：同步返回
exec: sleep 2; echo FOREGROUND_DONE
→ FOREGROUND_DONE（同步执行，输出立即返回）
# B. 超时：8 秒的命令，给 2 秒超时
exec: sleep 8; echo SHOULD_NOT_PRINT (timeout=2)
→ Command timed out after 2 seconds...
→ SHOULD_NOT_PRINT 未打印
# C. 后台：让出当前 Tool Call
exec: sleep 5; echo BACKGROUND_DONE (yieldMs=1000)
→ Command still running (session cool-daisy, pid 3988392)
process poll(单次等待 7 秒)
→ BACKGROUND_DONE
→ Process exited with code 0这里刻意没有列出超时场景的退出码和信号字段------本地构建对超时用的是哪个字段名未经确认，不预设。判断超时时以 Tool Result 的文本和 timedOut 类标志为准，而不是照搬其他版本文档里的字段名。
没有 process，exec 的后台能力就是摆设
process 工具是否存在，直接决定了 exec 后台能力是否有意义。 如果工具清单中没有 process，exec 就只能同步运行，yieldMs 和 background 获取的会话将无法被管理。长任务场景下，exec 和 process 必须成对出现。详见官方 Background process。
顺带一个值得记住的边界：官方明确说明，只有被转入后台的会话会被列出和保留，而且仅存在于内存、不落盘，进程重启即丢失。这一点在后面讲重启恢复时还会用到。
这里还撞到了一个配置机制。为 Agent 配置 tools.allow = ["read","write","exec","process"]，重启后执行 /tools verbose------process 并未出现。原因是全局 tools.allow 当时只有 ["exec","read","write"]。将 process 加入全局后，它才出现在工具清单中。
原则：Agent 级的 allow 只能在全局允许的范围内收窄，不能扩张。
多层配置之间取更严格者。实用价值在于：当某个工具始终不出现时，先检查上一层配置，而不是反复修改 Agent 自身的配置。
四种"失败"来自不同的层，不能用同一种方式应对
运行长任务时会遇到许多看起来都像"失败"的情况，但它们的成因和应对策略完全不同：
表2 · 四种失败形态的区分
| 现象 | 根本原因 | 所属层级 | 正确应对 |
|---|---|---|---|
| 命令返回非零退出码 | 命令自身失败（如路径不存在） | 命令层 | 查看 stderr，修正参数或换策略 |
| exec 超时被杀死 | Runtime 到点杀进程 | 工具执行层 | 先判断是"确实需要更久"还是"卡住了"；前者转后台，而不是一味加超时 |
| 命令转入后台 | 命令还活着，只是不阻塞 | 不是失败 | 用 process poll 查询结果 |
| 整个 Run 被外部取消 | 用户或系统主动中止 | 运行层 | 从工作区恢复，继续执行 |
外部中止的 Trajectory 记录
ini
aborted=true
externalAbort=true
timedOut=false
idleTimedOut=false
timedOutByRunBudget=false一眼可辨：这是外部取消，不是超时，更不是命令失败。分不清这几种情况，就会写出"失败了就整段重跑"的策略------既慢又危险，尤其是当中间已经执行过写操作时。
三、失败之后：先分类，再决定要不要重来
对应六层模型中的第②层（Agent 决策）和第①层（模型 / 供应商）。
三层 Retry 各管一段，只有一层归模型管
"重试"在 Agent 系统中至少指代三件不同的事：
表3 · 三层重试的分工
| 重试类型 | 所属层级 | 触发条件 | 谁来决定 |
|---|---|---|---|
| Transport Retry | 模型 / 供应商层 | HTTP 408 / 409 / 429 / 5xx | SDK 自动处理 |
| Agent Retry | Agent 决策层 | 工具报错后 | 模型决定是否换参数再试 |
| Recovery Retry | 运行时层 | Gateway 重启后 | 系统自动恢复中断的任务 |
官方 Retry policy 中有一条界限划分得非常清楚：重试针对单个 HTTP 请求（outbound provider calls），不针对整段多步流程。 底层帮你重发了一个请求，并不等于你的业务流程会自动重跑。
看到"OpenClaw 有自动重试"就以为流程失败会自愈，是一种危险的误解。多步流程的重试永远是 Agent 自身的决策，而这项决策必须有明确的边界。
能不能重放，比重试几次更重要
为 Agent 制定重试策略，核心问题不是"重试几次"，而是"这个操作能否重放"：
表4 · 操作的幂等性判断
| 操作类型 | 处理方式 | 判断依据 |
|---|---|---|
| 读取、查询、搜索 | 可以直接重试 | 多次执行结果一致 |
| 本地可验证的构建 | 可以有限次重试 | 重试后可用新结果验证 |
| 发送消息、创建记录、支付 | 禁止因"没看到结果"就重发 | 可能产生重复副作用 |
| 外部写操作，结果未知 | 先核实状态，再决定 | 超时后无法确定是否生效 |
最后一条最容易出事：命令超时了，你不知道它到底有没有生效。此时盲目重放比放弃更危险。正确的做法是先查询状态，确认没有执行成功再重试。
值得一提的是，OpenClaw 自己的实现就贯彻了这条原则。按官方 Model failover 的说明，当整条候选链只因过载而耗尽时，回复运行器可以在同一轮内重试整条链多次；但整轮重试只允许在工具执行或助手输出开始之前进行，以避免重复变更。也就是说，"一旦产生了副作用就不再整段重放"不是我们自己发明的纪律，而是运行时层面已有的设计取向。
实测：一次报错换来一次策略调整
我们设计了一个场景来检验模型的行为：要求它检查 .../repo/src/runtime.ts，并提前告知"这个路径可能不存在"；规则是禁止重复同一个失败调用，应使用 rg/find 去寻找真正的入口。
实际执行过程：
- 探测候选路径 → 确认不存在；
- 没有重试同一个路径 ，改用
ls列出目录结构； - 发现 runtime 不在
src/中，而在独立的container/目录下； - 沿启动链定位到真正的入口
container/agent-runner/src/index.ts； - 提供一条源码证据（文件头的 docstring），并将证据存入工作区。
验证出来的启动链是这样的：
bash
container/entrypoint.sh
→ exec bun run /app/src/index.ts < /tmp/input.json
container/agent-runner/package.json
→ "start": "bun src/index.ts"
src/index.ts
→ runPollLoop() (定义于 container/agent-runner/src/poll-loop.ts:78)这就是"把错误当证据"的典型表现------错误信息本身承载着信息量，它排除了一种可能性，应当用来引导策略调整，而不是作为"再试一次"的理由。
模型故障转移：没有 fallback 就如实记为单点故障
官方的模型故障转移分为两个阶段：先在 Provider 内进行凭证轮换 ，再走配置好的模型 fallback （Model failover）。
而显式的 /model xxx 属于严格的会话选择 ：据官方文档 Models CLI，用户选定的模型引用对该会话是严格的，一旦不可达就会明确报错，而不是悄悄沿着 agents.defaults.model.fallbacks 回退；只有配置的默认模型和 cron 主模型仍然走 fallback 链。手动 pin 模型的代价就在这里。
审计这套配置的结果是：只有主模型，没有配置任何 fallback。 与其为了"看起来高可用"而塞入未经验证的 provider，不如如实记录：
ini
MODEL_FAILOVER = 单点故障（未配置备用模型）只有真正调用成功过的模型才有资格进入 fallback 列表，否则故障时只会从一个错误演变成两个错误。
四、不失控：让上下文可以被主动放弃
对应六层模型中的第④层（上下文）。
这类问题的共同点是------模型自己不会主动喊停。
循环检测：主开关默认关闭，但压缩后的守卫一直在
据官方文档 Tool-loop detection，tools.loopDetection 下其实有两道协同的护栏，这一点容易被漏掉：
| 护栏 | 默认状态 | 作用 |
|---|---|---|
循环检测（enabled） |
关闭 | 监视滚动的工具调用历史，发现重复模式和对未知工具的反复重试 |
| 压缩后守卫 | 只要 enabled 没有显式设为 false 就生效 |
每次压缩重试后 arm，若在窗口内重复同样的（工具，参数，结果）三元组就中止本次 Run |
也就是说，即使你从未写过 loopDetection 配置块，压缩后守卫也在工作 ；反过来，显式写下 enabled: false 会把两道护栏一起关掉。这个区别在排查"上下文溢出 → 压缩 → 又回到同一个循环"时很关键。
开启主开关后，它会检测：重复的工具调用、重复的错误、无进展的模式、对不存在工具的反复重试。检测到循环时先告警，模式持续超过阈值后才阻断下一个工具周期。
表5 · 循环检测的可调参数
| 参数 | 默认值 | 作用 |
|---|---|---|
enabled |
false |
主开关（同时也控制压缩后守卫） |
historySize |
30 |
工具历史窗口大小 |
warningThreshold |
10 |
重复模式告警阈值 |
使用较小的模型时建议开启------小模型更容易陷入重复调用。本次为使用 Flash 模型的 Agent 开启了此功能。
Pruning 只动内存，Compaction 才写回磁盘
两者互为补充，都不是"把历史直接删掉"：
| 机制 | 作用范围 | 是否修改磁盘 |
|---|---|---|
| Pruning | 仅裁剪内存中的旧工具结果 | 不改写 transcript |
| Compaction | 总结旧对话，生成摘要 | 将摘要写回 transcript |
当前保持 compaction.mode = safeguard、reserveTokensFloor = 24000，未继续调优------在没有明确依据时，不要随意猜测这些阈值。
Checkpoint：把"重开一局"的成本降到最低
前面几条都是"省着用上下文"，而 Checkpoint 则是允许上下文被主动放弃。
做法很朴素：长任务中定期写入一个小文件记录进度。有了它，上下文溢出就不再是灾难------开启新会话，读取 checkpoint，接着往下做。
Checkpoint 建议用 Markdown 或 JSON，至少包含四个字段：
已完成事项 做过什么，别重复劳动
待完成事项 接下来从哪继续
证据路径 产出和原始材料在哪
阻塞点 卡在哪，新会话不必重新踩坑收官任务中，Agent 在写最终报告之前先落了一个 3.4 KB 的 notes/checkpoint-mission019.md，内容正是这四类信息。
五、长期运行：并发、恢复与可观测
对应六层模型中的第⑤层（运行时）和第⑥层（运维观测）。
前三类解决的是单次任务的问题，这一类管的是系统层面能否长期稳定运行。
队列保证会话串行，并发上限要按机器给
据官方文档 Command queue，关键保证是：
arduino
同一个 session key → 同时最多一个 active run（会话通道串行）
跨 session → 可以并行
全局并发 → 由 agents.defaults.maxConcurrent 控制表6 · 当前并发配置审计
| 配置项 | 当前值 |
|---|---|
agents.defaults.maxConcurrent |
4 |
subagents.maxConcurrent |
8 |
cron.maxConcurrentRuns |
8 |
| 宿主机资源 | 2 核 / 3.8 GB 内存 |
原则很简单：不要因为官方默认值更大就盲目提高并发。 可靠性的目标是并发够用，但不会导致 OOM、Provider 429 或大量任务争用。本次仅做审计，不改动数值------在小机器上，并发是最容易把自己搞垮的旋钮。
顺便说一句，/status 会直接显示当前队列状态（Queue: steer (depth 0)），这是判断是否有任务堆积的最快方式。这里的 steer 是队列模式之一------它决定"新消息到达时，是插进正在跑的这一轮，还是排队等下一轮"；官方提供 steer / followup / collect / interrupt 四种模式。
重启恢复：哪些状态在磁盘上，哪些只在进程里
据 Restart recovery，跨 Gateway 重启会保留的内容是：
bash
持久（在磁盘上）
对话历史 · transcript · 被中断的会话状态 · 子 Agent 注册表
后台任务记录 · 待投递消息 · 定时任务 · 重启续跑能力
不持久（仅在进程内）
Gateway 终端 PTY
后台 exec 会话列表（仅内存，进程重启即丢失）官方还给出了几个值得记住的数字：openclaw gateway restart 并不会立刻杀掉在途工作，而是先停止接收新任务，再等待活跃的 Agent 轮次和后台任务结束，默认排空预算 5 分钟 ；启动时的重连对暂时性失败重试 3 次并指数退避 ；每个被中断的主会话另有3 次持久化派发预算 ，预算耗尽后会话会被标记为墓碑状态，需要用 /new 或 /reset 换一个新会话，而不是无限重试下去。
进行了一次安全的重启冒烟测试（使用 gateway restart，而非 stop + start），重启后研究产物完好无损------因为它本就存储在磁盘上，与 Gateway 的进程状态无关。这再次印证了地基一节的核心结论。
可观测性：七个手段回答七个问题
表7 · 可观测性工具清单
| 工具 | 回答的问题 | 使用时机 |
|---|---|---|
gateway status --require-rpc |
网关是否存活、监听在哪里 | 每次部署后 |
status --all |
整体健康、Agent 数、会话数 | 日常巡检 |
doctor |
配置是否存在隐患 | 每次升级 Node 或版本管理器之后 |
| logs | 运行时为何失败 | 出问题时 |
| tasks | 后台任务处于什么状态 | 出问题时 |
| Transcript | 具体交换了什么内容 | 审计 / 调试 |
| Trajectory | 这一轮的运行时元数据 | 审计 / 调试 |
各命令的完整用法见 Gateway。
实测发现 ：gateway status 直接报出了两个隐患------服务的 PATH 中包含版本管理器，且 Node 来自 nvm。这意味着版本管理器升级之后，服务可能无法正常启动。
这类问题在平时完全无感，只有在某次自动更新之后才会爆发。定期运行一次 doctor，比出事后排查日志要便宜得多。
六、分界：能强制的，别靠自觉
以上所有内容，最终落在"约束应该写在哪一层"这个问题上。
表8 · 三类约束的对比
| 约束类型 | 载体 | 作用方式 | 适用内容 | 风险 |
|---|---|---|---|---|
| 软约束 | AGENTS.md |
劝导模型 | 方法论、工作流程 | 模型可能不听或遗忘 |
| 硬约束 | Tool Policy | 移除工具能力 | 能力边界 | 配置错误导致任务无法完成 |
| 硬约束 | Sandbox | 限制执行环境 | 执行位置、文件访问 | 配置错误导致任务无法完成 |
分界原则：
能强制的，别靠自觉。
方法论写进 AGENTS.md，能力清单交给 Tool Policy，危险动作交给 Sandbox。写在提示词里的"不要删库"拦不住任何事；把 exec 从工具清单中移除，才是真正的移除。
七、把守则写进 AGENTS.md，再验证它真的生效
以上内容不能只停留在文档中，必须成为 Agent 每次运行都能看到的协议。因此我们在 AGENTS.md 中追加了一份可靠性守则：
markdown
## 可靠性守则
### 错误处理
- 将工具错误视为证据，而非"再试一次"的许可
- 区分：输入/路径错误、暂时性故障、超时、结果不明的写操作
- 同一错误重复出现，就该换策略了
### 重试
- 只重试当前这一步，不要重跑整个流程
- 同一种策略最多尝试 2 次
- 非幂等的外部写操作，绝不盲目重放
- 结果不明时，先核实状态再决定
### 长任务
- 长命令必须设置明确的超时
- 能用后台就不要一直阻塞
- 不要使用紧密轮询
- 跑偏的后台任务要主动终止
### 上下文
- 限制工具输出大小，优先使用 rg/grep/sed/head，不要一次性倾倒整个文件
- 证据、进度、中间结论持续写入工作区
- 上下文是工作记忆，工作区是长期记忆
- 上下文耗尽时开启新会话从工作区续做，不要重复已完成的部分
### 收尾
- 不要仅凭"我认为做完了"就宣布成功
- 检查文件、命令结果、可观察的副作用
- 被卡住就保留部分证据，并明确说明卡在哪里需要说明："同一种策略最多 2 次"是本 Agent 的工程策略，不是 OpenClaw 的官方默认值。OpenClaw 自身的 HTTP 重试是另一层机制，两者不要混淆。
收官任务：30 次调用、1 次报错，行为模式全对
写下守则后，我们让 Agent 执行了一项相当繁重的任务：将此前研究报告中标记为"未验证 / 推断"的结论，逐条回到源码中进行核实。
表9 · 收官任务的运行数据（来自 Transcript 统计）
| 指标 | 实际值 | 说明 |
|---|---|---|
| 工具调用总次数 | 30 次 | 含 read、write、exec |
| 工具报错次数 | 1 次 | 复合命令中的 git log 返回 128 |
| 含工具调用的模型轮次 | 25 次 | --- |
| 单轮并行调用 | 4 次 | 一轮中同时发起 2--3 个调用 |
| 最终状态 | 正常收尾 | --- |
更值得关注的是它的行为模式：
① 开场先读工作区。 第一个动作是列出工作区目录，然后读取 reports/ 和 notes/------从持久记忆恢复，而不是假设自己还记得。
② 输出全程有界。 30 次调用中，几乎每条命令都带有 head、grep -n、sed -n '240,320p' 等限制输出范围的手段，没有一次将整个文件倒入上下文。
③ 出错立即换策略。 唯一一次报错是复合命令中的 git log 返回 128；下一次调用换成了 git status 2>&1 | head，加入了 stderr 重定向和输出限制------没有重复同一个失败的调用。
④ 写报告前先落 checkpoint。 在产出最终报告之前，先写了 3.4 KB 的 notes/checkpoint-mission019.md，记录已完成的工作和证据路径。
⑤ 最后验证产物再收尾。 报告完成后，又执行了一次 ls -l 确认文件确实存在且非空，然后才结束本轮工作。
最后这一点尤其值得强调： "模型说做完了"不是完成的证据，文件存在与否才是。
八、六个最容易让长期 Agent 散架的配置陷阱
基于本次实测，以下几类配置问题最容易让长期运行的 Agent 意外散架：
表10 · 配置陷阱与应对
| 陷阱 | 典型表现 | 正确做法 |
|---|---|---|
在 agents.defaults 中留下实验性配置 |
所有 Agent 和 Cron 继承极端参数 | 实验配置写到具体 Agent 项上，结束后立即收回 |
| 盲目提高并发数 | OOM、Provider 429、任务堆积 | 结合机器实际资源保守设置，先审计再调整 |
以为配了 workspaceAccess=rw 就只是"能写文件" |
沙箱内写入直接落盘到宿主机工作区 | 确实需要持久化产出时才用 rw，否则用 ro |
| 没配 model fallback 却以为有高可用 | 模型提供商故障时任务直接失败 | 只配置已验证凭证的备用模型，否则如实记录单点故障 |
| 改完配置未重启 / 未 recreate | 配置未生效，旧行为继续 | 修改后执行 gateway restart，涉及沙箱时再 sandbox recreate |
| pruning 参数设得过于激进 | 上下文被过早裁剪，模型丢失关键信息 | 保持官方默认或接近默认值 |
九、如果只带走三句话
第一，把状态放对地方。 上下文是工作记忆，工作区是长期记忆。任务进度必须落盘，否则一次溢出便前功尽弃。检验标准：把会话清空，它还能接着干吗？
第二，失败要先分类，再决定如何处理。 命令失败、超时、转入后台、运行被取消------这四件事产生于不同的层面；能重放和不能重放的操作，处理方式完全相反。分不清就只能"整段重来"，而这既慢又危险。
第三，能强制的别靠自觉。 六层可靠性中只有一层归模型管，剩下五层都有配置、命令和运行时机制。把该配的配上，再用 AGENTS.md 去补充那些无法通过配置表达的方法论。
一个真正能长期运行的 Agent，不是从不失败的 Agent，而是一个会失败、但不会失控的 Agent：每一步的错误都能被归类，每一次中断都能从磁盘上恢复，每一个"完成"都有可验证的副作用作为证据。
官方扩展阅读（简体中文）
- Agent loop · 智能体循环 --- 一次运行的完整链路、会话通道串行与提前结束的几种情形。
- Exec tool · 执行工具 ---
timeout、yieldMs、background与 host 解析。 - Background exec and process tool · 后台执行与 process 工具 --- 后台会话的生命周期与管理动作。
- Retry policy · 重试策略 --- 出站请求的重试边界与幂等性要求。
- Model failover · 模型故障转移 --- 凭证轮换与模型回退的两个阶段。
- Models CLI · 模型命令 ---
/model的严格选择语义与 fallback 链的关系。 - Tool-loop detection · 工具循环检测 --- 循环检测与压缩后守卫这两道护栏。
- Command queue · 命令队列 --- 会话串行、跨会话并发与四种队列模式。
- Compaction · 压缩 与 Session pruning · 会话修剪 --- 上下文的两种收缩方式。
- Restart recovery · 重启恢复 --- 哪些状态跨重启保留，以及恢复预算的上限。
- Gateway 运维手册 ---
status、doctor、日志与服务管理。