POST /v1/responses 端點。它預設停用，並與閘道共用同一個連接埠（WS + HTTP 多工）：http://<gateway-host>:<port>/v1/responses。
請求會作為一般閘道代理執行來運行（與 openclaw agent 相同的程式碼路徑），因此路由、權限與設定會符合你的閘道。
使用 gateway.http.endpoints.responses.enabled 啟用或停用。啟用時，同一個相容性介面也會提供 GET /v1/models、GET /v1/models/{id}、POST /v1/embeddings 與 POST /v1/chat/completions。
驗證、安全性與路由
操作行為符合 OpenAI Chat Completions：- 驗證路徑符合
gateway.auth.mode：shared-secret（token/password）使用Authorization: Bearer <token-or-password>；trusted-proxy 使用具身分感知的 Proxy 標頭（同主機 loopback Proxy 需要gateway.auth.trustedProxy.allowLoopback = true，且在沒有Forwarded/X-Forwarded-*/X-Real-IP標頭時，會透過gateway.auth.password/OPENCLAW_GATEWAY_PASSWORD使用同主機直接後援）；私有入口上的none不需要驗證標頭。請參閱受信任 Proxy 驗證。 - 請將此端點視為對閘道執行個體的完整操作員存取權。
- Shared-secret 驗證模式會忽略範圍較窄、由 Bearer 宣告的
x-openclaw-scopes，並還原完整預設操作員範圍集合：operator.admin、operator.approvals、operator.pairing、operator.read、operator.talk.secrets、operator.write。此端點上的聊天回合會被視為擁有者傳送者回合。 - 帶有受信任身分的 HTTP 模式（trusted-proxy，或
gateway.auth.mode="none"）會在存在x-openclaw-scopes時遵循它，否則會退回到操作員預設範圍集合。只有在呼叫端明確縮窄範圍且省略operator.admin時，才會失去擁有者語意。 - 使用
model: "openclaw"、"openclaw/default"、"openclaw/<agentId>"，或x-openclaw-agent-id標頭來選取代理。 - 使用
x-openclaw-model覆寫所選代理的後端模型（在帶有身分的驗證路徑上需要operator.admin）。 - 使用
x-openclaw-session-key進行明確工作階段路由（若使用保留命名空間，會以400 invalid_request_error拒絕：subagent:、cron:、acp:）。 - 使用
x-openclaw-message-channel作為非預設的合成入口通道情境。
openclaw/default、嵌入向量透傳與後端模型覆寫的標準說明，請參閱 OpenAI Chat Completions。
請參閱操作員範圍與安全性。
工作階段行為
預設情況下，此端點是每個請求無狀態（每次呼叫都會產生新的工作階段金鑰）。 如果請求包含 OpenResponsesuser 字串，閘道會從中衍生穩定的工作階段金鑰，讓重複呼叫可以共用代理工作階段。
當請求保持在相同的代理/使用者/請求工作階段範圍內時，previous_response_id 會重用先前回應的工作階段（依驗證主體、代理 ID 與 x-openclaw-session-key 比對）。
請求形狀
| 欄位 | 支援 |
|---|---|
input | 字串或項目物件陣列。 |
instructions | 併入系統提示。 |
tools | 用戶端工具定義（函式工具）。 |
tool_choice | "auto"、"none"、"required"，或 { "type": "function", "name": "..." }，用來篩選或要求用戶端工具。 |
stream | 啟用 SSE 串流。 |
max_output_tokens | 盡力而為的輸出限制（取決於提供者）。 |
temperature | 盡力而為的取樣溫度。會被以 ChatGPT 為基礎的 Codex Responses 後端忽略，該後端使用固定的伺服器端取樣。 |
top_p | 盡力而為的 nucleus 取樣。與 temperature 有相同的 Codex Responses 注意事項。 |
user | 穩定工作階段路由。 |
previous_response_id | 工作階段連續性（見上方）。 |
max_tool_calls、reasoning、metadata、store、truncation | 會接受，但目前忽略。 |
項目（輸入）
message
角色：system、developer、user、assistant。
system與developer會附加到系統提示。- 最近的
user或function_call_output項目會成為「目前訊息」。 - 較早的 user/assistant 訊息會作為脈絡歷史納入。
function_call_output（以回合為基礎的工具）
將工具結果傳回模型：
reasoning 與 item_reference
為結構描述相容性而接受，但在建構提示時忽略。
工具（用戶端函式工具）
使用tools: [{ type: "function", name, description?, parameters? }] 提供工具。
如果代理呼叫工具，回應會傳回 function_call 輸出項目。傳送包含 function_call_output 的後續請求以繼續該回合。
對於 tool_choice: "required" 與釘選函式的 tool_choice，端點會縮窄公開的用戶端函式工具集合，指示執行階段在回應前呼叫用戶端工具，並在回合未包含相符的結構化用戶端工具呼叫時拒絕該回合，符合 /v1/chat/completions 合約。非串流請求會回傳帶有 api_error 的 502；串流請求會發出 response.failed 事件。
圖片（input_image）
支援 base64 或 URL 來源：
image/jpeg、image/png、image/gif、image/webp、image/heic、image/heif。大小上限（預設）：10MB。
檔案（input_file）
支援 base64 或 URL 來源：
text/plain、text/markdown、text/html、text/csv、application/json、application/pdf。大小上限（預設）：5MB。
目前行為：
- 檔案內容會解碼並加入系統提示，而不是使用者訊息，因此會保持暫時性（不會保存在工作階段歷史中）。
- 解碼後的檔案文字在加入前會包裝為不受信任的外部內容，因此檔案位元組會被視為資料，而不是受信任的指示。注入的區塊使用明確邊界標記（
<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>/<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>）與一行Source: External中繼資料。它刻意省略冗長的SECURITY NOTICE:橫幅以保留提示預算；邊界標記與中繼資料仍然適用。 - PDF 會先解析文字。如果找到的文字很少，前幾頁會被點陣化為圖片並傳給模型，注入的檔案區塊會使用預留位置
[PDF content rendered to images]。
document-extract 外掛提供，該外掛使用 clawpdf 及其封裝的 PDFium WebAssembly 執行階段來進行文字擷取與頁面算繪。
URL 擷取預設值：
files.allowUrl：trueimages.allowUrl：truemaxUrlParts：8（每個請求中 URL 型input_file+input_image部分的總數）- 請求受到保護（DNS 解析、私有 IP 封鎖、重新導向上限、逾時）。
- 每種輸入類型都支援選用的主機名稱允許清單（
files.urlAllowlist、images.urlAllowlist）：精確主機（"cdn.example.com"）或萬用字元子網域（"*.assets.example.com"，不符合根網域）。空白或省略的允許清單表示沒有主機名稱允許清單限制。 - 若要完全停用 URL 型擷取，請設定
files.allowUrl: false和/或images.allowUrl: false。
檔案 + 圖片限制（設定）
可在gateway.http.endpoints.responses 下調整預設值：
| 鍵 | 預設值 |
|---|---|
maxBodyBytes | 20MB |
maxUrlParts | 8 |
files.maxBytes | 5MB |
files.maxChars | 60k |
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 |
input_image 來源在透過共享 OpenClaw 圖片處理器（Rastermill）交付給提供者前，會正規化為 JPEG；對於需要外部 codec 支援的格式，該處理器會退回使用系統轉換器（sips、ImageMagick、GraphicsMagick 或 ffmpeg）。
安全性注意事項：URL 允許清單會在擷取前以及重新導向跳轉時強制執行。將主機名稱加入允許清單不會繞過私有/內部 IP 封鎖。對於暴露在網際網路上的閘道，除了應用程式層級的保護外，也請套用網路出口控制。請參閱安全性。
串流（SSE）
設定stream: true 以接收 Server-Sent Events：
Content-Type: text/event-stream- 每個事件行都是
event: <type>和data: <json> - 串流以
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（發生錯誤時）。
用法
當底層供應商回報權杖計數時，會填入usage。OpenClaw 會先正規化常見的 OpenAI 風格別名，再讓這些計數器到達下游狀態/工作階段介面，包括 input_tokens / output_tokens 和 prompt_tokens / completion_tokens。
錯誤
錯誤使用如下的 JSON 物件：400 無效的請求主體、401 缺少/無效的驗證、403 缺少操作員範圍、405 方法錯誤、429 驗證失敗嘗試次數過多（含 Retry-After）。