工作节点本地推理¶

工作节点回合通常通过 Gateway 代理模型请求。已配置的配对设备配置文件可以改为选择工作节点推理，使用相同的准入、回合声明、本地编码工具、转录提交、实时事件和节点监督器。没有单独的运行时服务器或网络协议。

您的平台拥有主机、容器或 Pod 及其修订版本。内置的 device 提供者接管一个配对节点并释放逻辑租约；它不会创建、替换或删除平台工作负载。监督器仍然拥有其工作节点子进程和受管工作区。每个信任边界使用专用节点账户。工作区授权不是操作系统沙箱：以该账户运行的代码具有其正常的文件系统和进程访问权限。

部署与凭据信任契约¶

将受信任的 OpenClaw Gateway 保持在不受信任的工作节点工作负载之外。配对节点及其工作节点运行原生循环和编码工具；它们不构成与以同一操作系统用户运行的代码之间的凭据隔离边界。此类代码可能访问启动文件、环境和进程内存。私有启动管道和输出脱敏不会改变该信任边界。

在此部署中，外部凭据保管方或提供商代理必须在工作负载之外持有实际的提供商密钥。配置节点的模型端点以访问该服务，并仅将该服务的作用域受限的不透明认证值配置到节点中。OpenClaw 通过所选提供商适配器传递这些值；它不会将它们解释为提供商密钥、将其解析为密钥，或实现保管方。原生提供商操作使用其自身的传输策略，而不是 Gateway 的进程本地机密标记解释或受保护获取/SSRF 策略，包括嵌入式循环导入 Gateway 辅助函数时。Gateway 请求保留其现有策略。因此，已配置的端点和工作负载出站限制属于部署信任决策。原生提供商请求要求 HTTPS，保持在已配置的端点源上，并拒绝所有重定向，包括同源重定向。配置最终端点 URL。仅允许对字面回环 IP 地址（而非如 localhost 的 DNS 名称）使用纯 HTTP，用于受信任的同主机跳转或隔离的链路证明。该例外不是外部凭据隔离边界。常规 TLS 证书和主机名验证保持启用。适配器特定的认证封装和 HTTP 头规则仍然适用。不要在节点或工作节点上配置实际的提供商密钥。

启动检查会检查传输策略和命名认证值的存在；它无法区分原始提供商密钥和不透明令牌，无法证明保管方，也无法执行工作负载的操作系统出站限制。否则，任何非空的命名值都会满足凭据存在要求。仅限 broker 的保管规则是一项部署要求，而不是 OpenClaw 在技术上验证密钥来源的声明。

部署负责 Gateway 和保管方的隔离、工作负载出站、端点信任、令牌签发、作用域、过期、吊销以及提供商凭据轮换。任何能够读取工作负载令牌的人都可能行使该令牌外部授予的权限。OpenClaw 工作区/模型授权、回合取消和输出脱敏补充该部署策略；它们不会吊销已暴露的令牌，也不会替代外部授权。该外部服务的配置和实时验证不属于此核心功能范围。

配置节点¶

Windows 工作节点本地推理已推迟。Windows 节点不会通告此能力；请在那里使用 Gateway 推理。现有通过 Gateway 代理的工作节点保留其当前行为。Windows 支持需要单独的、可选加入的凭据传输实现和原生验证。

安装匹配的 Gateway 和节点构建，并正常配对节点。将外部保管方的不透明认证值放入节点服务的预配置启动环境中，而不是 Gateway 配置或配置文件设置。通过节点的 openclaw.json 中熟悉的顶层 models.providers 字段配置端点和模型目录，然后启用工作节点托管：

{
  models: {
    providers: {
      openai: {
        api: "openai-completions",
        baseUrl: "https://credential-proxy.example.test/v1",
        apiKey: "${WORKER_PROXY_AUTH}",
        models: [
          {
            id: "worker-model",
            name: "Worker model",
            contextWindow: 32768,
            maxTokens: 4096,
            reasoning: true,
            thinkingLevelMap: { low: "low", high: "high" },
            input: ["text", "image"],
            cost: { input: 2, output: 8, cacheRead: 1, cacheWrite: 2 },
          },
        ],
      },
    },
  },
  nodeHost: {
    workerRuns: {
      enabled: true,
      capacity: 1,
      isolation: "none",
    },
  },
}

外部平台可以在容器内运行节点。OpenClaw 的额外嵌套容器工作节点模式不支持本地推理。保持节点配置和服务环境仅由服务账户可读。对于受信任的私有代理 CA，通过节点服务的 NODE_EXTRA_CA_CERTS 配置只读 CA 捆绑包，或使用其 NODE_USE_SYSTEM_CA 设置。现有工作节点环境保留这些设置；它不会继承 NODE_OPTIONS 或通用的 HTTP_PROXY / HTTPS_PROXY 变量。将兼容的代理端点显式配置为 baseUrl，并且永远不要禁用证书验证。

