OpenAI Chat Completions API を使って OpenClaw を操作する

新しいツールを導入する際、独自の API 仕様に合わせてコードを書き直すのは手間がかかるものです。すでにある OpenAI 互換のライブラリやツールをそのまま使って、自作のエージェントを動かせたら便利だと思ったことはありませんか？

OpenClaw の Gateway を使えば、OpenAI 互換の Chat Completions エンドポイントを公開できます。これにより、既存のアプリケーションの接続先を OpenClaw に向けるだけで、高度なエージェント機能を組み込むことが可能になります。

必要なもの

作業を始める前に、以下の準備ができているか確認してください。

• OpenClaw Gateway が動作している環境
• Gateway の認証設定（Token または Password）
• 設定ファイルを編集できる権限

クイックスタート

OpenAI 互換エンドポイントは、デフォルトでは無効になっています。5 分ほどで完了する以下のステップで有効化しましょう。

1. エンドポイントを有効にする

設定ファイル（config）で chatCompletions.enabled を true に設定します。

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

2. リクエストを送信する

Gateway のポート（デフォルトでは WS と HTTP が共用）に対してリクエストを送ります。model フィールドに openclaw:<agentId> を指定することで、特定のエージェントを呼び出せます。

通常のレスポンス:

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"}]
  }'

ストリーミングレスポンス (SSE):

stream: true を含めることで、逐次レスポンスを受け取れます。

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"}]
  }'

重要なセキュリティの注意点

このエンドポイントは、Gateway インスタンスに対する**フル権限（オペレーターアクセス）**として扱われます。利用の際は以下の点に注意してください。

• このエンドポイントの認証情報は、オーナー権限と同じ重みを持ちます。
• ユーザーごとの細かい権限管理（Scope）は提供されません。
• エージェントに機密性の高いツールの使用が許可されている場合、この API 経由でそれらが実行可能です。
• 公開インターネットに直接さらさず、loopback、tailnet、またはプライベートな Ingress 経由でのみアクセスするようにしてください。

トラブルシューティング

設定や接続で問題が発生した場合は、以下を確認してください。

• 429 Too Many Requests: gateway.auth.rateLimit が設定されている場合、認証エラーが続くとこのエラーが返されます。Retry-After ヘッダーを確認して時間を置いてから再試行してください。
• 認証エラー: gateway.auth.mode が "token" の場合は gateway.auth.token を、"password" の場合は gateway.auth.password を正しく使用しているか確認してください。

セットアップに関する個別の質問がある場合は、AI Setup Assistant がお手伝いします。

次のステップ

• Security
• Remote access