OpenAI Compatibility Guide

The GoClaw Gateway exposes an OpenAI-compatible interface, allowing it to act as a drop-in proxy for tools like Cursor, Continue.dev, or any library that supports the OpenAI API.

Endpoints

/v1/chat/completions

Method: POST

Implements the standard OpenAI Chat Completions API.

Key Features:

• Streaming: Supports stream: true using Server-Sent Events (SSE). Besides the usual chat.completion.chunk frames, a stream can carry data: {"buffer_reset":true} (the reply is being retried: discard the text received so far) and data: {"error":{"message":"…"}}, which ends the stream with no finish chunk and no data: [DONE].
• Non-Streaming: Returns a standard JSON response.
• Message content: Each message's content must be a string. Content sent as an array of parts (text and images) is refused with 400.
• Model Routing: All requests go to the Default Agent configured in GoClaw. The model parameter is echoed back in the response and does not select an agent or a model. max_tokens and temperature are read and ignored.
• Subagent Commands: A last user message that starts with /subagents is a GoClaw subagent command, answered without the model: /subagents spawn <agent_id> <task>, /subagents list, /subagents status <run_id>, /subagents stop <run_id>.

Example Request:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "How many files are in the current directory?"}]
  }'

/v1/models

Method: GET

Not implemented: the gateway answers 404. Use the default model or any string, as all traffic goes to the default agent.

Authentication

The gateway token is always required: the gateway does not start without gateway.auth.token. Provide it in one of the following ways:

• Bearer Token: Authorization: Bearer <your-token>
• Custom Header: X-GoClaw-Token: <your-token>
• Query Parameter: ?token=<your-token> (for browser clients that cannot set a header, such as EventSource)
• Cookie: the X-Goclaw-Token cookie a browser receives from the Web UI's login link

?auth_code= is a different thing: a one-time login code the gateway prints at startup, which exchanges itself for a session cookie. It is not the token.

Request Handling

When a request is received via the OpenAI compatibility layer:

1. Agent Selection: The Gateway uses the Default Agent: agents.default, else the agent marked default: true, else the first agent in agents.list, else main.
2. Conversation: The last user message is the prompt; the system, user and assistant messages before it are the conversation history. GoClaw keeps no history for this endpoint: a session openai-compat:<client-ip> is created, but nothing is written to it, so send the whole conversation in messages on every request.
3. Provider Logic: The request is processed by the default agent's provider. When it fails before the reply used a tool (a rate limit, an outage, a bad key), the next provider of ai.fallback serves it (see Provider Fallback). When every provider fails, the error is returned as an OpenAI-style error ({"error":{"message":…}}, status 500 when not streaming).
4. Token Estimation: Usage stats (prompt_tokens, completion_tokens) are estimated based on character count (~4 characters per token).

Usage in IDEs (Cursor/Continue)

To use GoClaw in your IDE:

1. Set the Base URL to http://your-gateway:8080/v1.
2. Set the API Key to your gateway token.
3. Select any model (GoClaw will route to your default configured agent).