OpenClaw Gateway 整合 OpenResponses 實作指南

寫過 Agent 的開發者都知道，要把複雜的代理邏輯塞進傳統的聊天 API 真的很痛苦。你可能遇過串流事件不夠語義化，或是處理多輪工具調用（Tool Calls）時，資料結構亂成一團的問題。為了讓開發體驗更順暢，我們決定在 Gateway 中引進 OpenResponses 標準。

這套標準專為 Agent 工作流設計，使用以項目為基礎（item-based）的輸入與語義化的串流事件，讓你的應用程式能更精準地掌握 AI 的思考與執行過程。

需要準備的東西

OpenClaw Gateway 執行環境
具備存取 Gateway 設定檔的權限
支援 POST 請求的工具（如 curl）

快速開始

要在 5 分鐘內開始使用 OpenResponses，請按照以下步驟操作：

1. 啟用端點

在你的設定檔中開啟新的端點開關。目前 /v1/responses 預設是關閉的。

gateway:
  http:
    endpoints:
      responses:
        enabled: true
      chatCompletions:
        enabled: true # 可視需求保留或關閉 legacy 端點

2. 發送第一個請求

你可以直接對 /v1/responses 發送請求。這個端點接受 model、input 和 instructions 等參數。

curl -X POST http://localhost:3000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4",
    "input": [
      {
        "role": "user",
        "content": "哈囉！幫我規劃一個技術架構"
      }
    ],
    "stream": true
  }'

3. 處理串流事件

如果你開啟了 stream: true，你會收到一系列語義化的事件，這比舊有的 API 更好解析：

response.created
response.output_text.delta（文字增量）
response.completed
[DONE]（結束標記）

第一階段支援範圍

我們在 Phase 1 優先實作了核心功能，確保遷移過程穩定：

輸入處理：支援字串或 ItemParam[] 格式，包含 system、developer、user 及 assistant 角色。
工具整合：支援 function_call_output 項目。
驗證機制：使用 Zod 進行嚴格的 Schema 檢查，確保資料格式正確。
相容性：保留 /v1/chat/completions 作為相容層，但建議逐步切換到新端點。

疑難排解

收到 invalid_request_error：檢查你的請求內容是否包含了圖片或檔案。目前 Phase 1 尚未支援多媒體內容，僅支援純文字與工具調用。
串流中斷或格式錯誤：確認你的客戶端是否有正確處理 Content-Type: text/event-stream，並檢查事件序列是否以 [DONE] 結尾。
認證失敗：請確保你的 Authorization Header 格式正確，且 Gateway 已配置相對應的存取權限。
找不到端點：請確認設定檔中的 gateway.http.endpoints.responses.enabled 已設為 true 並重啟服務。

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

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。