OpenAI Chat Completions (HTTP)

Gateway của OpenClaw có thể cung cấp một endpoint Chat Completions tương thích với OpenAI.

Endpoint này mặc định bị tắt. Các bạn cần bật nó trong config trước nhé.

  • POST /v1/chat/completions
  • Dùng cùng port với Gateway (WS + HTTP multiplex): http://<gateway-host>:<port>/v1/chat/completions

Về cơ bản, các request sẽ được thực thi như một lần chạy Agent bình thường của Gateway (cùng codepath với openclaw agent), nên routing/permissions/config sẽ khớp với Gateway của các bạn.

Xác thực (Authentication)

Sử dụng cấu hình auth của Gateway. Gửi bearer token:

  • Authorization: Bearer <token>

Lưu ý:

  • Khi gateway.auth.mode="token", dùng gateway.auth.token (hoặc OPENCLAW_GATEWAY_TOKEN).
  • Khi gateway.auth.mode="password", dùng gateway.auth.password (hoặc OPENCLAW_GATEWAY_PASSWORD).

Chọn Agent

Không cần custom header: các bạn encode agent id vào trường model của OpenAI:

  • model: "openclaw:<agentId>" (ví dụ: "openclaw:main", "openclaw:beta")
  • model: "agent:<agentId>" (alias)

Hoặc chỉ định Agent cụ thể của OpenClaw qua header:

  • x-openclaw-agent-id: <agentId> (mặc định: main)

Nâng cao:

  • x-openclaw-session-key: <sessionKey> để kiểm soát hoàn toàn session routing.

Bật endpoint

Đặt gateway.http.endpoints.chatCompletions.enabled thành true:

{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: true },
      },
    },
  },
}

Tắt endpoint

Đặt gateway.http.endpoints.chatCompletions.enabled thành false:

{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: false },
      },
    },
  },
}

Hành vi Session

Mặc định endpoint này stateless cho mỗi request (một session key mới được tạo cho mỗi lần gọi).

Nếu request có chuỗi user của OpenAI, Gateway sẽ tạo một session key ổn định từ nó, để các lần gọi lặp lại có thể chia sẻ cùng một Agent session.

Streaming (SSE)

Đặt stream: true để nhận Server-Sent Events (SSE):

  • Content-Type: text/event-stream
  • Mỗi dòng event là data: <json>
  • Stream kết thúc với data: [DONE]

Ví dụ

Non-streaming:

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "messages": [{"role":"user","content":"hi"}]
  }'

Streaming:

curl -N http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'