Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix sessions_spawn tool schema includes ACP-only fields that break non-native OpenAI providers [2 pull requests, 3 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#66719•Fetched 2026-04-15 06:24:44
View on GitHub
Comments
3
Participants
2
Timeline
9
Reactions
0
Author
Gi99linGi99lin
Participants
ArtyomkunArtyomkunGi99linGi99lin
Timeline (top)
commented ×3mentioned ×2subscribed ×2cross-referenced ×1

Error Message

  • Error: Strict schema validation failures on upstream providers

Fix Action

Fix / Workaround

Current Workaround

PR fix notes

PR #66720: fix: strip runtime-specific properties from sessions_spawn tool schema for provider compatibility

Description (problem / solution / changelog)

Problem

When OpenClaw sends the sessions_spawn tool schema to non-native OpenAI-compatible providers (e.g., via proxy gateways like OmniRoute → MiniMax, Codex proxy, or other OpenAI-compatible endpoints), the schema includes all runtime-specific parameters regardless of which runtimes are actually available:

  • ACP-only: streamTo, resumeSessionId
  • Subagent-only: lightContext, attachments (complex nested array of objects), attachAs

This causes strict-schema validation failures on providers that reject schemas with:

  • Complex nested object/array properties (attachments)
  • Too many optional parameters that waste model tokens
  • Unknown or unsupported schema keywords

Current Workaround

Users deploying OpenClaw behind proxy gateways (like OmniRoute) must run a separate request-sanitizer proxy that intercepts every API request and strips these properties from the tool schema before forwarding upstream. This adds operational complexity and an extra point of failure.

Solution

Add a simplifiedSchemaForGateway option that strips both ACP-specific and complex subagent properties from the sessions_spawn tool schema when they'd cause strict-schema validation failures:

  1. Define GATEWAY_STRIPPED_SCHEMA_PROPERTIES set containing all properties that cause issues (streamTo, resumeSessionId, lightContext, attachments, attachAs)
  2. Add simplifiedSchemaForGateway?: boolean option to createSessionsSpawnTool()
  3. Wire simplifiedSchemaForGateway through createOpenClawTools() so the production call path can activate schema stripping

Changes

  • sessions-spawn-tool.ts: Added buildSessionsSpawnSchema(), GATEWAY_STRIPPED_SCHEMA_PROPERTIES, and simplifiedSchemaForGateway option
  • openclaw-tools.ts: Added simplifiedSchemaForGateway option and wired it through to createSessionsSpawnTool()

Behavior

simplifiedSchemaForGatewaySchemaUse Case
undefined / falseFull schema (no change)Native OpenAI, local Codex
trueStripped schema (no streamTo, resumeSessionId, lightContext, attachments, attachAs)Proxy gateways, non-native providers

Backward Compatibility

  • Default behavior is unchanged — full schema is used unless simplifiedSchemaForGateway: true is explicitly passed
  • The execute() function still accepts all parameters regardless of schema (graceful degradation)

Fixes #66719

Changed files

  • src/agents/openclaw-tools.ts (modified, +7/-0)
  • src/agents/tools/sessions-spawn-tool.ts (modified, +54/-1)

PR #68397: fix(sessions_spawn): silently strip ACP-only fields for runtime=subagent

Description (problem / solution / changelog)

Summary

sessions_spawn currently hard-errors when runtime="subagent" receives streamTo or resumeSessionId, even though the subagent code path never consumes either field. Schema-strict providers (most notably gpt-5.4 via the OpenAI bridge) auto-fill every advertised tool parameter on every call regardless of the runtime value the model also picks, which makes subagent spawns fail 90%+ of the time for those models.

This PR switches the two ACP-only fields from "reject with error" to "silently drop when runtime!=='acp'". ACP semantics are unchanged — when runtime==='acp' the fields flow through unmodified and the existing ACP spawn logic validates them.

Why the silent-drop approach

  • The subagent branch never reads streamTo / resumeSessionId, so dropping them has no observable effect on the subagent code path.
  • Schema filtering per-runtime would be the cleaner long-term fix but requires reworking the shared tool-schema pipeline (tracked in #59225, #66719). Silent-drop unblocks affected users today without that churn.
  • Hard-erroring loses to a predictable failure mode that many downstream models cannot avoid — the model doesn't know the field is ACP-only because the schema doesn't tell it.

Related issues

Addresses (non-exhaustive):

  • #68275 — sessions_spawn auto-injects streamTo:"parent" for runtime="subagent"
  • #67248 — sessions_spawn(runtime="subagent") fails on 2026.4.14 with ACP-only streamTo under GPT-5.4
  • #64714 — sessions_spawn rejects subagent runtime when streamTo is auto-filled by strict-mode providers
  • #63120 — LLMs pass streamTo for subagent runtime causing 100% spawn failures
  • #61724 — sessions_spawn(runtime="subagent") fails with "streamTo is only supported for runtime=acp"
  • #60965 — sessions_spawn schema allows streamTo for runtime=subagent but execute rejects it
  • #59390 — unified schema exposes ACP-only streamTo to subagent spawns
  • #56193 — sessions_spawn(runtime="subagent") can receive ACP-only streamTo from tool-call bridge
  • #56326 — sessions_spawn exposes ACP-only fields and breaks runtime=subagent with schema-following models
  • #53370 — Make sessions_spawn more forgiving for ACP-only fields in subagent runtime
  • #43556 — Bug: streamTo in sessions_spawn breaks subagent runtime

Test plan

  • Updated existing rejects resumeSessionId without runtime=acp and rejects streamTo when runtime is not "acp" cases to assert the new silent-drop contract: the tool forwards to spawnSubagentDirect without the ACP-only keys and returns no error.
  • Unchanged: runtime=acp path still passes streamTo / resumeSessionId through to spawnAcpDirect (existing tests at lines 177, 226 still cover this).
  • Suggested: add an integration test that round-trips a runtime="subagent" call with streamTo="parent" through the tool-call bridge to catch future regressions at the schema layer.

Changed files

  • src/agents/tools/sessions-spawn-tool.test.ts (modified, +14/-10)
  • src/agents/tools/sessions-spawn-tool.ts (modified, +9/-16)

Code Example

{
  "name": "sessions_spawn",
  "parameters": {
    "properties": {
      "task": { ... },
      "streamTo": { "enum": ["parent"] },
      "mode": { "enum": ["run", "session"] },
      "resumeSessionId": { ... },
      "sandbox": { "enum": ["inherit", "require"] },
      "thread": { "type": "boolean" },
      "lightContext": { "type": "boolean" },
      "attachments": { "type": "array", "items": { "type": "object", ... } },
      "attachAs": { "type": "object", ... }
    }
  }
}
RAW_BUFFERClick to expand / collapse

Problem

When OpenClaw sends sessions_spawn tool schema to non-native OpenAI providers (e.g., via proxy gateways like OmniRoute → MiniMax, Codex proxy, or other OpenAI-compatible endpoints), the tool schema includes all runtime-specific parameters regardless of which runtimes are actually available:

{
  "name": "sessions_spawn",
  "parameters": {
    "properties": {
      "task": { ... },
      "streamTo": { "enum": ["parent"] },
      "mode": { "enum": ["run", "session"] },
      "resumeSessionId": { ... },
      "sandbox": { "enum": ["inherit", "require"] },
      "thread": { "type": "boolean" },
      "lightContext": { "type": "boolean" },
      "attachments": { "type": "array", "items": { "type": "object", ... } },
      "attachAs": { "type": "object", ... }
    }
  }
}

This causes issues with strict-schema providers that reject schemas with:

  • Complex nested attachments array of objects
  • Too many optional parameters that the model wastes tokens trying to fill
  • Unknown schema keywords

Current Workaround

We currently use a proxy (spawn-sanitizer) that intercepts OpenAI-format requests and strips the ACP-only properties (streamTo, mode, resumeSessionId, sandbox, thread, lightContext, attachments, attachAs) from the sessions_spawn tool schema before forwarding to the upstream provider.

Proposed Solution

Option A (minimal): Allow createSessionsSpawnTool() to accept an option to build a simplified schema when the deployment context is known (e.g., simplifiedSchema: true or availableRuntimes: ["subagent"]). When only subagent runtime is available, strip ACP-only fields (streamTo, resumeSessionId). When ACP is unavailable, also strip attachments/attachAs since they're currently unsupported for ACP anyway.

Option B (broader): Extend the existing unsupportedToolSchemaKeywords compat mechanism to also support stripping properties from specific tool schemas, not just top-level JSON Schema keywords.

Option C (dynamic): Have createSessionsSpawnTool detect whether ACP is enabled via policy/config and dynamically build the schema at tool registration time.

Environment

  • OpenClaw: latest main
  • Provider: OpenAI-compatible via OmniRoute gateway
  • API type: openai-completions
  • Error: Strict schema validation failures on upstream providers

extent analysis

TL;DR

Implementing a simplified schema for the sessions_spawn tool by stripping ACP-only fields when the deployment context is known can resolve strict schema validation failures on upstream providers.

Guidance

  • Identify the available runtimes in the deployment context to determine which fields to strip from the sessions_spawn tool schema.
  • Consider implementing Option A (minimal) by adding an option to createSessionsSpawnTool() to build a simplified schema based on the available runtimes.
  • Evaluate the feasibility of Option B (broader) or Option C (dynamic) for a more comprehensive solution, depending on the complexity and requirements of the project.
  • Verify the effectiveness of the simplified schema by testing it with strict-schema providers and monitoring for any validation failures.

Example

// Simplified schema example with ACP-only fields stripped
{
  "name": "sessions_spawn",
  "parameters": {
    "properties": {
      "task": { ... }
    }
  }
}

Notes

The choice of solution depends on the specific requirements and constraints of the project, including the complexity of the schema and the availability of runtimes.

Recommendation

Apply workaround by implementing Option A (minimal), as it provides a straightforward solution to the problem with minimal changes to the existing codebase. This approach allows for a simplified schema to be built based on the available runtimes, reducing the likelihood of strict schema validation failures on upstream providers.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#tensor shape#autograd error#model save/load#optimization

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix sessions_spawn tool schema includes ACP-only fields that break non-native OpenAI providers [2 pull requests, 3 comments, 2 participants]