fix: Pipeline stalls after triage — OpenClaw security envelope blocks tool calls (fixes #13)

alokemajumder · alokemajumder · commit f5f77283e162 · 2026-03-04T11:41:02.000+05:30
OpenClaw wraps webhook payloads in EXTERNAL_UNTRUSTED_CONTENT which tells
models not to execute tools from untrusted content. Our web_fetch callback
URLs were inside this envelope, so agents correctly refused to invoke them.

Two-layer fix:
- Add allowUnsafeExternalContent: true to all 6 hook mappings in openclaw.json,
  openclaw-airgapped.json, and install.sh template (safe: loopback + token auth)
- Restructure webhook messages to be data-only — callback URL templates now
  live in each agent's AGENTS.md system prompt, not the webhook payload
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- **Pipeline stalls after triage — OpenClaw security envelope blocks tool calls** (fixes #13): OpenClaw wraps webhook payloads in `EXTERNAL_UNTRUSTED_CONTENT` which instructs models not to execute tools mentioned within untrusted content. Our `web_fetch` callback URLs were inside this envelope, so agents correctly refused to call them. Fix: added `allowUnsafeExternalContent: true` to all 6 hook mappings (safe — webhooks are loopback-only and token-authenticated), and restructured webhook messages to be data-only (callback URL templates now live in each agent's AGENTS.md system prompt instead of the webhook payload).
+
 ### Added
 - **Provider policy notice and OpenRouter recommendation**: README, QUICKSTART, and openclaw.json now warn users that Anthropic and Google have banned subscription OAuth tokens in third-party agent tools. OpenRouter is recommended as the safest single-key option. Direct provider API keys (pay-per-token) still work fine.
 - **Stalled-pipeline detector**: Automatically detects cases stuck in transient statuses (open, triaged, correlated, etc.) for longer than a configurable threshold and re-dispatches the webhook to give the agent another attempt. Configurable via `STALLED_PIPELINE_ENABLED`, `STALLED_PIPELINE_THRESHOLD_MINUTES` (default 30), and `STALLED_PIPELINE_CHECK_INTERVAL_MS` (default 300000). New metrics: `autopilot_stalled_pipeline_detected_total`, `autopilot_stalled_pipeline_redispatched_total`.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
@@ -266,6 +266,33 @@ If `web_fetch` is only in agent allow lists but missing from the global allow li
 journalctl -u openclaw-gateway | grep "unknown entries"
 ```
 
+### Agent receives webhook but doesn't call web_fetch (EXTERNAL_UNTRUSTED_CONTENT)
+
+OpenClaw wraps all webhook payloads in a security envelope (`EXTERNAL_UNTRUSTED_CONTENT`) that instructs models **not** to execute tools or commands mentioned within the untrusted content. This is a safety feature to prevent prompt injection from external sources.
+
+**Problem:** If your `openclaw.json` hook mappings don't include `"allowUnsafeExternalContent": true`, the model sees the callback URL inside the security envelope and correctly refuses to call `web_fetch`. The agent outputs a text summary but never advances the pipeline.
+
+**Symptoms:**
+- Agent sessions show the model producing text analysis but never invoking `web_fetch`
+- Cases stay in `open` status despite triage agent running
+- Stalled pipeline detector fires repeatedly with no progress
+- Session logs show `stopReason: "stop"` (not `"error"`) with token usage > 0
+
+**Fix:** Add `"allowUnsafeExternalContent": true` to each hook mapping in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "match": { "path": "wazuh-alert" },
+  "action": "agent",
+  "agentId": "wazuh-triage",
+  "messageTemplate": "{{message}}",
+  "name": "Wazuh Alert Triage",
+  "allowUnsafeExternalContent": true
+}
+```
+
+This is safe because webhook payloads come from your own runtime service on loopback (`127.0.0.1`), authenticated by `hooks.token`. Apply to all 6 hook mappings. Version 2.4.4+ of the installer and reference configs include this flag by default.
+
 ### Stalled pipeline detector (automatic recovery)
 
 The runtime includes a stalled-pipeline detector that automatically re-dispatches webhooks for cases stuck in transient statuses (`open`, `triaged`, `correlated`, `investigated`, `planned`, `approved`). If a case remains in one of these statuses longer than the threshold, the detector re-sends the appropriate webhook to give the agent another chance.
diff --git a/install/install.sh b/install/install.sh
@@ -995,12 +995,12 @@ deploy_agents() {
     "path": "/webhook",
     "token": "$OPENCLAW_WEBHOOK_TOKEN",
     "mappings": [
-      {"match": {"path": "wazuh-alert"}, "action": "agent", "agentId": "wazuh-triage", "messageTemplate": "{{message}}", "name": "Wazuh Alert Triage"},
-      {"match": {"path": "case-created"}, "action": "agent", "agentId": "wazuh-correlation", "messageTemplate": "{{message}}", "name": "Wazuh Correlation"},
-      {"match": {"path": "investigation-request"}, "action": "agent", "agentId": "wazuh-investigation", "messageTemplate": "{{message}}", "name": "Wazuh Investigation"},
-      {"match": {"path": "plan-request"}, "action": "agent", "agentId": "wazuh-response-planner", "messageTemplate": "{{message}}", "name": "Wazuh Response Planning"},
-      {"match": {"path": "policy-check"}, "action": "agent", "agentId": "wazuh-policy-guard", "messageTemplate": "{{message}}", "name": "Wazuh Policy Check"},
-      {"match": {"path": "execute-action"}, "action": "agent", "agentId": "wazuh-responder", "messageTemplate": "{{message}}", "name": "Wazuh Action Execution"}
+      {"match": {"path": "wazuh-alert"}, "action": "agent", "agentId": "wazuh-triage", "messageTemplate": "{{message}}", "name": "Wazuh Alert Triage", "allowUnsafeExternalContent": true},
+      {"match": {"path": "case-created"}, "action": "agent", "agentId": "wazuh-correlation", "messageTemplate": "{{message}}", "name": "Wazuh Correlation", "allowUnsafeExternalContent": true},
+      {"match": {"path": "investigation-request"}, "action": "agent", "agentId": "wazuh-investigation", "messageTemplate": "{{message}}", "name": "Wazuh Investigation", "allowUnsafeExternalContent": true},
+      {"match": {"path": "plan-request"}, "action": "agent", "agentId": "wazuh-response-planner", "messageTemplate": "{{message}}", "name": "Wazuh Response Planning", "allowUnsafeExternalContent": true},
+      {"match": {"path": "policy-check"}, "action": "agent", "agentId": "wazuh-policy-guard", "messageTemplate": "{{message}}", "name": "Wazuh Policy Check", "allowUnsafeExternalContent": true},
+      {"match": {"path": "execute-action"}, "action": "agent", "agentId": "wazuh-responder", "messageTemplate": "{{message}}", "name": "Wazuh Action Execution", "allowUnsafeExternalContent": true}
     ]
   },
 
diff --git a/openclaw/openclaw-airgapped.json b/openclaw/openclaw-airgapped.json
@@ -232,48 +232,57 @@
     "enabled": true,
     "path": "/webhook",
     "token": "${OPENCLAW_WEBHOOK_TOKEN}",
+    // allowUnsafeExternalContent: Webhook payloads come from our own runtime
+    // on loopback, authenticated by hooks.token. Without this, OpenClaw wraps
+    // messages in EXTERNAL_UNTRUSTED_CONTENT which blocks tool invocations.
     "mappings": [
       {
         "match": { "path": "wazuh-alert" },
         "action": "agent",
         "agentId": "wazuh-triage",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Alert Triage"
+        "name": "Wazuh Alert Triage",
+        "allowUnsafeExternalContent": true
       },
       {
         "match": { "path": "case-created" },
         "action": "agent",
         "agentId": "wazuh-correlation",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Correlation"
+        "name": "Wazuh Correlation",
+        "allowUnsafeExternalContent": true
       },
       {
         "match": { "path": "investigation-request" },
         "action": "agent",
         "agentId": "wazuh-investigation",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Investigation"
+        "name": "Wazuh Investigation",
+        "allowUnsafeExternalContent": true
       },
       {
         "match": { "path": "plan-request" },
         "action": "agent",
         "agentId": "wazuh-response-planner",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Response Planning"
+        "name": "Wazuh Response Planning",
+        "allowUnsafeExternalContent": true
       },
       {
         "match": { "path": "policy-check" },
         "action": "agent",
         "agentId": "wazuh-policy-guard",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Policy Check"
+        "name": "Wazuh Policy Check",
+        "allowUnsafeExternalContent": true
       },
       {
         "match": { "path": "execute-action" },
         "action": "agent",
         "agentId": "wazuh-responder",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Action Execution"
+        "name": "Wazuh Action Execution",
+        "allowUnsafeExternalContent": true
       }
     ]
   },
diff --git a/openclaw/openclaw.json b/openclaw/openclaw.json
@@ -269,48 +269,60 @@
     "enabled": true,
     "path": "/webhook",
     "token": "${OPENCLAW_WEBHOOK_TOKEN}",
+    // allowUnsafeExternalContent: Webhook payloads come from our own runtime
+    // service on loopback (127.0.0.1), authenticated by hooks.token. Without
+    // this flag, OpenClaw wraps the message in an EXTERNAL_UNTRUSTED_CONTENT
+    // security envelope that instructs the model NOT to execute tools mentioned
+    // in the message — which blocks agents from calling web_fetch to advance
+    // the pipeline. Safe here because the webhook source is trusted internal.
     "mappings": [
       {
         "match": { "path": "wazuh-alert" },
         "action": "agent",
         "agentId": "wazuh-triage",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Alert Triage"
+        "name": "Wazuh Alert Triage",
+        "allowUnsafeExternalContent": true
       },
       {
         "match": { "path": "case-created" },
         "action": "agent",
         "agentId": "wazuh-correlation",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Correlation"
+        "name": "Wazuh Correlation",
+        "allowUnsafeExternalContent": true
       },
       {
         "match": { "path": "investigation-request" },
         "action": "agent",
         "agentId": "wazuh-investigation",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Investigation"
+        "name": "Wazuh Investigation",
+        "allowUnsafeExternalContent": true
       },
       {
         "match": { "path": "plan-request" },
         "action": "agent",
         "agentId": "wazuh-response-planner",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Response Planning"
+        "name": "Wazuh Response Planning",
+        "allowUnsafeExternalContent": true
       },
       {
         "match": { "path": "policy-check" },
         "action": "agent",
         "agentId": "wazuh-policy-guard",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Policy Check"
+        "name": "Wazuh Policy Check",
+        "allowUnsafeExternalContent": true
       },
       {
         "match": { "path": "execute-action" },
         "action": "agent",
         "agentId": "wazuh-responder",
         "messageTemplate": "{{message}}",
-        "name": "Wazuh Action Execution"
+        "name": "Wazuh Action Execution",
+        "allowUnsafeExternalContent": true
       }
     ]
   },
