OpenAI チャット補完

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• POST /v1/chat/completions
• Gateway と同じポート（WS + HTTP 多重化）: http://<gateway-host>:<port>/v1/chat/completions

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

​

認証

• 共有シークレット認証（gateway.auth.mode="token" または "password"）: Authorization: Bearer <token-or-password>
• 信頼された ID 付き HTTP 認証（gateway.auth.mode="trusted-proxy"）: 設定済みの ID 認識プロキシ経由でルーティングし、必要な ID ヘッダーを注入させます
• プライベート入口のオープン認証（gateway.auth.mode="none"）: 認証ヘッダーは不要です

• gateway.auth.mode="token" の場合は、gateway.auth.token（または OPENCLAW_GATEWAY_TOKEN）を使用します。
• gateway.auth.mode="password" の場合は、gateway.auth.password（または OPENCLAW_GATEWAY_PASSWORD）を使用します。
• gateway.auth.mode="trusted-proxy" の場合、HTTP リクエストは設定済みの信頼されたプロキシソースから送信される必要があります。同一ホストのループバックプロキシには、明示的に gateway.auth.trustedProxy.allowLoopback = true が必要です。
• gateway.auth.rateLimit が設定されていて認証失敗が多すぎる場合、エンドポイントは Retry-After 付きで 429 を返します。

​

セキュリティ境界（重要）

• ここでの HTTP ベアラー認証は、狭いユーザー別スコープモデルではありません。
• このエンドポイントの有効な Gateway トークン/パスワードは、所有者/オペレーター資格情報と同様に扱う必要があります。
• リクエストは、信頼されたオペレーター操作と同じコントロールプレーンエージェントパスを通じて実行されます。
• このエンドポイントには、別個の非所有者/ユーザー別ツール境界はありません。呼び出し元がここで Gateway 認証を通過すると、OpenClaw はその呼び出し元をこの Gateway の信頼されたオペレーターとして扱います。
• 共有シークレット認証モード（token と password）では、呼び出し元がより狭い x-openclaw-scopes ヘッダーを送信しても、エンドポイントは通常の完全なオペレーターデフォルトを復元します。
• 信頼された ID 付き HTTP モード（たとえば信頼済みプロキシ認証や gateway.auth.mode="none"）では、x-openclaw-scopes が存在する場合はそれを尊重し、存在しない場合は通常のオペレーターデフォルトスコープセットにフォールバックします。
• 対象エージェントポリシーが機密性の高いツールを許可している場合、このエンドポイントはそれらを使用できます。
• このエンドポイントは loopback/tailnet/プライベート入口のみに置いてください。公開インターネットへ直接公開しないでください。

• gateway.auth.mode="token" または "password" + Authorization: Bearer ...
  • 共有 Gateway オペレーターシークレットの所持を証明します
  • より狭い x-openclaw-scopes を無視します
  • 完全なデフォルトオペレータースコープセットを復元します: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • このエンドポイント上のチャットターンを所有者送信者ターンとして扱います
• 信頼された ID 付き HTTP モード（たとえば信頼済みプロキシ認証、またはプライベート入口上の gateway.auth.mode="none"）
  • 何らかの外側の信頼された ID またはデプロイ境界を認証します
  • ヘッダーが存在する場合は x-openclaw-scopes を尊重します
  • ヘッダーが存在しない場合は通常のオペレーターデフォルトスコープセットにフォールバックします
  • 呼び出し元が明示的にスコープを狭め、operator.admin を省略した場合にのみ所有者セマンティクスを失います

​

エージェント優先モデル契約

• model: "openclaw" は設定済みのデフォルトエージェントへルーティングします。
• model: "openclaw/default" も設定済みのデフォルトエージェントへルーティングします。
• model: "openclaw/<agentId>" は特定のエージェントへルーティングします。

• x-openclaw-model: <provider/model-or-bare-id> は選択されたエージェントのバックエンドモデルを上書きします。
• x-openclaw-agent-id: <agentId> は互換性のための上書きとして引き続きサポートされます。
• x-openclaw-session-key: <sessionKey> はセッションルーティングを完全に制御します。
• x-openclaw-message-channel: <channel> は、チャネル対応プロンプトとポリシー用の合成入口チャネルコンテキストを設定します。

