OpenAI Chat Completions (HTTP)

OpenClaw 게이트웨이는 소규모 OpenAI 호환 Chat Completions 엔드포인트를 제공할 수 있습니다.

이 엔드포인트는 기본적으로 비활성화되어 있습니다. 먼저 설정에서 활성화해야 합니다.

POST /v1/chat/completions
게이트웨이와 동일한 포트 (WS + HTTP 다중화): http://<gateway-host>:<port>/v1/chat/completions

내부적으로 요청은 일반 게이트웨이 에이전트 실행(openclaw agent와 동일한 코드 경로)으로 처리되므로, 라우팅/권한/설정이 게이트웨이 설정과 동일하게 적용됩니다.

인증

게이트웨이 인증 설정을 사용합니다. Bearer 토큰을 전송하세요:

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이 설정되어 있고 인증 실패가 너무 많이 발생하면, 엔드포인트는 Retry-After와 함께 429를 반환합니다.

보안 경계 (중요)

이 엔드포인트를 게이트웨이 인스턴스에 대한 완전한 운영자 접근 표면으로 취급하세요.

이 HTTP bearer 인증은 사용자별 세밀한 범위 모델이 아닙니다.
이 엔드포인트의 유효한 게이트웨이 토큰/비밀번호는 소유자/운영자 자격 증명과 동일하게 취급해야 합니다.
요청은 신뢰할 수 있는 운영자 작업과 동일한 제어 평면 에이전트 경로를 거칩니다.
이 엔드포인트에는 별도의 비소유자/사용자별 도구 경계가 없습니다. 호출자가 게이트웨이 인증을 통과하면, OpenClaw는 해당 호출자를 이 게이트웨이의 신뢰할 수 있는 운영자로 취급합니다.
대상 에이전트 정책이 민감한 도구를 허용하는 경우, 이 엔드포인트에서 해당 도구를 사용할 수 있습니다.
이 엔드포인트는 루프백/Tailnet/프라이빗 인그레스에서만 사용하세요. 공개 인터넷에 직접 노출하지 마세요.

보안 및 원격 접근을 참고하세요.

에이전트 선택

커스텀 헤더가 필요 없습니다. OpenAI model 필드에 에이전트 ID를 인코딩하세요:

model: "openclaw:<agentId>" (예: "openclaw:main", "openclaw:beta")
model: "agent:<agentId>" (별칭)

또는 헤더로 특정 OpenClaw 에이전트를 지정할 수 있습니다:

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 문자열이 포함된 경우, 게이트웨이가 해당 값에서 안정적인 세션 키를 생성하므로 반복 호출이 에이전트 세션을 공유할 수 있습니다.

스트리밍 (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"}]
  }'