OpenAI Chat Completions (HTTP)

OpenClaw の Gateway は、OpenAI 互換の小規模な Chat Completions エンドポイントを提供できます。

このエンドポイントはデフォルトで無効です。まず設定で有効化してください。

  • POST /v1/chat/completions
  • Gateway と同じポート（WS + HTTP マルチプレクス）：http://<gateway-host>:<port>/v1/chat/completions

内部的には通常の Gateway エージェント実行（openclaw agent と同じコードパス）として処理されるため、ルーティング/権限/設定は Gateway の設定に従います。

認証

Gateway の認証設定を使用します。ベアラートークンを送信してください：

  • Authorization: Bearer <token>

注意事項：

  • gateway.auth.mode="token" の場合、gateway.auth.token（または OPENCLAW_GATEWAY_TOKEN）を使用します。
  • gateway.auth.mode="password" の場合、gateway.auth.password（または OPENCLAW_GATEWAY_PASSWORD）を使用します。
  • gateway.auth.rateLimit が設定されていて認証失敗が多すぎると、エンドポイントは 429 と Retry-After を返します。

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

このエンドポイントは Gateway インスタンスに対するフルオペレーターアクセス面として扱ってください。

  • ここでの HTTP ベアラー認証は、狭いユーザーごとのスコープモデルではありません。
  • このエンドポイント用の有効な Gateway トークン/パスワードは、オーナー/オペレーター資格情報と同等に扱うべきです。
  • リクエストは信頼されたオペレーターアクションと同じコントロールプレーンのエージェントパスを経由します。
  • このエンドポイントには独立した非オーナー/ユーザーごとのツール境界はありません。呼び出し元が Gateway 認証を通過すると、OpenClaw はその呼び出し元をこの Gateway の信頼されたオペレーターとして扱います。
  • 対象エージェントのポリシーが機密ツールを許可している場合、このエンドポイントからもそれらを使用できます。
  • このエンドポイントはループバック/Tailnet/プライベートイングレスのみで使用し、パブリックインターネットに直接公開しないでください。

詳細は セキュリティ と リモートアクセス を参照してください。

エージェントの選択

カスタムヘッダーは不要です。OpenAI の model フィールドにエージェント ID を埋め込んでください：

  • model: "openclaw:<agentId>"（例："openclaw:main"、"openclaw:beta"）
  • model: "agent:<agentId>"（エイリアス）

ヘッダーで特定のエージェントを指定することもできます：

  • x-openclaw-agent-id: <agentId>（デフォルト：main）

高度な設定：

  • x-openclaw-session-key: <sessionKey> でセッションルーティングを完全に制御できます。

エンドポイントの有効化

gateway.http.endpoints.chatCompletions.enabled を true に設定します：

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

エンドポイントの無効化

gateway.http.endpoints.chatCompletions.enabled を false に設定します：

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

セッションの動作

デフォルトではリクエストごとにステートレスです（呼び出しごとに新しいセッションキーが生成されます）。

リクエストに OpenAI の user 文字列が含まれている場合、Gateway はそこから安定したセッションキーを導出し、繰り返しの呼び出しでエージェントセッションを共有できます。

ストリーミング（SSE）

stream: true を設定すると Server-Sent Events（SSE）を受信できます：

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

使用例

非ストリーミング：

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "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-agent-id: main' \
  -d '{
    "model": "openclaw",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'
arrow_back
前へ
Bridge Protocol
次へ
Openresponses HTTP API
arrow_forward