为什么要先搞懂数据流与变量管理

在 OpenClaw 的实际项目里，最容易出现的不是“节点不会拖”“动作不会选”，而是：

• 变量明明赋值了，下游读到的却是旧值或空值；
• 同名变量在不同子流程里互相覆盖，导致行为随机；
• 数据在 UI、技能、AI、关卡触发器之间传来传去，最后变成一团“线团”；
• 为了传一个值，把它写到全局，结果埋下难以排查的状态污染。

所以这篇《OpenClaw教程》聚焦一个核心：把 OpenClaw 的数据流想清楚，变量的上下文与作用域定清楚，数据的传递方式选对。只要这三件事做对，你的流程图会更稳定、更可复用，也更容易调试。

OpenClaw 中“数据从哪里来，到哪里去”的三层视角

把 OpenClaw 的数据流拆成三层来理解，会非常清晰：

1. 节点内部（Node-local）：一个节点执行时产生的输出数据（例如“命中目标”“随机数”“Raycast命中点”）。这类数据通常只对当前连线链路有意义。
2. 上下文（Context）：一次流程执行的“运行时包裹”，里面携带输入参数、临时状态、调用者信息等。它比节点局部更长寿，但通常只在当前流程调用链内有效。
3. 作用域变量（Scoped Variables）：为了跨节点、跨分支甚至跨子流程共享而存在的变量容器，按作用域不同分为局部/流程/对象/全局等（具体以你的 OpenClaw 项目配置与可用容器为准）。

从工程实践上讲：

• 短期值（只在几步之内用）：优先走节点输出/临时上下文；
• 中期值（需要跨分支、跨循环复用）：放入流程级/子流程级变量；
• 长期状态（需要跨场景/跨系统共享）：谨慎放入对象级或全局级，并建立命名规范与生命周期管理。

上下文（Context）：一次执行“带着走”的信息包

Context 通常包含什么

在 OpenClaw 的流程系统中，“上下文”更像是一次调用的参数与运行态集合，常见包含：

• 输入参数：例如开始执行时传入的 Target、Damage、Caster、Position；
• 调用链信息：当前是由哪个子流程触发、上一层是谁、是否处于循环等；
• 临时标记：例如“是否已播放动画”“是否已扣除一次体力”，避免重复执行；
• 错误/调试信息：用于追踪本次执行的关键路径。

什么时候该用 Context，而不是变量表

建议遵循两条规则：

1. 参数性质的值用 Context：例如“技能释放目标”“这次对话选择结果”。它们属于一次执行的输入/输出，天然应被当作上下文参数传递。
2. 不希望泄漏到下一次执行的值用 Context：例如一次射线检测得到的命中点，仅对这次判定有效；如果写进全局变量，很容易被下次覆盖或被其他系统误读。

示例：把“伤害计算”的输入都放在 Context

假设你有一个“ApplyDamage”子流程，需要以下信息：

• attacker（攻击者）
• target（受击者）
• baseDamage（基础伤害）
• damageType（伤害类型）

做法建议：

1. 在调用 ApplyDamage 时，通过“调用子流程/Invoke SubFlow”的节点把这些值作为参数传入。
2. 在子流程开头用“Get Context Param”类节点读取参数，之后所有计算只依赖这些上下文参数与子流程内部变量。
3. 子流程输出“finalDamage / isCritical”等结果时，用“Return/Set Output Param”返回给上层。

这样优点是：

• 子流程可复用，输入清晰；
• 不依赖外部全局变量，调试可控；
• 并行触发多次也不互相污染（每次执行各自带着自己的 Context）。

作用域（Scope）：变量到底“活”在哪一层

不同团队的 OpenClaw 项目可能会封装不同的变量容器，但工程上你可以用统一的思维来治理：变量必须有明确归属与生命周期。下面按常见层级给出实践建议（名称以你项目里实际的变量面板/容器为准）。

H3 流程局部（Flow/Graph Local）变量：最推荐的默认选择

适用场景：

• 跨多个节点共享；
• 需要在分支、循环里读写；
• 不希望离开当前流程后仍存在。

建议：

• 绝大多数“中间计算值”都应该放这里，例如：currentComboIndex、accumulatedTime、selectedOptionId。
• 对于循环变量（例如计数器），要明确初始化节点，避免复用上一次运行残留的值。