diff --git a/runtime/autopilot-service/index.js b/runtime/autopilot-service/index.js
@@ -1044,12 +1044,16 @@ async function updateCase(caseId, updates) {
       };
       const webhookPath = statusWebhooks[updates.status];
       if (webhookPath) {
+        // NOTE: Callback URLs are in each agent's AGENTS.md (system prompt), not here.
+        // OpenClaw wraps webhook content in EXTERNAL_UNTRUSTED_CONTENT which blocks
+        // tool invocations from the message body. Agents read case_id from the data
+        // below and use the URL templates from their system prompt.
         const statusMessages = {
-          triaged: `Correlate case ${caseId} (${evidencePack.severity} severity). Search for related alerts, identify attack patterns, then use web_fetch to call: http://localhost:${config.metricsPort}/api/agent-action/update-case?case_id=${caseId}&status=correlated`,
-          correlated: `Investigate case ${caseId} (${evidencePack.severity} severity). Perform deep analysis using MCP tools: check agent health, search security events, analyze threat indicators. Then use web_fetch to call: http://localhost:${config.metricsPort}/api/agent-action/update-case?case_id=${caseId}&status=investigated`,
-          investigated: `Plan response for case ${caseId} (${evidencePack.severity} severity). Review investigation findings and create a response plan. Then use web_fetch to submit the plan: http://localhost:${config.metricsPort}/api/agent-action/create-plan?case_id=${caseId}&title={url_encoded_title}&risk_level={risk_level}&actions={url_encoded_actions_json}`,
-          planned: `Evaluate proposed plan for case ${caseId} (${evidencePack.severity} severity). Check all policy rules, risk levels, and approval requirements. Then use web_fetch to submit your decision: http://localhost:${config.metricsPort}/api/agent-action/approve-plan?plan_id={plan_id}&approver_id=policy-guard&decision={allow|deny|escalate}&reason={url_encoded_reason}`,
-          approved: `Execute approved plan for case ${caseId} (${evidencePack.severity} severity). Check responder status, then execute the plan. Use web_fetch to call: http://localhost:${config.metricsPort}/api/agent-action/execute-plan?plan_id={plan_id}&executor_id=responder-agent`,
+          triaged: `New correlation task. Case ID: ${caseId}. Severity: ${evidencePack.severity}. Search for related alerts, identify attack patterns, and advance the pipeline per your AGENTS.md instructions.`,
+          correlated: `New investigation task. Case ID: ${caseId}. Severity: ${evidencePack.severity}. Perform deep analysis using MCP tools, then advance the pipeline per your AGENTS.md instructions.`,
+          investigated: `New response planning task. Case ID: ${caseId}. Severity: ${evidencePack.severity}. Review investigation findings and create a response plan per your AGENTS.md instructions.`,
+          planned: `New policy evaluation task. Case ID: ${caseId}. Severity: ${evidencePack.severity}. Check all policy rules, risk levels, and approval requirements per your AGENTS.md instructions.`,
+          approved: `New execution task. Case ID: ${caseId}. Severity: ${evidencePack.severity}. Execute the approved plan per your AGENTS.md instructions.`,
         };
         dispatchToGateway(webhookPath, {
           message: statusMessages[updates.status] || `Process case ${caseId} — status changed to ${updates.status}.`,
@@ -3354,8 +3358,14 @@ function createServer() {
           log("info", "triage", "Created new case from alert", { case_id: caseId, alert_id: alertId, severity });
 
           // Dispatch to triage agent via OpenClaw gateway
+          // NOTE: Callback URLs are NOT included in the webhook message because
+          // OpenClaw wraps webhook content in an EXTERNAL_UNTRUSTED_CONTENT security
+          // envelope that instructs models not to execute tools from untrusted content.
+          // Instead, each agent's AGENTS.md (loaded as system prompt) contains the
+          // callback URL templates. The agent reads case_id from this data and
+          // substitutes it into the URL pattern from its system prompt.
           dispatchToGateway("/webhook/wazuh-alert", {
-            message: `Triage new ${severity}-severity alert: ${caseData.title}. Case ${caseId} with ${entities.length} entities extracted. Analyze the alert, assess threat level, then use web_fetch to call: http://localhost:${config.metricsPort}/api/agent-action/update-case?case_id=${caseId}&status=triaged`,
+            message: `New triage task. Case ID: ${caseId}. Severity: ${severity}. Title: ${caseData.title}. Entities: ${entities.length} extracted. Follow your AGENTS.md instructions to triage this alert and advance the pipeline.`,
             case_id: caseId,
             severity,
             title: caseData.title,
@@ -4405,35 +4415,9 @@ async function checkStalledPipeline() {
 
       try {
         const evidencePack = await getCase(caseSummary.case_id);
-        const statusMessages = {
-          open: `[RETRY] Triage alert for case ${caseSummary.case_id}`,
-          triaged: `[RETRY] Correlate case ${caseSummary.case_id}`,
-          correlated: `[RETRY] Investigate case ${caseSummary.case_id}`,
-          investigated: `[RETRY] Plan response for case ${caseSummary.case_id}`,
-          planned: `[RETRY] Evaluate plan for case ${caseSummary.case_id}`,
-          approved: `[RETRY] Execute plan for case ${caseSummary.case_id}`,
-        };
-
-        // Build callback URLs — for statuses that need a plan_id, look it up from the evidence pack
-        const latestPlan = (evidencePack.plans || []).slice(-1)[0];
-        const planId = latestPlan?.plan_id || "";
-        const callbackUrls = {
-          open: `http://localhost:${config.metricsPort}/api/agent-action/update-case?case_id=${caseSummary.case_id}&status=triaged`,
-          triaged: `http://localhost:${config.metricsPort}/api/agent-action/update-case?case_id=${caseSummary.case_id}&status=correlated`,
-          correlated: `http://localhost:${config.metricsPort}/api/agent-action/update-case?case_id=${caseSummary.case_id}&status=investigated`,
-          // For investigated: don't include actions — let the agent build its own plan
-          investigated: `http://localhost:${config.metricsPort}/api/agent-action/update-case?case_id=${caseSummary.case_id}&status=investigated`,
-        };
-        // Only include plan-dependent URLs if we actually have a plan_id
-        if (planId) {
-          callbackUrls.planned = `http://localhost:${config.metricsPort}/api/agent-action/approve-plan?plan_id=${encodeURIComponent(planId)}&approver_id=policy-guard&decision=allow`;
-          callbackUrls.approved = `http://localhost:${config.metricsPort}/api/agent-action/execute-plan?plan_id=${encodeURIComponent(planId)}&executor_id=responder`;
-        }
-
-        let msg = `${statusMessages[caseSummary.status]} (${evidencePack.severity || caseSummary.severity} severity, stalled ${ageMinutes}m).`;
-        if (callbackUrls[caseSummary.status]) {
-          msg += ` Use web_fetch to call: ${callbackUrls[caseSummary.status]}`;
-        }
+        // NOTE: Callback URLs are in each agent's AGENTS.md (system prompt), not
+        // in the webhook message. See comment in updateCase() for rationale.
+        const msg = `[RETRY] Case ID: ${caseSummary.case_id}. Severity: ${evidencePack.severity || caseSummary.severity}. Status: ${caseSummary.status}. Stalled for ${ageMinutes}m. Follow your AGENTS.md instructions to process this case and advance the pipeline.`;
 
         dispatchToGateway(webhookPath, {
           message: msg,
