메인 콘텐츠로 건너뛰기

​
OpenAI Chat Completions (HTTP)

OpenClaw의 Gateway는 작은 OpenAI 호환 Chat Completions 엔드포인트를 제공할 수 있습니다. 이 엔드포인트는 기본적으로 비활성화되어 있습니다. 먼저 config에서 활성화하세요.
  • 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 agent 실행으로 처리되므로(openclaw agent와 동일한 코드 경로), 라우팅/권한/config는 사용자의 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 요청이 구성된 non-loopback 신뢰 프록시 소스에서 와야 합니다. 동일 호스트의 loopback 프록시는 이 모드를 충족하지 않습니다.
  • gateway.auth.rateLimit이 구성되어 있고 인증 실패가 너무 많이 발생하면 엔드포인트는 Retry-After와 함께 429를 반환합니다.

​
보안 경계(중요)

이 엔드포인트는 해당 gateway 인스턴스에 대한 전체 운영자 액세스 표면으로 취급하세요.
  • 여기의 HTTP bearer 인증은 좁은 범위의 사용자별 스코프 모델이 아닙니다.
  • 이 엔드포인트에 대한 유효한 Gateway token/password는 소유자/운영자 자격 증명처럼 취급해야 합니다.
  • 요청은 신뢰된 운영자 작업과 동일한 control-plane agent 경로를 통해 실행됩니다.
  • 이 엔드포인트에는 별도의 비소유자/사용자별 도구 경계가 없습니다. 호출자가 여기서 Gateway 인증을 통과하면, OpenClaw는 그 호출자를 이 gateway의 신뢰된 운영자로 취급합니다.
  • 공유 비밀 인증 모드(token, password)에서는 호출자가 더 좁은 x-openclaw-scopes 헤더를 보내더라도 엔드포인트가 정상적인 전체 운영자 기본값을 복원합니다.
  • 신뢰된 ID 포함 HTTP 모드(예: trusted proxy 인증 또는 gateway.auth.mode="none")는 x-openclaw-scopes가 있으면 이를 따르고, 없으면 정상적인 운영자 기본 스코프 집합으로 대체됩니다.
  • 대상 agent 정책이 민감한 도구를 허용하면, 이 엔드포인트도 이를 사용할 수 있습니다.
  • 이 엔드포인트는 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
    • 이 엔드포인트의 chat 턴을 owner-sender 턴으로 취급함
  • 신뢰된 ID 포함 HTTP 모드(예: trusted proxy 인증 또는 비공개 인그레스의 gateway.auth.mode="none")
    • 어떤 외부 신뢰 ID 또는 배포 경계를 인증함
    • 헤더가 있으면 x-openclaw-scopes를 따름
    • 헤더가 없으면 정상적인 운영자 기본 스코프 집합으로 대체됨
    • 호출자가 명시적으로 스코프를 좁히고 operator.admin을 생략한 경우에만 owner 의미 체계를 잃음
Security 및 Remote access를 참조하세요.

​
Agent 우선 모델 계약

OpenClaw는 OpenAI model 필드를 원시 provider 모델 id가 아니라 agent 대상으로 취급합니다.
  • model: "openclaw"는 구성된 기본 agent로 라우팅됩니다.
  • model: "openclaw/default"도 구성된 기본 agent로 라우팅됩니다.
  • model: "openclaw/<agentId>"는 특정 agent로 라우팅됩니다.
선택적 요청 헤더:
  • x-openclaw-model: <provider/model-or-bare-id>는 선택된 agent의 백엔드 모델을 재정의합니다.
  • x-openclaw-agent-id: <agentId>는 호환성 재정의로 계속 지원됩니다.
  • x-openclaw-session-key: <sessionKey>는 세션 라우팅을 완전히 제어합니다.
  • x-openclaw-message-channel: <channel>은 채널 인식 프롬프트와 정책을 위한 synthetic ingress 채널 컨텍스트를 설정합니다.
호환성 별칭도 계속 허용됩니다:
  • 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는 거기서 안정적인 세션 키를 도출하므로, 반복 호출이 동일한 agent 세션을 공유할 수 있습니다.

​
왜 이 표면이 중요한가

이것은 셀프 호스팅 프런트엔드와 도구를 위한 가장 활용도 높은 호환성 집합입니다:
  • 대부분의 Open WebUI, LobeChat, LibreChat 설정은 /v1/models를 기대합니다.
  • 많은 RAG 시스템은 /v1/embeddings를 기대합니다.
  • 기존 OpenAI chat 클라이언트는 대체로 /v1/chat/completions로 시작할 수 있습니다.
  • 더 agent 중심적인 클라이언트는 점점 /v1/responses를 선호합니다.

​
모델 목록과 agent 라우팅

OpenClaw agent 대상 목록입니다.반환되는 id는 openclaw, openclaw/default, openclaw/<agentId> 항목입니다. 이를 OpenAI model 값으로 직접 사용하세요.
백엔드 provider 모델도 아니고 하위 agent도 아닌, 최상위 agent 대상만 나열합니다.하위 agent는 내부 실행 토폴로지로 남습니다. pseudo-model로 나타나지 않습니다.
openclaw/default는 구성된 기본 agent의 안정적인 별칭입니다.즉, 환경마다 실제 기본 agent id가 바뀌더라도 클라이언트는 예측 가능한 하나의 id를 계속 사용할 수 있습니다.
x-openclaw-model을 사용하세요.예시: x-openclaw-model: openai/gpt-5.4 x-openclaw-model: gpt-5.4이 헤더를 생략하면 선택된 agent는 정상적으로 구성된 모델 선택으로 실행됩니다.
/v1/embeddings는 같은 agent 대상 model id를 사용합니다.model: "openclaw/default" 또는 model: "openclaw/<agentId>"를 사용하세요. 특정 임베딩 모델이 필요하면 x-openclaw-model에 보내세요. 이 헤더가 없으면 요청은 선택된 agent의 일반적인 임베딩 설정으로 전달됩니다.

​
스트리밍(SSE)

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 token
  • 모델: openclaw/default
예상 동작:
  • GET /v1/models는 openclaw/default를 나열해야 합니다
  • Open WebUI는 openclaw/default를 chat 모델 id로 사용해야 합니다
  • 해당 agent에 대해 특정 백엔드 provider/model이 필요하면, agent의 일반 기본 모델을 설정하거나 x-openclaw-model을 보내세요
빠른 스모크 테스트: 
curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'
여기서 openclaw/default가 반환되면 대부분의 Open WebUI 설정은 같은 기본 URL과 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는 원시 provider 카탈로그가 아니라 OpenClaw agent 대상을 반환합니다.
  • openclaw/default는 항상 존재하므로 하나의 안정적인 id가 환경 전반에서 작동합니다.
  • 백엔드 provider/model 재정의는 OpenAI model 필드가 아니라 x-openclaw-model에 속합니다.
  • /v1/embeddings는 input으로 문자열 또는 문자열 배열을 지원합니다.