<!-- source: https://deepwiki.com/openclaw/openclaw/2.8-http-apis -->

# HTTP APIs

- docs/gateway/openai-http-api.md
- docs/gateway/openresponses-http-api.md
- docs/reference/code-mode.md
- scripts/e2e/lib/session-log-mentions.ts
- scripts/e2e/mcp-code-mode-gateway-client.ts
- scripts/e2e/mcp-code-mode-gateway-docker.sh
- scripts/e2e/mcp-code-mode-gateway-live-docker.sh
- scripts/e2e/mcp-code-mode-gateway-seed.ts
- scripts/mcp-code-mode-gateway-e2e.ts
- scripts/tool-search-gateway-e2e.ts
- src/agents/code-mode-namespaces.ts
- src/agents/code-mode.test.ts
- src/agents/code-mode.ts
- src/agents/code-mode.worker.ts
- src/agents/command/shared-types.ts
- src/agents/embedded-agent-runner/model.static-catalog.test.ts
- src/agents/openai-transport-stream.test.ts
- src/agents/openai-transport-stream.ts
- src/agents/tool-search.ts
- src/gateway/open-responses.schema.ts
- src/gateway/openai-compat-errors.ts
- src/gateway/openai-http.image-budget.test.ts
- src/gateway/openai-http.test.ts
- src/gateway/openai-http.ts
- src/gateway/openai-tool-choice.ts
- src/gateway/openresponses-http.test.ts
- src/gateway/openresponses-http.ts
- src/llm/providers/openai-completions.test.ts
- src/llm/providers/openai-completions.ts
- src/shared/text/reasoning-tag-text-partitioner.test.ts
- src/shared/text/reasoning-tag-text-partitioner.ts
- test/scripts/mcp-code-mode-gateway-client.test.ts
- test/scripts/session-log-mentions.test.ts
- test/scripts/tool-search-gateway-e2e.test.ts

The OpenClaw Gateway exposes several HTTP surfaces to facilitate integration with external tools, OpenAI-compatible clients, and Model Context Protocol (MCP) ecosystems. These interfaces allow the Gateway to act as a bridge between the core agent runtime and third-party applications.

## OpenAI-Compatible Endpoints

OpenClaw provides a compatibility layer that allows standard OpenAI clients to interact with OpenClaw-backed agents and models. This is primarily handled through the `/v1/chat/completions` and `/v1/responses` endpoints.

### Chat Completions ( /v1/chat/completions )

This endpoint mimics the OpenAI Chat Completions API. When a request is received, the Gateway routes it to the appropriate agent or model provider based on the configuration.

- Implementation : The routing logic determines if the request should be handled by an internal agent or forwarded to a configured provider. The handleGatewayPostJsonEndpoint src/gateway/openai-http.ts 44 helper manages the ingress, while buildAgentCommandInput src/gateway/openai-http.ts 145-170 prepares the payload for the agent runtime.
- Agent Routing : OpenClaw treats the model field as an agent target. model: "openclaw" routes to the default agent, while model: "openclaw/<agentId>" targets a specific one. This is resolved via resolveOpenAiCompatModelOverride src/gateway/openai-http.ts 47
- Data Flow : Client sends an OpenAI-formatted JSON payload. Gateway validates sampling parameters using validateOpenAiSamplingParams src/gateway/openai-http.ts 51 The request is processed via agentCommandFromIngress src/gateway/openai-http.ts 21 which triggers the agent execution pipeline. Streaming responses are handled by createAssistantMessageEventStream src/agents/openai-transport-stream.ts 24 and delivered via SSE src/gateway/openai-http.ts 141-143

### Responses Endpoint ( /v1/responses )

