Gateway

OpenResponses API

OpenClaw 的 Gateway 可以提供相容 OpenResponses 的 POST /v1/responses 端點。

此端點預設停用。請先在設定中啟用。

POST /v1/responses
與 Gateway 相同的連接埠（WS + HTTP 多工）：http://<gateway-host>:<port>/v1/responses

在底層，請求會以一般 Gateway agent 執行來處理（與 openclaw agent 相同的程式路徑），因此路由／權限／設定都會符合你的 Gateway。

驗證、安全性與路由

操作行為與 OpenAI Chat Completions 相同：

使用對應的 Gateway HTTP 驗證路徑：
- shared-secret 驗證（gateway.auth.mode="token" 或 "password"）：Authorization: Bearer <token-or-password>
- trusted-proxy 驗證（gateway.auth.mode="trusted-proxy"）：來自已設定受信任 proxy 來源的身分感知 proxy 標頭；同主機 loopback proxy 需要明確設定 gateway.auth.trustedProxy.allowLoopback = true
- private-ingress 開放驗證（gateway.auth.mode="none"）：不需要驗證標頭
將此端點視為對 gateway 執行個體的完整 operator 存取權
對於 shared-secret 驗證模式（token 和 password），忽略較窄的 bearer 宣告 x-openclaw-scopes 值，並還原一般完整 operator 預設值
對於帶有受信任身分的 HTTP 模式（例如 trusted proxy 驗證或 gateway.auth.mode="none"），當 x-openclaw-scopes 存在時遵從該值，否則回退到一般 operator 預設 scope 集合
使用 model: "openclaw"、model: "openclaw/default"、model: "openclaw/<agentId>" 或 x-openclaw-agent-id 選擇 agent
當你想覆寫所選 agent 的後端模型時，使用 x-openclaw-model
使用 x-openclaw-session-key 進行明確的 session 路由
當你想使用非預設的 synthetic ingress channel context 時，使用 x-openclaw-message-channel

驗證矩陣：

gateway.auth.mode="token" 或 "password" + Authorization: Bearer ...
- 證明持有 shared gateway operator secret
- 忽略較窄的 x-openclaw-scopes
- 還原完整預設 operator scope 集合： operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
- 將此端點上的對話回合視為 owner-sender 回合
帶有受信任身分的 HTTP 模式（例如 trusted proxy 驗證，或 private ingress 上的 gateway.auth.mode="none"）
- 當標頭存在時遵從 x-openclaw-scopes
- 當標頭不存在時，回退到一般 operator 預設 scope 集合
- 只有在呼叫者明確縮窄 scope 且省略 operator.admin 時，才會失去 owner 語意

使用 gateway.http.endpoints.responses.enabled 啟用或停用此端點。

相同的相容性介面也包含：

GET /v1/models
GET /v1/models/{id}
POST /v1/embeddings
POST /v1/chat/completions

若要了解 agent 目標模型、openclaw/default、embeddings 傳遞，以及後端模型覆寫如何搭配運作的權威說明，請參閱 OpenAI Chat Completions 和模型清單與 agent 路由。

Session 行為

預設情況下，此端點每個請求都是無狀態（每次呼叫都會產生新的 session key）。

如果請求包含 OpenResponses user 字串，Gateway 會從中衍生穩定的 session key，因此重複呼叫可以共用同一個 agent session。

請求形狀（支援）

請求遵循 OpenResponses API，並使用以項目為基礎的輸入。目前支援：

input：字串或項目物件陣列。
instructions：合併到 system prompt。
tools：client tool 定義（function tools）。
tool_choice：篩選或要求 client tools。
stream：啟用 SSE 串流。
max_output_tokens：盡力而為的輸出限制（依 provider 而定）。
user：穩定 session 路由。

接受但目前會忽略：

max_tool_calls
reasoning
metadata
store
truncation

支援：

previous_response_id：當請求仍在相同 agent／user／requested-session 範圍內時，OpenClaw 會重用先前 response session。

項目（輸入）

`message`

角色：system、developer、user、assistant。

system 和 developer 會附加到 system prompt。
最新的 user 或 function_call_output 項目會成為「current message」。
較早的 user／assistant 訊息會作為 context 的 history 包含進來。

`function_call_output`（以回合為基礎的 tools）

將 tool 結果傳回模型：

{
  "type": "function_call_output",
  "call_id": "call_123",
  "output": "{\"temperature\": \"72F\"}"
}

`reasoning` 和 `item_reference`

為了 schema 相容性而接受，但在建立 prompt 時會忽略。

Tools（client-side function tools）

使用 tools: [{ type: "function", function: { name, description?, parameters? } }] 提供 tools。

如果 agent 決定呼叫 tool，response 會回傳 function_call output item。接著你可以傳送包含 function_call_output 的後續請求來繼續此回合。

圖片（`input_image`）

支援 base64 或 URL 來源：

{
  "type": "input_image",
  "source": { "type": "url", "url": "https://example.com/image.png" }
}

允許的 MIME 類型（目前）：image/jpeg、image/png、image/gif、image/webp、image/heic、image/heif。大小上限（目前）：10MB。

檔案（`input_file`）

支援 base64 或 URL 來源：

{
  "type": "input_file",
  "source": {
    "type": "base64",
    "media_type": "text/plain",
    "data": "SGVsbG8gV29ybGQh",
    "filename": "hello.txt"
  }
}

允許的 MIME 類型（目前）：text/plain、text/markdown、text/html、text/csv、 application/json、application/pdf。

大小上限（目前）：5MB。

