问题排查

按"你看到的症状"组织。快速定位到接近的一条，跟着"怎么修"走一遍。修不了的再去「常见问题」或提工单。

执行相关

执行一直 PENDING，不变 RUNNING

先查：

1. 看「执行历史」顶部有没有"达到并发上限"的提示。Free 并发 1 / Pro 5 / Team 15 —— 你的同时跑数量有没有达到上限？
2. 看这条 workflow 有没有 manual_approval 步骤卡在最前面。
3. 让它再等 30 秒 —— 偶发瞬时。超过 2 分钟还 PENDING 的提工单。

执行失败：credential_not_found

怎么修：

1. 看 error_message 里提示的凭据名。
2. 打开凭据中心 —— 这个名字的凭据真的存在吗？大小写、下划线 / 短横线都要一致。
3. 你是否在"团队命名空间"里建了凭据，但当前你是 Viewer 角色？Viewer 不能引用凭据。
4. 清单上有就是没被解析到 —— 退出重新登录一次刷新权限。

执行失败：rate_limit_exceeded

原因：你或平台的 LLM Provider 限流被触发。

怎么修：

1. 在失败的 step 上加 retry 策略：

- id: call_llm
  type: single
  agent: writer
  retry:
    max_attempts: 3
    backoff: exponential
    initial_delay_ms: 2000
    retry_on: [rate_limit, http_5xx]

2. 如果经常 rate_limit，BYOK 升级 Provider 账户 Tier 是根本解法。
3. batch 跑很多任务时用 sub_workflow + max_parallel 控制并发。

执行失败：timeout

原因：单个 step 超过它的 timeout 值，或整个 execution 超过 workflow 级 timeout。

怎么修：

• code step：在 step 上显式加 timeout 字段（单位秒，默认 30）。
• LLM step：可能是模型生成太长；减小 max_tokens 或用更快的模型。
• 整个 workflow 慢：在顶部加 timeout 字段（单位秒，默认 3600）。

Agent 输出空 / 不合理

先查：

1. 执行详情 → 点这个 step → 看"Agent tool_call 历史"，是不是被引导到了错误的工具。
2. 看 input 变量是不是空了 —— 上游 step 被 condition 跳过了？
3. 调整 temperature：推理 / 分类任务 0–0.3；创意 0.6–0.9。
4. task 描述加更具体的 few-shot 例子。
5. 试试换更强的 model（claude-opus-4-7 / gpt-5）。

code step 报 permission denied 或 network error

code step 在隔离沙箱里跑，限制：

• 文件系统只读 —— 只有 /tmp 可写；
• 网络只出不进（不能监听端口）；
• CPU / 内存 / 运行时间有上限。

怎么修：permission denied 通常是你尝试写 /tmp 之外的路径 —— 改成 /tmp/something。network error 多数是沙箱封禁了你的目标 host（平台有 egress 白名单），可提工单加白名单。

保存与编辑相关

保存时提示"YAML 与 DAG 不一致"

意味着你手改了 YAML 后不满足 round-trip 规则。常见原因：

• 用了 camelCase 字段名（应该是 snake_case）
• 引用了已删除的 preset 或 agent
• depends_on 指向了不存在的 step id

点"验证"按钮会给出精确行号 —— 按错误定位修。

编辑器打不开 / 一直转圈

1. 刷新一下。通常瞬态。
2. 看状态栏显示"xxx 正在编辑" —— 别人拿着编辑锁。等他 5 分钟无操作自动释放，或联系对方。
3. Admin 可以在团队设置里"强制解锁"。
4. 清浏览器缓存 / 换浏览器测试。

AI 助手给的 diff 应用后验证失败

Ctrl / Cmd + Z 回滚 —— 编辑器支持多级撤销。然后把错误消息 + 原 YAML 粘回给助手，它会修。

调度 / Webhook 相关

cron 到点没触发

1. 调度详情页「下次触发时间」是否与预期一致？时区配错是最常见原因。
2. 「最近 10 次触发历史」有没有记录？没有的话可能是 workflow 被 Archive 或删除了。
3. 看 workflow 的状态 —— 是不是被 pause 了？pause 的调度仍然计数，但不会真触发。
4. 用"立即触发一次"按钮手动验证 workflow 本身没问题。

Webhook 触发返回 401 / 403

1. API Key 方式：Authorization: Bearer 或 X-API-Key 头带的 key 对不对？key 是否已过期、是否有 WEBHOOK_TRIGGER 范围？
2. HMAC 兼容方式：你是否用 HMAC-SHA256 对 raw body 算了签名，放 X-Webhook-Signature 头？格式是 sha256=<hex>。注意：绑定了 API Key 的 webhook 不再接受 HMAC 签名。
3. URL path 里的 webhook ID 写对了吗？对应 workflow 是否被删？

Webhook 触发 200 但执行没起来

200 只代表"请求被收下"，执行可能被拒绝：

• workflow 是否 pause；
• 本套餐是否达到并发 / 调度配额；
• body 映射到 variables 时校验失败（必填缺失 / 类型错）。

Webhook 触发日志 —— 调度详情页「历史」Tab，能看到平台收到请求后解析的详情。

审批相关

manual_approval 永远不推通知

1. 「通知配置」页有没有绑定 Slack / 飞书 / 邮件任一 channel？
2. 审计日志 → 过滤 approval_notify_failed —— 看通知为什么发不出去（webhook url 失效？邮箱退信？）。
3. approvers 列表空时默认向"所有 Admin 及以上"通知 —— 你账号是不是其中一个？

我批准了但工作流没继续

审批后工作流应该在 10 秒内继续。超过 1 分钟没继续：

1. 刷新一下执行详情页，是否已经是 RUNNING？
2. 系统正在忙可能排队 30 秒 —— 等等。
3. 超过 5 分钟提工单。

团队 / 权限相关

切换团队后看不到工作流

工作流是按团队隔离的 —— 不会跨团队显示。确认你切对了团队（右上角下拉）。如果是"个人"切到"团队"，你需要在团队里重新建工作流或从个人移动过去。

同事说没权限改某个工作流

他在这个团队是 Viewer 角色吗？Viewer 只读。Admin 给他升到 Editor 即可。

我不是 Owner，但我想转移我创建的 workflow

"移动到团队"需要你在目标团队有 Editor 以上。自己加入目标团队即可。

支付 / 账单

信用卡扣款失败

1. 账单页 → 「重试扣款」。3 次失败后套餐会暂时降级到 Free —— 只要你在 14 天内成功扣款会自动恢复。
2. 中国卡可能被 Stripe 风控，换支付宝 / 微信支付。

发票抬头填错了

次月开票前可以在账单页改抬头。已开出的发票需要邮件到 billing@braidrun.com 申请作废重开。

都试过还是不行

1. 右下角"帮助"→ 提工单。自动附上浏览器环境 + 最近 execution ID。
2. Enterprise 套餐 → 直接联系专属 CSM。