The `/v1/responses` endpoint provides compatibility with the Azure OpenAI Responses API, used for managing complex model turns and reasoning outputs [src/gateway/openresponses-http.ts1-5](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/openresponses-http.ts#L1-L5)

- Usage Tracking : The processResponsesStream function handles the consumption of SSE streams from upstream providers and normalizes usage data src/agents/openai-transport-stream.ts 1111
- Failure Handling : It observes response.failed events via normalizeResponsesFailedEvent src/agents/openai-transport-stream.ts 1093 and normalizes them into standard error shapes without leaking sensitive request IDs src/agents/openai-transport-stream.test.ts 143-187
- Payload Policy : Payload restrictions and reasoning summary preferences are enforced via applyOpenAIResponsesPayloadPolicy src/agents/openai-transport-stream.ts 59-61

**Sources**: [src/gateway/openai-http.ts21-170](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/openai-http.ts#L21-L170) [src/agents/openai-transport-stream.ts24-1111](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openai-transport-stream.ts#L24-L1111) [src/agents/openai-transport-stream.test.ts143-187](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openai-transport-stream.test.ts#L143-L187) [src/gateway/openresponses-http.ts1-5](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/openresponses-http.ts#L1-L5)

## Tool Invocation API ( /tools/invoke )

The `/tools/invoke` endpoint allows external systems to directly trigger OpenClaw tools without going through a natural language prompt.

### Execution Guardrails

Direct tool calls are subject to security policies and lifecycle hooks.

- Media Handling : Tool results are subject to image budget limits, configured via resolveOpenAiChatCompletionsLimits src/gateway/openai-http.ts 116-139
- Input Processing : Image content is extracted from sources using extractImageContentFromSource src/gateway/openai-http.ts 30

**Sources**: [src/gateway/openai-http.ts30-139](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/openai-http.ts#L30-L139) [src/gateway/openai-http.test.ts82](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/openai-http.test.ts#L82-L82)

## MCP Bridge ( openclaw mcp serve )

OpenClaw includes a Model Context Protocol (MCP) bridge, allowing clients like **Claude Code**, **Codex**, or **Cursor** to use OpenClaw as a host for tools.

### Architecture

The MCP bridge translates between the MCP protocol and the internal OpenClaw Gateway.

1. Transport : Usually runs over stdio .
2. Tool Mapping : OpenClaw's internal tools are exposed as MCP tools.
3. Code Mode Integration : MCP tools are grouped under the MCP namespace in OpenClaw's experimental Code Mode docs/reference/code-mode.md 47-48
4. Code Mode Execution : Code mode uses a quickjs-wasi worker src/agents/code-mode.ts 203 to evaluate model-generated JavaScript/TypeScript, calling MCP tools through a hidden catalog bridge src/agents/code-mode.ts 30-42

**Sources**: [docs/reference/code-mode.md47-48](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/reference/code-mode.md?plain=1#L47-L48) [src/agents/code-mode.ts30-203](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/code-mode.ts#L30-L203)

## Data Flow & Entity Mapping

The following diagrams illustrate how HTTP requests transition from external APIs into the Gateway internals.

### Request Routing Architecture

Title: "HTTP Request to Gateway Internal Flow"

```

```

**Sources**: [src/gateway/openai-http.ts21-51](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/openai-http.ts#L21-L51) [src/agents/code-mode.ts1-203](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/code-mode.ts#L1-L203) [src/agents/code-mode.worker.ts219-224](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/code-mode.worker.ts#L219-L224)

### Model Transport and Stream Processing

Title: "OpenAI Transport Stream Processing"

```

```

**Sources**: [src/agents/openai-transport-stream.ts81-82](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openai-transport-stream.ts#L81-L82) [src/agents/openai-transport-stream.ts19-21](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openai-transport-stream.ts#L19-L21) [src/agents/openai-transport-stream.ts35](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openai-transport-stream.ts#L35-L35)

## Security and Authentication

All HTTP APIs enforce the OpenClaw security model, assuming a single trusted operator boundary.

### Authentication Modes

The Gateway supports multiple authentication strategies [docs/gateway/openai-http-api.md24-49](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/openai-http-api.md?plain=1#L24-L49):

- Token : A static bearer token ( mode: "token" ) verified against gateway.auth.token .
- Password : Verified against gateway.auth.password .
- Trusted Proxy : Relies on identity headers from a configured proxy.
- None : Used for local-only development src/gateway/openai-http.test.ts 37

### Request Isolation

- Session Scoping : Requests are isolated by sessionKey src/gateway/openai-http.ts 149
- Media Protection : Input files are limited by size and MIME type via InputImageLimits src/gateway/openai-http.ts 101-107
- Usage Tracking : The transport layer tracks usage (input/output tokens) via normalizeUsage src/gateway/openai-http.ts 15
- Code Sandbox : Code Mode execution is isolated in a quickjs-wasi worker with strict memory ( memoryLimitBytes ) and timeout ( timeoutMs ) constraints src/agents/code-mode.ts 67-80

**Sources**: [src/gateway/openai-http.ts15-149](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/openai-http.ts#L15-L149) [src/gateway/openai-http.test.ts37](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/openai-http.test.ts#L37-L37) [docs/gateway/openai-http-api.md24-49](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/openai-http-api.md?plain=1#L24-L49) [src/agents/code-mode.ts67-80](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/code-mode.ts#L67-L80)