目前行為：

檔案內容會被解碼並加入system prompt，而不是 user message，因此會保持臨時性（不會持久化到 session history）。
解碼後的檔案文字會在加入前包裝為不受信任的外部內容，因此檔案位元組會被視為資料，而不是受信任的指令。
注入的區塊會使用明確的邊界標記，例如 <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>，並包含 Source: External metadata 行。
此檔案輸入路徑刻意省略較長的 SECURITY NOTICE: 橫幅，以保留 prompt 預算；邊界標記和 metadata 仍會保留。
PDF 會先被解析為文字。如果找到的文字很少，前幾頁會被 rasterized 成圖片並傳給模型，而注入的檔案區塊會使用 [PDF content rendered to images] placeholder。

PDF 解析由內建的 document-extract plugin 提供，它使用 Node 友善的 pdfjs-dist legacy build（無 worker）。現代 PDF.js build 預期 browser workers／DOM globals，因此不會在 Gateway 中使用。

URL 擷取預設值：

files.allowUrl：true
images.allowUrl：true
maxUrlParts：8（每個請求中 URL-based input_file + input_image parts 的總數）
請求會受到保護（DNS resolution、private IP blocking、redirect caps、timeouts）。
每種輸入類型都支援選用的 hostname allowlists（files.urlAllowlist、images.urlAllowlist）。
- Exact host："cdn.example.com"
- Wildcard subdomains："*.assets.example.com"（不符合 apex）
- 空白或省略的 allowlists 表示沒有 hostname allowlist 限制。
若要完全停用 URL-based fetches，請設定 files.allowUrl: false 和／或 images.allowUrl: false。

檔案 + 圖片限制（設定）

預設值可以在 gateway.http.endpoints.responses 下調整：

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          maxUrlParts: 8,
          files: {
            allowUrl: true,
            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
            allowedMimes: [
              "text/plain",
              "text/markdown",
              "text/html",
              "text/csv",
              "application/json",
              "application/pdf",
            ],
            maxBytes: 5242880,
            maxChars: 200000,
            maxRedirects: 3,
            timeoutMs: 10000,
            pdf: {
              maxPages: 4,
              maxPixels: 4000000,
              minTextChars: 200,
            },
          },
          images: {
            allowUrl: true,
            urlAllowlist: ["images.example.com"],
            allowedMimes: [
              "image/jpeg",
              "image/png",
              "image/gif",
              "image/webp",
              "image/heic",
              "image/heif",
            ],
            maxBytes: 10485760,
            maxRedirects: 3,
            timeoutMs: 10000,
          },
        },
      },
    },
  },
}

省略時的預設值：

maxBodyBytes：20MB
maxUrlParts：8
files.maxBytes：5MB
files.maxChars：200k
files.maxRedirects：3
files.timeoutMs：10s
files.pdf.maxPages：4
files.pdf.maxPixels：4,000,000
files.pdf.minTextChars：200
images.maxBytes：10MB
images.maxRedirects：3
images.timeoutMs：10s
HEIC/HEIF input_image 來源會被接受，並在傳遞給 provider 前正規化為 JPEG。

安全性注意事項：

URL allowlists 會在 fetch 前和 redirect hops 上強制執行。
Allowlist 中的 hostname 不會繞過 private/internal IP blocking。
對於暴露在網際網路上的 gateways，除了應用程式層級的防護外，也請套用網路 egress controls。請參閱安全性。

串流（SSE）

設定 stream: true 以接收伺服器傳送事件（SSE）：

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

目前發出的事件類型：

response.created
response.in_progress
response.output_item.added
response.content_part.added
response.output_text.delta
response.output_text.done
response.content_part.done
response.output_item.done
response.completed
response.failed（錯誤時）

使用量

當底層 provider 回報 token counts 時，usage 會被填入。 OpenClaw 會在這些 counters 到達下游 status／session 介面前，先正規化常見的 OpenAI-style aliases，包括 input_tokens / output_tokens 和 prompt_tokens / completion_tokens。

錯誤

錯誤會使用如下的 JSON 物件：

{ "error": { "message": "...", "type": "invalid_request_error" } }

常見情況：

401 缺少／無效的驗證
400 無效的請求 body
405 錯誤的方法

範例

非串流：

curl -sS http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "input": "hi"
  }'

串流：

curl -N http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "stream": true,
    "input": "hi"
  }'

OpenResponses API

驗證、安全性與路由

Session 行為

請求形狀（支援）

項目（輸入）

`message`

`function_call_output`（以回合為基礎的 tools）

`reasoning` 和 `item_reference`

Tools（client-side function tools）

圖片（`input_image`）

檔案（`input_file`）

檔案 + 圖片限制（設定）

串流（SSE）

使用量

錯誤

範例

相關

Ask OpenClaw

# 驗證、安全性與路由

# Session 行為

# 請求形狀（支援）

# 項目（輸入）

# message

# function_call_output（以回合為基礎的 tools）

# reasoning 和 item_reference

# Tools（client-side function tools）

# 圖片（input_image）

# 檔案（input_file）

# 檔案 + 圖片限制（設定）

# 串流（SSE）

# 使用量

# 錯誤

# 範例

# 相關

驗證、安全性與路由

Session 行為

請求形狀（支援）

項目（輸入）

`message`

`function_call_output`（以回合為基礎的 tools）

`reasoning` 和 `item_reference`

Tools（client-side function tools）

圖片（`input_image`）

檔案（`input_file`）

檔案 + 圖片限制（設定）

串流（SSE）

使用量

錯誤

範例

相關