​

OpenAI Chat Completions（HTTP）

• POST /v1/chat/completions
• 與 Gateway 使用相同埠（WS + HTTP 多工）：http://<gateway-host>:<port>/v1/chat/completions

​

認證

• Authorization: Bearer <token>

• 當 gateway.auth.mode="token" 時，使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
• 當 gateway.auth.mode="password" 時，使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
• 若設定了 gateway.auth.rateLimit 且發生太多認證失敗，endpoint 會返回帶有 Retry-After 的 429。

​

安全邊界（重要）

• 此處的 HTTP bearer 認證不是狹義的每使用者範圍模型。
• 此 endpoint 的有效 Gateway token/password 應視為擁有者/operator 憑證。
• 請求透過與受信任的 operator 操作相同的控制平面 agent 路徑執行。
• 此 endpoint 沒有獨立的非擁有者/每使用者工具邊界；一旦呼叫者通過此處的 Gateway 認證，OpenClaw 將該呼叫者視為此 gateway 的受信任 operator。
• 若目標 agent 政策允許敏感工具，此 endpoint 可以使用它們。
• 僅在 loopback/tailnet/私有 ingress 上保留此 endpoint；不要直接暴露到公共網路。

​

選擇 Agent

• model: "openclaw:<agentId>"（範例："openclaw:main"、"openclaw:beta"）
• model: "agent:<agentId>"（別名）

• x-openclaw-agent-id: <agentId>（預設：main）

• x-openclaw-session-key: <sessionKey> 完全控制 session 路由。

​

啟用 endpoint

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

​

停用 endpoint

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

​

Session 行為

​

Streaming（SSE）

• Content-Type: text/event-stream
• 每個事件行為 data: <json>
• 串流以 data: [DONE] 結束

​

範例

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"}]
  }'

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"}]
  }'