H3 子流程输入/输出参数：用来做“接口”，不是用来当缓存

如果你已经决定把逻辑拆成子流程，那么：

• 输入参数就是子流程的“函数入参”；
• 输出参数就是子流程的“返回值”。

不要把子流程参数当成临时仓库，否则上层调用者很难读懂你到底需要什么、会输出什么。

H3 对象/实体级（Object/Entity）变量：用于“状态”，避免用于“临时值”

适用场景：

• 角色当前 HP、耐力、等级、Buff 列表等；
• 与对象生命周期一致的状态；
• 多个流程都需要访问同一对象的数据。

建议：

• 对象变量要有严格命名：如 Stat.HP、Stat.Stamina、AI.AlertLevel。
• 对象变量的写入应集中在少数节点/子流程里（例如“属性系统子流程”），防止到处散写导致不可追踪。

H3 全局/会话级（Global/Session）变量：少用，但要用对

适用场景：

• 当前关卡 ID、全局难度、玩家设置（音量/画质）、全局任务进度等；
• 需要跨场景、跨对象读取。

风险：

• 状态污染：任何流程都能写，出现“谁最后写入谁生效”；
• 并行执行：多个事件同时触发时全局变量被覆盖；
• 回放/存档：全局变量往往需要额外纳入持久化。

建议：

• 规定全局变量只允许通过“管理子流程”读写，例如 GlobalState.SetQuestFlag(flagId, value)。
• 对全局变量进行前缀分区：Game.、User.、Quest.、Analytics.。

数据传递方式：四种常用手段与选择策略

在 OpenClaw 的图形流程里，数据传递通常可以归为四类。你不需要“都用”，而是要按数据生命周期与耦合程度选。

H3 1）节点连线输出（Output → Input）：最直观、最安全

特点：

• 数据只沿着连线向下游流动；
• 不会污染外部；
• 调试时沿线追踪最容易。

适合：

• 一次性数据：随机数、命中点、临时判断结果；
• 线性流程：A 产出结果 → B 使用。

建议：

• 如果一个值只被下游 1~2 个节点使用，优先用连线输出，不要急着写变量。

H3 2）写入流程局部变量（Set Local Var）：跨分支/循环共享

特点：

• 可在任意位置读取；
• 适合汇聚数据（例如多个分支都要写一个“最终选择结果”）。

适合：

• if/else 后续要用同一个值；
• 循环累加；
• 多处读、少处写的中间结果。

示例：分支汇聚

• 分支 A：玩家选择“攻击” → action = "Attack"
• 分支 B：玩家选择“防御” → action = "Defend"
• 分支结束后统一读取 action 进入执行阶段

这种情况下，用流程局部变量比在分支末端用复杂的连线汇聚更清晰。

H3 3）上下文参数传递（Invoke SubFlow / Return）：模块化与复用的关键

特点：

• 子流程变成“可复用函数”；
• 通过参数显式声明依赖；
• 减少对外部变量容器的耦合。

适合：

• 任何可复用逻辑：伤害、掉落、对话分支计算、UI 打开/关闭等；
• 需要明确输入输出边界的团队协作。

建议：

• 子流程参数命名要像函数签名：targetEntity、baseDamage、out_finalDamage；
• 输出参数控制在 1~3 个以内，太多说明子流程职责过大。

H3 4）共享状态容器（对象/全局变量）：跨系统共享，但要治理

特点：

• 任何地方都能读写（视权限而定）；
• 很强大，也最容易失控。

适合：

• “真实状态”必须被多个系统共同认知：HP、任务进度；
• 需要被保存/加载的长期数据。

建议：

• 写入点集中化：通过少数“写入接口子流程”完成；
• 配合事件/消息机制（如果项目中有）来通知变更，而不是各处轮询读取。

一套可落地的变量命名与分层规范（建议直接照抄到团队文档）

H3 命名规则：前缀 + 域 + 含义

推荐格式：<ScopePrefix>.<Domain>.<Name>

• ScopePrefix：L(Local)、E(Entity/Object)、G(Global)、C(Context Param 名不必加)
• Domain：Combat、UI、Quest、AI、Stat…
• Name：清晰名词或动宾短语

例子：

• L.Combat.comboIndex
• L.UI.selectedMenuId
• E.Stat.hp
• G.Quest.mainlineStage

H3 类型规则：不要让字符串扮演一切

