执行失败排查

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：crates/cheng-engine、crates/cheng-api/src/rest/handlers/execution、crates/cheng-api/src/ws/protocol.rs

系统装好了、编辑器也能用，但某次运行没有达到预期。本文就是诊断路径。

方法

几乎所有执行失败，都可以通过先回答一个问题来定位：失败的那个节点，收到的输入是你以为的那些吗？

1. 打开执行记录，点击失败的节点。
2. 阅读错误以及它实际收到的输入。
3. 如果输入不对，问题在上游——顺着连线回溯，检查那个节点的输出。
4. 如果输入没问题，那么问题出在该节点的配置或某个外部服务上。

这个顺序很重要，因为一个报出令人费解错误的节点，通常是被塞了意料之外的东西。先研究错误信息、后检查输入，是很多人白白搭进一个下午的原因。

到哪里去看

读懂节点状态

skipped 往往是正确的，而不是故障。如果你期望运行的节点被跳过了，请检查上游的 utils/condition_router 以及它实际求值出了什么——路由节点做的是它的条件所说的事，而那未必是你想表达的意思。

读懂执行状态

停在 waiting_for_review 的运行是在正常工作：某个工具返回了 requires_review: true。在编辑器的审批卡片中回答，在 CLI 中用 /approve，或调用 POST /executions/:id/approve。

常见失败

模型节点立即失败

首次运行中最常见的失败。按可能性排序：

1. 该供应商没有配置凭证。
2. 模型名供应商无法识别。
3. 工作流假定了某项供应商能力，但供应商并未声明——特别是在 Anthropic 或 Ollama 上使用 use_function_calling = true 的智能体，这两者未声明原生 function calling。参见模型配置。
4. 因为 ALLOW_PRIVATE_LLM_ENDPOINTS=false 而被拦截的本地模型端点。
5. 供应商侧的频率限制或额度耗尽。

你配置的字段被忽略

有连线接到了那个输入端口。连线优先于手动输入的值——字段渲染为只读的「已连接」指示器，正是为了提示这一点。如果你确实想输入字面值，请删除那条连线。

输出里出现了字面的 {{variable}}

名称与任何可达的上游输出都不匹配。请使用变量选择器而不是手工输入名字；选择器会列出在图中那个位置真正可用的值。

运行无法启动

该工作流已有一次执行处于 running、paused 或 waiting_for_review 状态。请先取消或处理它。GET /executions/active 会列出占用名额的运行。

超时

节点任务默认有 300 秒超时。执行进入 timeout 状态意味着某个节点超出了时间预算——通常是缓慢的外部 API、过大的模型请求，或一个在等待永远不会到来的输入的 shell 命令。请拆分工作，或减少单步中要求节点完成的事情。

沙箱与文件错误

文件工具被限制在工作区沙箱内。这里的错误意味着：

• 路径在沙箱之外。
• CHENG_CLI_ALLOWED_ROOTS 未设置（CLI 会话被完全禁用）。
• CLI 与 API 在不同的文件系统命名空间中看待该路径。
• 会话是只读的（--read-only）。

代码节点不可用

检查 CHENG_ENABLE_CODE_PYTHON 和 CHENG_ENABLE_CODE_JS。

智能体相关的失败

智能体失败时需要的是事件流，而不只是 trace 输出——轨迹告诉你发生了什么，事件流告诉你它卡在哪里。关注 AGENT_ITERATION_COMPLETED、TOOL_EXECUTION_* 和 CONTEXT_WINDOW_STATUS_UPDATED。

恢复与重试

用 POST /executions/:id/cancel 取消。重试一次失败的执行会从失败点继续，并产生一个新的执行 id——失败的记录会作为证据完整保留，而不会被覆盖。

轨迹是持久的，因此关闭浏览器不会丢失长时间的智能体运行。编辑器会在重连时重新加入事件流。如果事件流静默 30 秒，客户端会与 API 对账而不是无限等待——所以一个永远不结束的加载图标是客户端问题，未必意味着运行真的卡住了。

当所有请求都返回 403

403 DEMO_MODE_RESTRICTED 意味着 CHENG_DEMO_MODE=true，它按白名单拒绝执行和写入。这是配置问题，不是权限问题。

下一步

• 执行模型——为什么节点按那个顺序运行。
• 测试与调试——编辑器提供的工具。
• 安装问题排查——问题出在安装而非运行时。