Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix [Feature]: POST /api/sessions/spawn — fire-and-forget HTTP endpoint to spawn subagents [1 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#55481•Fetched 2026-04-08 01:39:05
View on GitHub
Comments
0
Participants
1
Timeline
2
Reactions
0
Author
vposteavpostea
Participants
vposteavpostea
Timeline (top)
cross-referenced ×1labeled ×1

Add a gateway HTTP endpoint that creates a session and fires an initial agent task asynchronously, returning the session key immediately without blocking on completion.

Root Cause

Add a gateway HTTP endpoint that creates a session and fires an initial agent task asynchronously, returning the session key immediately without blocking on completion.

Fix Action

Fix / Workaround

  1. agentTurn mode cron jobs — blocks until the subagent finishes, causing timeout failures at scale. The current workaround.
  2. WebSocket sessions.create + chat.send — requires maintaining a persistent WebSocket connection, which external scripts and cron jobs cannot easily do.
RAW_BUFFERClick to expand / collapse

Summary

Add a gateway HTTP endpoint that creates a session and fires an initial agent task asynchronously, returning the session key immediately without blocking on completion.

Problem to solve

The only way to spawn a subagent today is from inside an agent turn via sessions_spawn. Cron jobs that need to spawn agents must use agentTurn mode, which blocks waiting for the subagent to finish. At scale this causes timeout failures. External processes (scripts, webhooks, other services) have no way to spawn agents directly without going through the WebSocket RPC protocol.

Proposed solution

Add POST /api/sessions/spawn to the gateway's existing HTTP surface:

  • Authenticates via the same bearer token used for WebSocket connections
  • Accepts { agentId?, task, model?, label?, timeoutSeconds? }
  • Creates the session immediately (sessionId available at call time)
  • Fires the initial task asynchronously — does not wait for the agent to finish
  • Returns 202 Accepted with { sessionKey, sessionId }

The agent runs fully async; completion is push-based (same as existing subagent behavior). Callers get the session key and disconnect immediately.

Alternatives considered

  1. agentTurn mode cron jobs — blocks until the subagent finishes, causing timeout failures at scale. The current workaround.
  2. WebSocket sessions.create + chat.send — requires maintaining a persistent WebSocket connection, which external scripts and cron jobs cannot easily do.

Impact

  • Affected: Operators running cron jobs or external scripts that need to spawn agents without blocking; any external system (webhook receiver, API integration) that wants to trigger an agent run.
  • Severity: Blocks workflow at scale — cron jobs time out waiting for subagents.
  • Frequency: Every scheduled job that spawns a subagent.
  • Consequence: Cron jobs fail under load; no clean way to integrate external systems with the agent runtime without a persistent WebSocket.

Evidence/examples

Current cron payload (broken at scale): { "kind": "agentTurn", "message": "spawn and wait...", "timeoutSeconds": 120 }

With this endpoint, a cron job becomes a simple curl: curl -X POST https://gateway/api/sessions/spawn
-H "Authorization: Bearer $TOKEN"
-d '{"task": "run the daily report", "agentId": "worker"}' → 202 { "sessionKey": "agent:worker:dashboard:...", "sessionId": "..." }

Additional information

  • Auth reuses the existing gateway operator bearer token — no new auth surface.
  • The session is pre-registered before the agent starts, so sessionId in the 202 response is stable and can be used to poll session history immediately.
  • Fully backward-compatible — existing WebSocket sessions.create behavior unchanged.

extent analysis

Fix Plan

To implement the proposed solution, follow these steps:

  • Add a new endpoint POST /api/sessions/spawn to the gateway's HTTP surface.
  • Authenticate incoming requests using the existing bearer token used for WebSocket connections.
  • Accept the following parameters in the request body:
    • agentId: optional
    • task: required
    • model: optional
    • label: optional
    • timeoutSeconds: optional
  • Create a new session immediately and generate a unique sessionId.
  • Fire the initial task asynchronously without waiting for the agent to finish.
  • Return a 202 Accepted response with the sessionKey and sessionId.

Example code snippet in Node.js:

const express = require('express');
const app = express();
const asyncHandler = require('express-async-handler');

app.post('/api/sessions/spawn',
  authenticateBearerToken,
  asyncHandler(async (req, res) => {
    const { agentId, task, model, label, timeoutSeconds } = req.body;
    const sessionId = generateSessionId();
    const sessionKey = generateSessionKey(sessionId);

    // Create a new session and fire the initial task asynchronously
    createSession(sessionId, agentId, task, model, label, timeoutSeconds);

    res.status(202).json({ sessionKey, sessionId });
  })
);

// Helper functions
function authenticateBearerToken(req, res, next) {
  // Implement bearer token authentication
}

function generateSessionId() {
  // Implement session ID generation
}

function generateSessionKey(sessionId) {
  // Implement session key generation
}

function createSession(sessionId, agentId, task, model, label, timeoutSeconds) {
  // Implement session creation and initial task firing
}

Verification

To verify that the fix worked, test the new endpoint using a tool like curl:

curl -X POST https://gateway/api/sessions/spawn \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"task": "run the daily report", "agentId": "worker"}'

The response should be a 202 Accepted with the sessionKey and sessionId:

{
  "sessionKey": "agent:worker:dashboard:...",
  "sessionId": "..."
}

Extra Tips

  • Ensure that the createSession function is properly implemented to handle errors and edge cases.
  • Consider adding logging and monitoring to track the performance and reliability of the new endpoint.
  • Review the authentication and authorization mechanisms to ensure that they are secure and compliant with existing standards.

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#ssr#installation#tensor shape#autograd error

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 - 💡(How to fix) Fix [Feature]: POST /api/sessions/spawn — fire-and-forget HTTP endpoint to spawn subagents [1 participants]