• 枚举/整型 ID：用于选项、状态机状态，如 selectedOptionId: int
• 布尔：使用肯定式，如 isCritical、hasKey
• 数值：注明单位语义，如 moveSpeed_mps、cooldown_s

H3 生命周期规则：每个“可变变量”必须有初始化节点

尤其是流程局部变量：

• 在流程入口统一初始化（或在“On Start”分支初始化）；
• 不要依赖上一次执行残留值。

实操：构建一个“可复用的数据传递链”示例（从命中到扣血）

下面用一个常见玩法把数据流串起来，给你一个可以照着搭的结构：

H3 场景

玩家按下攻击键 → 进行命中检测 → 计算伤害 → 对目标扣血 → 播放受击反馈。

H3 推荐的数据流设计

1. 输入阶段（Context）

   • 在“Attack_Start”流程入口，将 attacker（通常是玩家实体）与 attackConfigId 作为上下文参数。

2. 命中检测（节点输出）

   • 使用检测节点（例如扇形检测/射线/碰撞体扫描），输出 hitTarget、hitPoint。
   • 若 hitTarget 为空，直接结束或进入挥空反馈。

3. 写入中间结果（流程局部变量）

   • 将 hitTarget 写入 L.Combat.hitTarget，将 hitPoint 写入 L.Combat.hitPoint。
   • 这样做的原因：后续可能有分支（是否暴击、是否破防、是否触发特效），多处都要读目标与命中点。

4. 调用子流程计算伤害（参数传递）

   • Invoke CalcDamage 子流程：

     • 输入：attacker、target=L.Combat.hitTarget、attackConfigId
     • 输出：finalDamage、isCritical

5. 应用伤害（对象变量/系统接口）

   • Invoke ApplyDamage 子流程：

     • 输入：target、finalDamage、damageType
   • 子流程内部集中写入对象变量：E.Stat.hp = E.Stat.hp - finalDamage
   • 如果项目有事件系统，同步触发 OnDamaged(target, finalDamage, hitPoint)

6. 反馈展示（尽量不写全局）

   • 受击特效、飘字、音效等使用 hitPoint 与 isCritical，走节点输出或局部变量读取即可。

H3 这样设计的好处

• CalcDamage、ApplyDamage 都是可复用模块；
• 命中检测产生的临时值不落全局；
• 真正的“状态变化”（HP）集中在 ApplyDamage 内，便于审计与回放。

常见坑与排查清单（调不出来时按这个顺序查）

H3 1）读到默认值：先查作用域是否一致

• 你写的是流程局部，但读的是全局（或相反）？
• 子流程里读了同名变量，但其实是子流程自己的局部变量？

建议：变量名带前缀分层（如 L. G. E.），能显著减少误读。

H3 2）值被覆盖：查是否有“多处写入点”

• 同一个变量是否在多个分支/多个事件入口都写？
• 并行触发时是否共享了同一全局变量？

解决：

• 把写入集中到一个子流程；
• 把“临时值”移出全局，改用 Context/局部变量。

H3 3）子流程行为诡异：查参数是否显式传入

• 子流程内部是否偷偷读取了外部全局状态？
• 输入参数是否遗漏（导致拿了旧上下文）？

解决：

• 给子流程加“入口参数校验”节点：为空则提前返回并输出错误码/日志。

H3 4）循环/计时器异常：查初始化与重入

• 计数器是否每次进入都归零？
• 同一流程是否可能重入（比如事件重复触发）导致局部变量被共享？

解决：

• 在入口统一初始化；
• 若存在重入，改用 Context 携带本次执行的临时计数，或引入执行实例 ID。

建议的“最小可用”数据流架构（适合新手快速稳定）

如果你刚开始做项目，又不想一上来就设计得很复杂，可以采用下面这套最小架构：

1. 默认用节点输出传值；
2. 跨分支/循环就用流程局部变量；
3. 复用逻辑一律拆子流程，并用参数传递；
4. 对象状态集中在少数系统子流程写入；
5. 全局变量只存“确实是全局”的东西，并强制走接口写入。

做到这五条，你的 OpenClaw 流程会自然呈现“上游输入清晰、下游输出明确、中间状态可追踪”的结构，也更符合系列《OpenClaw教程：从入门到实战的分层学习路线》里强调的“可复用、可维护、可扩展”。