Primary Error Manifestation

When attempting to invoke any tool via the OpenClaw API, the response returns an immediate error:

json { “error”: { “errorCode”: “INVALID_REQUEST”, “errorMessage”: “unknown agent id”, “latency”: “0ms”, “timestamp”: “2026-03-15T10:30:45Z” } }

CLI Reproduction

bash

Attempt 1: Direct tools catalog call

curl -X POST http://localhost:8080/api/v1/tools/catalog
-H “Content-Type: application/json”
-H “Authorization: Bearer ”
-d ‘{}’

Response:

{“error”:{“errorCode”:“INVALID_REQUEST”,“errorMessage”:“unknown agent id”,“latency”:“0ms”}}

bash

Attempt 2: Via CLI client

openclaw tools list

Output:

ERROR: tools.catalog 0ms errorCode=INVALID_REQUEST errorMessage=unknown agent id

Observed Tool Availability

When listed by the system, only session management tools appear available:

Available tools:

• message - 发送消息
• sessions_list - 列出会话
• sessions_history - 获取会话历史
• sessions_send - 向其他会话发消息
• session_status - 显示会话状态

Missing: All configured tools under the full profile (e.g., http_request, web_search, file_operations, etc.)

Configuration Verification

User reports configuration includes:

json { “tools”: { “profile”: “full” } }

Primary Cause: Missing or Invalid Agent ID in Request Context

The unknown agent id error indicates that the OpenClaw API requires an explicit agent_id field in the request context, but the client is not providing it. This is a regression introduced in version 2026.3.2 where the API enforcing stricter validation of the agent context.

Technical Failure Sequence

1. Request Initialization: Client sends request to /api/v1/tools/catalog
2. Context Validation Phase: OpenClaw’s API gateway validates the request context
3. Agent ID Lookup Failure: The middleware cannot find a valid agent_id in:
   • Request headers (X-Agent-ID)
   • JWT token claims (sub or agent_id field)
   • Session context
4. Early Rejection: Request is rejected at 0ms latency (pre-processing phase)

Code Path Analysis

Client Request ↓ [API Gateway Middleware] ↓ (validates request context) [AgentContextValidator] ↓ (checks agent_id presence) ✗ MISSING → throws INVALID_REQUEST

Architectural Changes in v2026.3.2

Version 2026.3.2 introduced stricter agent isolation requirements:

• Agent ID is now mandatory for all tool-related endpoints
• Previous versions defaulted to a system-level agent context
• Configuration-only ("profile": "full") approach no longer sufficient

Environment-Specific Triggers

Option A: Configure Agent ID in OpenClaw Configuration File

Before (~/.openclaw/config.json): json { “tools”: { “profile”: “full” } }

After: json { “agent_id”: “default-agent”, “tools”: { “profile”: “full” } }

Option B: Set Agent ID via Environment Variable

bash export OPENCLAW_AGENT_ID=“default-agent”

Restart OpenClaw service for changes to take effect

sudo systemctl restart openclaw

Option C: Configure via Command Line Flag

bash

For direct execution

openclaw start –agent-id default-agent

For Docker

docker run -e AGENT_ID=default-agent openclaw/server:2026.3.2

For Docker Compose

yaml services: openclaw: image: openclaw/server:2026.3.2 environment: - AGENT_ID=default-agent

Option D: Fix API Client Headers

If calling the API directly, include the X-Agent-ID header:

bash curl -X POST http://localhost:8080/api/v1/tools/catalog
-H “Content-Type: application/json”
-H “Authorization: Bearer ”
-H “X-Agent-ID: default-agent”
-d ‘{}’

Option E: Fix SDK Client Configuration

Python SDK: python from openclaw import Client

client = Client( base_url=“http://localhost:8080”, agent_id=“default-agent” # Required in v2026.3.2+ )

Node.js SDK: javascript const { Client } = require(‘openclaw’);

const client = new Client({ baseURL: ‘http://localhost:8080’, agentId: ‘default-agent’ // Required in v2026.3.2+ });

Step 1: Verify Configuration File

bash cat ~/.openclaw/config.json | jq ‘.agent_id’

Expected output: “default-agent” or valid UUID

Step 2: Verify Environment Variable

bash echo $OPENCLAW_AGENT_ID

Expected output: default-agent or valid UUID

Step 3: Test Tools Catalog API

bash curl -s -X POST http://localhost:8080/api/v1/tools/catalog
-H “Content-Type: application/json”
-H “X-Agent-ID: default-agent”
-d ‘{}’ | jq ‘.tools | length’

Expected output: > 0 (number of available tools)

Step 4: Verify via CLI

bash openclaw tools list

Expected output: List of tools including http_request, web_search, etc.

Step 5: Verify Tool Invocation

bash curl -s -X POST http://localhost:8080/api/v1/tools/execute
-H “Content-Type: application/json”
-H “X-Agent-ID: default-agent”
-d ‘{ “tool”: “http_request”, “params”: {“method”: “GET”, “url”: “https://example.com”} }’ | jq ‘.status’

Expected output: “success” or tool response

Expected Successful Response

json { “tools”: [ {“name”: “http_request”, “description”: “…”}, {“name”: “web_search”, “description”: “…”}, {“name”: “file_operations”, “description”: “…”} ], “profile”: “full”, “agent_id”: “default-agent” }

Pitfall 1: Configuration vs. Runtime Agent ID Mismatch

If the config file has agent_id but the environment variable is also set, the environment variable takes precedence in v2026.3.2. This can cause confusion when debugging.

Solution: Ensure consistency between config file and environment variables.

Pitfall 2: Docker Container Network Mode

When running in Docker with --network=host, environment variables may not propagate correctly on some orchestrators.

Solution: Explicitly pass -e AGENT_ID or use docker-compose.yml with environment: block.

Pitfall 3: JWT Token Claims Ignored

If your authentication system embeds agent_id in JWT claims, ensure the OpenClaw server has JWT validation configured to extract these claims:

json { “auth”: { “jwt”: { “extract_agent_id”: true, “claim_path”: “agent_id” } } }

Pitfall 4: Upgrading from Pre-2026.3.2

Existing configurations may not include agent_id. After upgrade, add it to the config file:

bash

Migration script

jq ‘. + {agent_id: “default-agent”}’ ~/.openclaw/config.json > ~/.openclaw/config.json.new mv ~/.openclaw/config.json.new ~/.openclaw/config.json

Pitfall 5: Multiple Agent Environments

In multi-tenant setups, each agent must have a unique agent_id. Reusing default-agent across tenants causes ID collisions.

Solution: Use UUIDs or tenant-specific identifiers: bash export AGENT_ID="$(uuidgen)" # Linux/macOS

Related Historical Issues

• v2026.2.x: Agent ID was optional; tools defaulted to system context
• v2026.1.x: No agent isolation; all tools accessible globally
• Configuration-only migration: Required step for all v2026.2.x → v2026.3.2 upgrades