Skip to main content

​
コンテキスト

OpenClaw Gateway は現在、最小限の OpenAI 互換 Chat Completions エンドポイントを /v1/chat/completions で公開しています。詳細は OpenAI Chat Completions を参照してください。 Open Responses は、OpenAI Responses API をベースにしたオープンな推論標準です。エージェント型ワークフロー向けに設計されており、アイテムベースの入力と意味論的なストリーミングイベントを使用します。OpenResponses の仕様で定義されているのは /v1/responses であり、/v1/chat/completions ではありません。

​
目標

  • OpenResponses のセマンティクスに準拠した /v1/responses エンドポイントを追加する
  • Chat Completions は、無効化しやすく、最終的に削除しやすい互換レイヤーとして維持する
  • 独立して再利用できるスキーマにより、検証とパースを標準化する

​
非目標

  • 初期フェーズで OpenResponses の全機能と同等にすること（画像、ファイル、ホスト型ツールを含む）
  • 内部のエージェント実行ロジックやツールオーケストレーションを置き換えること
  • 第 1 フェーズで既存の /v1/chat/completions の挙動を変更すること

​
調査の要約

参照元: OpenResponses OpenAPI、OpenResponses 仕様サイト、Hugging Face のブログ記事。 主な確認事項:
  • POST /v1/responses は、model、input（文字列または ItemParam[]）、instructions、tools、tool_choice、stream、max_output_tokens、max_tool_calls などの CreateResponseBody フィールドを受け付ける
  • ItemParam は次の判別共用体で構成される
    • system、developer、user、assistant の各 role を持つ message
    • function_call と function_call_output
    • reasoning
    • item_reference
  • 正常応答では object: "response"、status、output を含む ResponseResource が返る
  • ストリーミングでは、次のような意味論的イベントを使用する
    • response.created、response.in_progress、response.completed、response.failed
    • response.output_item.added、response.output_item.done
    • response.content_part.added、response.content_part.done
    • response.output_text.delta、response.output_text.done
  • 仕様上の必須要件は次のとおり
    • Content-Type: text/event-stream
    • event: は JSON の type フィールドと一致すること
    • 終端イベントはリテラルの [DONE] であること
  • reasoning アイテムは content、encrypted_content、summary を公開する場合がある
  • Hugging Face の例では、リクエストに OpenResponses-Version: latest を含めている（任意ヘッダー）

​
提案アーキテクチャ

  • Zod スキーマだけを持つ src/gateway/open-responses.schema.ts を追加する（ゲートウェイ側 import は含めない）
  • /v1/responses 向けに src/gateway/openresponses-http.ts（または open-responses-http.ts）を追加する
  • src/gateway/openai-http.ts は従来互換アダプターとしてそのまま維持する
  • 設定項目 gateway.http.endpoints.responses.enabled を追加する（デフォルトは false）
  • gateway.http.endpoints.chatCompletions.enabled は独立させ、両エンドポイントを個別に切り替えられるようにする
  • Chat Completions が有効な場合は、従来機能であることを示す起動時警告を出す

​
Chat Completions の非推奨化方針

  • 厳密なモジュール境界を維持し、responses と chat completions の間でスキーマ型を共有しない
  • Chat Completions は設定による opt-in にして、コード変更なしで無効化できるようにする
  • /v1/responses が安定した段階で、Chat Completions を legacy と明示するようドキュメントを更新する
  • 将来的な任意の施策として、Chat Completions リクエストを Responses ハンドラーへマップし、削除経路を単純化することを検討する

​
フェーズ 1 のサポート範囲

  • input は文字列、または message role と function_call_output を含む ItemParam[] として受け付ける
  • system / developer メッセージは extraSystemPrompt に抽出する
  • エージェント実行時の現在メッセージには、最新の user または function_call_output を使う
  • 未対応の content part（画像 / ファイル）は invalid_request_error で拒否する
  • output_text を含む単一の assistant message を返す
  • トークン集計が接続されるまでは、usage は 0 埋めした値を返す

​
検証戦略（SDK なし）

  • 次の対応範囲について Zod スキーマを実装する
    • CreateResponseBody
    • ItemParam と message content part union
    • ResponseResource
    • ゲートウェイで使用するストリーミングイベント形状
  • スキーマは単一で独立したモジュールにまとめ、仕様との乖離を防ぎつつ、将来的な codegen にも対応しやすくする

​
ストリーミング実装（フェーズ 1）

  • SSE 行には event: と data: の両方を含める
  • 必要となる最小シーケンス:
    • response.created
    • response.output_item.added
    • response.content_part.added
    • response.output_text.delta（必要に応じて繰り返す）
    • response.output_text.done
    • response.content_part.done
    • response.completed
    • [DONE]

​
テストと検証計画

  • /v1/responses 向けに e2e カバレッジを追加する
    • 認証が必須であること
    • 非ストリーミング応答の形状
    • ストリームイベントの順序と [DONE]
    • ヘッダーと user を使ったセッションルーティング
  • src/gateway/openai-http.test.ts は変更しない
  • 手動確認として、stream: true を指定して /v1/responses に curl し、イベント順序と終端の [DONE] を確認する

​
ドキュメント更新（後続タスク）

  • /v1/responses の使い方と例を説明する新しいドキュメントページを追加する
  • /gateway/openai-http-api に legacy 注記を追加し、/v1/responses への導線を設ける