OpenAI 채팅 완성

OpenClaw의 Gateway는 작은 OpenAI 호환 Chat Completions 엔드포인트를 제공할 수 있습니다.

이 엔드포인트는 기본적으로 비활성화되어 있습니다. 먼저 구성에서 활성화하세요.

• POST /v1/chat/completions
• Gateway와 동일한 포트(WS + HTTP 멀티플렉스): http://<gateway-host>:<port>/v1/chat/completions

Gateway의 OpenAI 호환 HTTP 인터페이스가 활성화되면 다음도 함께 제공합니다.

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

내부적으로 요청은 일반 Gateway 에이전트 실행(openclaw agent와 동일한 코드 경로)으로 실행되므로, 라우팅/권한/구성이 Gateway와 일치합니다.

# 인증

Gateway 인증 구성을 사용합니다.

일반적인 HTTP 인증 경로:

• 공유 비밀 인증(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 요청은 구성된 신뢰할 수 있는 프록시 소스에서 와야 합니다. 동일 호스트 loopback 프록시는 명시적으로 gateway.auth.trustedProxy.allowLoopback = true가 필요합니다.
• gateway.auth.rateLimit이 구성되어 있고 인증 실패가 너무 많이 발생하면 엔드포인트는 Retry-After와 함께 429를 반환합니다.

# 보안 경계(중요)

이 엔드포인트를 Gateway 인스턴스에 대한 전체 운영자 액세스 인터페이스로 취급하세요.

• 여기의 HTTP bearer 인증은 좁은 사용자별 범위 모델이 아닙니다.
• 이 엔드포인트의 유효한 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을 생략한 경우에만 소유자 의미 체계를 잃습니다.

보안 및 원격 액세스를 참조하세요.

# 에이전트 우선 모델 계약

OpenClaw는 OpenAI model 필드를 원시 공급자 모델 ID가 아니라 에이전트 대상으로 취급합니다.

• 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: true },
      },
    },
  },
}

# 엔드포인트 비활성화

gateway.http.endpoints.chatCompletions.enabled를 false로 설정하세요.

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

# 세션 동작

기본적으로 엔드포인트는 요청별로 상태 비저장입니다(호출할 때마다 새 세션 키가 생성됩니다).

요청에 OpenAI user 문자열이 포함되어 있으면 Gateway는 여기서 안정적인 세션 키를 파생하므로, 반복 호출이 에이전트 세션을 공유할 수 있습니다.

# 이 인터페이스가 중요한 이유

이것은 자체 호스팅 프런트엔드와 도구를 위한 가장 활용도 높은 호환성 집합입니다.

• 대부분의 Open WebUI, LobeChat, LibreChat 설정은 /v1/models를 기대합니다.
• 많은 RAG 시스템은 /v1/embeddings를 기대합니다.
• 기존 OpenAI 채팅 클라이언트는 보통 /v1/chat/completions로 시작할 수 있습니다.
• 더 에이전트 네이티브한 클라이언트는 점점 /v1/responses를 선호합니다.

# 모델 목록 및 에이전트 라우팅

# 스트리밍(SSE)

서버 전송 이벤트(Server-Sent Events, SSE)를 받으려면 stream: true를 설정하세요.

• Content-Type: text/event-stream
• 각 이벤트 라인은 data: <json>입니다.
• 스트림은 data: [DONE]으로 끝납니다.

# Open WebUI 빠른 설정

기본 Open WebUI 연결의 경우:

• 기준 URL: http://127.0.0.1:18789/v1
• macOS의 Docker 기준 URL: http://host.docker.internal:18789/v1
• API 키: Gateway bearer 토큰
• 모델: 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'

이것이 openclaw/default를 반환하면, 대부분의 Open WebUI 설정은 동일한 기준 URL과 토큰으로 연결할 수 있습니다.

# 예

비스트리밍:

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는 항상 존재하므로, 하나의 안정적인 ID가 여러 환경에서 작동합니다.
• 백엔드 공급자/모델 재정의는 OpenAI model 필드가 아니라 x-openclaw-model에 있어야 합니다.
• /v1/embeddings는 문자열 또는 문자열 배열로 input을 지원합니다.

# 관련 항목

• 구성 참조
• OpenAI