将端点替换为外部保管方的兼容 API，并使用其模型元数据。价格按每百万 Token 计。apiKey 使用与普通 OpenClaw 模型配置相同的字面量、环境变量插值和受支持的 SecretRef 形式；配置外部作用域的代理值，而不是原始提供商密钥。可选的提供商和模型 headers 也是节点本地启动值。所有已配置的 HTTP 头值都会保守地受到保护，避免出现在工作节点诊断和协议输出中。

在 models.providers 下，每个具有可用凭据的兼容模型都可在此节点上用于 worker 本地轮次。没有第二个工作区/模型允许列表。监督者将精确的已准入工作区投射到每个子进程，并且节点和 worker 都会检查其规范身份。模型配置不会从工作区、轮次请求、Gateway 身份验证配置文件或 dotenv 文件加载。

节点在启动时对其规范模型配置和已解析的身份验证值进行快照。轮换需要通过你的平台生命周期进行受控的节点/worker 替换；它不会修改正在运行的快照。私有启动载体在工具执行前被移除，以避免意外继承，而不是为了将其与同用户代码隔离。工作区准备、仓库设置以及无关的代理 worker 不会继承它。

在 Gateway 上选择放置¶

使用已配对设备 ID 配置显式设备配置文件：

{
  models: {
    providers: {
      openai: {
        api: "openai-completions",
        models: [
          {
            id: "worker-model",
            name: "Worker model",
            contextWindow: 32768,
            maxTokens: 4096,
            reasoning: true,
            thinkingLevelMap: { low: "low", high: "high" },
            input: ["text", "image"],
            cost: { input: 2, output: 8, cacheRead: 1, cacheWrite: 2 },
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/worker-model" },
      models: { "openai/worker-model": { agentRuntime: { id: "openclaw" } } },
    },
    entries: { assistant: {} },
  },
  cloudWorkers: {
    profiles: {
      "dedicated-native": {
        provider: "device",
        settings: {
          device: "PAIRED_DEVICE_ID",
          inference: "worker",
        },
      },
    },
  },
}

Gateway 副本为此自定义模型引用提供运行时元数据，以便其授权该选择并准备工具。保持这些能力与节点定义一致，但将 baseUrl、apiKey 和机密 headers 仅保留在节点配置中。已存在于 Gateway 目录中的模型不需要此额外元数据条目。

使用 worker 代理身份验证创建并分发¶

使用已认证的操作员 CLI/API 连接，以及配置了 OpenClaw 运行时的默认模型。配置文件分发需要 operator.admin。创建会话时不包含初始消息或显式 model/agentRuntime 选择，将其分发到已配置的配置文件，然后提交其第一个轮次：

openclaw gateway call sessions.create --json \
  --params '{"agentId":"assistant","label":"native-work","worktree":true,"worktreeSource":"empty"}'

# Replace SESSION_KEY with the key returned by sessions.create.
openclaw gateway call sessions.dispatch --json --timeout 240000 \
  --params '{"key":"SESSION_KEY","agentId":"assistant","profileId":"dedicated-native"}'

# Wait for placement.state to be active before sending.
# Use a fresh idempotencyKey for each new turn.
openclaw gateway call agent --json --timeout 180000 \
  --params '{"agentId":"assistant","sessionKey":"SESSION_KEY","message":"Say hello from the worker.","deliver":false,"idempotencyKey":"native-work-turn-1","timeout":120}'

# Replace RUN_ID with the runId returned by agent; acceptance is not completion.
openclaw gateway call agent.wait --json --timeout 195000 \
  --params '{"runId":"RUN_ID","timeoutMs":180000}'

空工作区由会话拥有。对于基于仓库的会话，请改用仓库创建/分发流程，仍然省略初始消息和显式 model/runtime 选择。选择 profileId，而不是普通配对设备目标：普通设备放置仍然保持代理。

在 Control UI 中，选择命名的 worker 推理配置文件，并保留 agent 的已配置模型和 OpenClaw 运行时默认值。配置文件和激活的放置标识 worker 推理，而不暴露提供商设置或凭据。现有会话使用其绑定环境记录的选项，而不是后续对配置文件的编辑。已停止、已回收和不精确的放置不会建立当前 worker 推理绑定。

当前限制：显式 model/runtime 选择仍使用 Gateway 模型可用性和身份验证检查；worker 代理身份验证值无法满足这些检查。显式 agentRuntime 需要显式规范 model 和可用的 Gateway 运行时选项。模型选择器不是节点模型配置的目录。使用上述已配置默认流程；不要将 worker 身份验证值复制到 Gateway，也不要禁用身份验证检查以使显式选择通过。这些是选择时检查：它们不会使 Gateway 提供商身份验证成为继续已绑定 worker 推理会话的要求，包括先前已接受的模型选择。Gateway 身份验证、agent/model 授权、工具权限、会话和放置访问权限以及当前运行权限仍然适用。

启动携带一个受功能门控的推理选择和现有模型引用，而不是模型端点、headers 或提供商凭据。缺少本地配置、不可用模型、不兼容 worker 和提供商错误都会失败关闭。worker 和 Gateway 都拒绝本地轮次的代理回退。省略 settings.inference，或将其设置为 gateway，会保留默认值。

故障排除¶

worker 本地推理被有意设计为失败关闭。失败的轮次绝不会回退到 Gateway 推理，因为这会悄悄更改凭据保管和放置。使用下面第一个匹配的诊断，修复其责任方，然后重试或重启失败的 worker 放置。

| 诊断 | 需要修复什么 |

如果 Control UI 报告 Runner failed，请打开该诊断的放置详情。在不更改指定配置的情况下重启，会重复相同的失败。Gateway 日志不包含节点凭据，也不完整包含节点本地模型目录。

升级和降级¶

规范配置文件值为 gateway 和 worker；省略表示 gateway。 升级已发布安装不会启用 worker 推理或添加原生配置。已分配的环境保留其原始快照；配置文件编辑不会更改活动绑定。无需数据库重写或 schema 版本变更。

在启用该配置文件之前，请将 Gateway 和节点服务升级到支持 worker 本地推理的兼容构建。Gateway 会在配对的节点上安装其固定的 worker 捆绑包，并验证其构建回执；仅新增 worker 捆绑包不会升级节点 supervisor，也不会让较旧的节点获得原生启动配置。本地轮次需要 worker-local-inference-v1 能力，并且从不回退到不兼容 worker 上的 Gateway 推理。遵循正常的 worker 更新与恢复生命周期 以及你所在平台的节点服务替换流程。

在将任一服务降级到不包含此功能的构建之前：

1. 停止新提交，完成或停止活动轮次，并在兼容的 Gateway 和节点仍在运行时回收所有原生放置。使用 Stop cloud worker… 或现有 RPC：

openclaw gateway call sessions.reclaim --json --timeout 600000 \
  --params '{"key":"SESSION_KEY","agentId":"assistant"}'

等待成功协调以及 reclaimed 或 local 放置。离线设备或待拆除状态不是已确认释放；重新连接并解决清理后再继续。不要仅为了降级而强制销毁。

1. 从 cloudWorkers.profiles 中移除原生配置文件，并移除任何引用它们的默认值。移除配置文件不会更改活动环境记录的推理选择；请先回收它。如果 worker 专用模型条目和认证环境不再被普通节点本地 OpenClaw 操作使用，请通过平台生命周期将其退役。
2. 仅在该清理完成后再降级。较旧的 Gateway 不会将 settings.inference 解释为本地推理要求。不要留下原生放置或配置文件，让较旧的 Gateway 去恢复。任何后续的 Gateway 或代理轮次都需要其自身配置的 provider 凭据。

行为与限制¶

• 编码工具在 worker 中执行。现有授权和权限模式适用。交互式 exec 审批和 worker LLM 审查审批传输仍不受支持；需要审批的执行会被拒绝，而不是自动批准。
• 节点的规范模型配置拥有真实模型 API、输入能力、上下文窗口、输出 token 限制、价格和 thinking 支持。不支持的 thinking 和冲突的 token 预算覆盖会被拒绝。现有的 worker 重放投影会在规范 Gateway 转录中保留受支持的 provider 重放。
• 自动压缩和重试仍由现有 worker 运行时禁用。本地推理不会添加替代压缩路径。
• 需要环境端点配置和环境 Vertex ADC 标记凭据的 Azure 适配器会被拒绝。不会添加 provider 插件加载。
• 取消和替换使用现有 worker 围栏，并终止本地模型请求。在首次成功准入后，失去 Gateway 连接也会停止当前本地轮次。重新连接可以结算该中断轮次，但不会恢复其 provider 请求；新轮次需要新的准入。初始连接/准入重试仍受支持。Gateway 保留转录、确认和终态结算。
• 运行时会防护字面凭据反射，包括流片段和规范化值。这不是通用数据丢失防护，也不是针对以节点操作系统用户身份运行的代码的隔离边界。

验证¶

聚焦的编译进程证明使用一个隔离的真实 Gateway 服务、SQLite 转录、一个派生的 worker，以及一个回环 HTTP 模型 fixture：

node scripts/run-vitest.mjs run src/worker/native-worker.integration.test.ts

它覆盖本地 provider 调用和工具、转录持久化、拒绝、取消、替换，以及被代理的 sibling。这不是付费 provider、外部托管者隔离或实时平台部署测试。测试运行器通过其拥有的运行时图编译源 fixture；它不会在子进程中临时使用 TS loader。要验证实际的部署 bundle、安装程序和 node supervisor：

pnpm build
TEST_NATIVE_WORKER_BUNDLE=1 node scripts/run-vitest.mjs run src/worker/native-worker.bundle.integration.test.ts

可选通道使用受支持的预打包、SHA 寻址归档路径，并检查真实的安装程序、预热、supervisor 和 worker；它不会通过 HTTP 执行归档获取。如果缺少匹配的构建产物，它会失败。安装时请遵循常规的 node 和 worker 设置；此功能不会自动部署或重启服务。