使用 OpenAI 相容接口調用 OpenClaw Gateway

想把 OpenClaw 整合到現有的應用程式裡，但又不想重新寫一套 API 串接邏輯嗎？很多時候我們只是想用現有的 OpenAI 客戶端或工具來調用自定義的 Agent，卻發現接口格式不統一，導致要在代碼裡寫很多轉換邏輯。

OpenClaw Gateway 提供了一個與 OpenAI 相容的 Chat Completions 接口，讓你可以直接把 Gateway 當作 OpenAI API 來使用。這個接口底層運行的邏輯與 openclaw agent 完全一致，這意味著你的路由、權限和配置都能直接套用。

需要準備的東西

• OpenClaw Gateway 實例
• 有效的 Gateway Token 或 Password
• 已配置好的 Agent（例如 main）

快速開始

這個接口預設是關閉的。你需要在配置文件中手動開啟它。

1. 啟用接口

在你的 config 中將 gateway.http.endpoints.chatCompletions.enabled 設為 true：

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

2. 發送請求

接口路徑與 Gateway 的 WebSocket 端口一致。你可以使用 curl 快速測試：

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

安全邊界提醒（重要）

你必須把這個接口視為 Gateway 實例的「管理員權限」入口。

• 這裡的 HTTP Bearer 認證並非針對單一用戶的權限模型。
• 任何持有有效 Token 或 Password 的調用者，都會被 OpenClaw 視為受信任的操作員。
• 如果目標 Agent 的策略允許使用敏感工具，調用者就能使用這些工具。
• 建議只在 loopback、tailnet 或私有網絡中使用，不要直接暴露在公網。

選擇 Agent

你不需要使用自定義 Header，可以直接在 OpenAI 的 model 欄位中指定 agentId：

• model: "openclaw:<agentId>" (例如 "openclaw:main")
• model: "agent:<agentId>"

或者使用 Header 指定（預設為 main）：

• x-openclaw-agent-id: <agentId>

如果你需要精確控制 Session 路由，可以使用 x-openclaw-session-key。

會話行為

預設情況下，這個接口對每個請求都是 stateless（無狀態）的，每次調用都會生成新的 Session Key。

如果你在請求中包含 OpenAI 的 user 字串，Gateway 會根據它生成固定的 Session Key，這樣多次調用就能共享同一個 Agent 會話。

Streaming (SSE)

如果你需要流式輸出，只需將 stream 設為 true：

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

疑難排解

• 429 錯誤：如果你配置了 gateway.auth.rateLimit 且出現過多認證失敗，接口會回傳 429 狀態碼以及 Retry-After Header。
• 認證失敗：請檢查 gateway.auth.mode。如果是 token，請使用 gateway.auth.token；如果是 password，請使用 gateway.auth.password。

如果你在設定過程中遇到問題，可以詢問 AI Setup Assistant。

下一步

• Security 詳解
• Remote access 配置