• model: "openclaw:<agentId>"
• model: "agent:<agentId>"

​

エンドポイントを有効化する

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

​

エンドポイントを無効化する

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

​

セッション動作

​

このサーフェスが重要な理由

• ほとんどの Open WebUI、LobeChat、LibreChat セットアップは /v1/models を期待します。
• 多くの RAG システムは /v1/embeddings を期待します。
• 既存の OpenAI チャットクライアントは通常、/v1/chat/completions から開始できます。
• よりエージェントネイティブなクライアントでは、/v1/responses がますます好まれています。

​

モデル一覧とエージェントルーティング

​

ストリーミング（SSE）

• Content-Type: text/event-stream
• 各イベント行は data: <json> です
• ストリームは data: [DONE] で終了します

​

チャットツール契約

​

サポートされるリクエストフィールド

• tools: { "type": "function", "function": { ... } } の配列
• tool_choice: "auto", "none"
• messages[*].role: "tool" のフォローアップターン
• 以前のツール呼び出しへツール結果を結び付けるための messages[*].tool_call_id
• max_completion_tokens: 数値。完了トークン合計（推論トークンを含む）の呼び出しごとの上限です。現在の OpenAI Chat Completions フィールド名です。max_completion_tokens と max_tokens の両方が送信された場合はこちらが優先されます。
• max_tokens: 数値。後方互換性のために受け付けられるレガシーエイリアスです。max_completion_tokens も存在する場合は無視されます。

​

サポートされないバリアント

• 配列でない tools
• 関数でないツールエントリ
• tool.function.name の欠落
• allowed_tools や custom などの tool_choice バリアント
• tool_choice: "required"（ランタイムではまだ強制されません。強制が実装されるとサポートされます）
• tool_choice: { "type": "function", "function": { "name": "..." } }（required と同じ理由）
• 指定された tools と一致しない tool_choice.function.name 値

​

非ストリーミングツール応答の形状

• choices[0].finish_reason = "tool_calls"
• 次を含む choices[0].message.tool_calls[] エントリ:
  • id
  • type: "function"
  • function.name
  • function.arguments（JSON 文字列）

​

ストリーミングツール応答の形状

• 初期のアシスタントロールデルタ
• 任意のアシスタントコメントデルタ
• ツール ID と引数フラグメントを運ぶ 1 つ以上の delta.tool_calls チャンク
• finish_reason: "tool_calls" を含む最終チャンク
• data: [DONE]

​

ツールフォローアップループ

• 以前のアシスタントツール呼び出しメッセージ
• 一致する tool_call_id を持つ 1 つ以上の role: "tool" メッセージ

​

Open WebUI クイックセットアップ

• ベース URL: http://127.0.0.1:18789/v1
• macOS 上の Docker ベース URL: http://host.docker.internal:18789/v1
• API キー: Gateway ベアラートークン
• モデル: openclaw/default

• GET /v1/models は openclaw/default を一覧表示する必要があります
• Open WebUI は openclaw/default をチャットモデル ID として使用する必要があります
• そのエージェントに特定のバックエンドプロバイダー/モデルを使いたい場合は、エージェントの通常のデフォルトモデルを設定するか、x-openclaw-model を送信します

curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

​

例

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openclaw/default",
    "messages": [{"role":"user","content":"hi"}]
  }'

curl -N http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/gpt-5.4' \
  -d '{
    "model": "openclaw/research",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'

curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -sS http://127.0.0.1:18789/v1/embeddings \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/text-embedding-3-small' \
  -d '{
    "model": "openclaw/default",
    "input": ["alpha", "beta"]
  }'

• /v1/models は未加工のプロバイダーカタログではなく、OpenClaw エージェントターゲットを返します。
• openclaw/default は常に存在するため、1 つの安定した id が環境をまたいで機能します。
• バックエンドのプロバイダー/モデルのオーバーライドは、OpenAI の model フィールドではなく x-openclaw-model に指定します。
• /v1/embeddings は、input を文字列または文字列の配列としてサポートします。

​

関連

• 設定リファレンス
• OpenAI