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 요청은 설정된 신뢰할 수 있는 프록시 소스에서 와야 합니다. 같은 호스트 루프백 프록시는 명시적으로 gateway.auth.trustedProxy.allowLoopback = true가 필요합니다.
• 프록시를 우회하는 내부 같은 호스트 호출자는 로컬 직접 폴백으로 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD를 사용할 수 있습니다. Forwarded, X-Forwarded-* 또는 X-Real-IP 헤더 증거가 있으면 대신 요청은 trusted-proxy 경로에 유지됩니다.
• 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가 있을 때 이를 존중하고, 없으면 일반 운영자 기본 범위 세트로 폴백합니다.
• 대상 에이전트 정책이 민감한 도구를 허용하면 이 엔드포인트가 이를 사용할 수 있습니다.
• 이 엔드포인트는 루프백/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을 생략할 때만 소유자 의미 체계를 잃습니다.
  • x-openclaw-model 같은 소유자 수준 요청 제어에는 operator.admin이 필요합니다.

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

이 엔드포인트를 사용할 때

기존 Gateway와 도구 또는 신뢰할 수 있는 앱 측 백엔드를 통합하고 Gateway 운영자 자격 증명을 안전하게 보관할 수 있을 때 /v1/chat/completions를 사용하세요.

• 통합이 같은 Gateway에 대한 또 다른 운영자/클라이언트 표면에 불과하다면 새 내장 채널을 추가하는 것보다 이를 선호하세요.
• 원격 Gateway에 직접 연결하는 네이티브 모바일 클라이언트의 경우 WebChat 또는 Gateway Protocol을 선호하고, 기기가 공유 HTTP 토큰/비밀번호를 필요로 하지 않도록 페어링된 기기 부트스트랩/기기 토큰 플로를 구현하세요.
• 자체 사용자, 방, Webhook 전달 또는 아웃바운드 전송이 있는 외부 메시징 네트워크를 통합하는 경우 대신 채널 Plugin을 빌드하세요. Plugin 빌드를 참조하세요.

에이전트 우선 모델 계약

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

• model: "openclaw"는 설정된 기본 에이전트로 라우팅합니다.
• model: "openclaw/default"도 설정된 기본 에이전트로 라우팅합니다.
• model: "openclaw/<agentId>"는 특정 에이전트로 라우팅합니다.

선택적 요청 헤더:

• x-openclaw-model: <provider/model-or-bare-id>는 선택된 에이전트의 백엔드 모델을 재정의합니다. 공유 비밀 bearer 호출자는 이 헤더를 사용할 수 있습니다. trusted-proxy 또는 x-openclaw-scopes가 있는 비공개 무인증 인그레스 요청 같은 ID 포함 호출자에게는 operator.admin이 필요합니다. 쓰기 전용 호출자는 403 missing scope: operator.admin을 받습니다.
• x-openclaw-agent-id: <agentId>는 호환성 재정의로 계속 지원됩니다.
• x-openclaw-session-key: <sessionKey>는 세션 라우팅을 명시적으로 제어합니다. 값은 subagent:, cron:, acp: 같은 예약된 내부 세션 네임스페이스를 사용하면 안 됩니다. 그런 요청은 400 invalid_request_error로 거부됩니다.
• 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는 여기에서 안정적인 세션 키를 파생하므로 반복 호출이 에이전트 세션을 공유할 수 있습니다.

커스텀 앱의 경우 가장 안전한 기본값은 대화 스레드별로 같은 user 값을 재사용하는 것입니다. 여러 대화나 기기가 하나의 OpenClaw 세션을 공유하길 명시적으로 원하는 경우가 아니라면 계정 수준 식별자는 피하세요. 여러 클라이언트나 스레드 간 명시적 라우팅 제어가 필요할 때만 x-openclaw-session-key를 사용하고, subagent:, cron:, acp: 같은 예약된 내부 네임스페이스로 시작하지 않는 애플리케이션 소유 키를 선택하세요.

이 표면이 중요한 이유

이는 자체 호스팅 프런트엔드와 도구를 위한 가장 영향력 있는 호환성 세트입니다.

• 대부분의 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]으로 끝납니다.

채팅 도구 계약

/v1/chat/completions는 일반적인 OpenAI Chat 클라이언트와 호환되는 함수 도구 하위 집합을 지원합니다.

지원되는 요청 필드

• tools: { "type": "function", "function": { ... } }의 배열
• tool_choice: "auto", "none", "required" 또는 { "type": "function", "function": { "name": "..." } }
• messages[*].role: "tool" 후속 턴
• 이전 도구 호출에 도구 결과를 다시 바인딩하기 위한 messages[*].tool_call_id
• max_completion_tokens: 숫자; 총 완료 토큰에 대한 호출별 한도(추론 토큰 포함). 현재 OpenAI Chat Completions 필드 이름입니다. max_completion_tokens와 max_tokens가 모두 전송되면 선호됩니다.
• max_tokens: 숫자; 이전 버전과의 호환성을 위해 허용되는 레거시 별칭입니다. max_completion_tokens도 있으면 무시됩니다.
• temperature: 숫자; 에이전트 스트림 매개변수 채널을 통해 업스트림 공급자에 전달되는 최선 노력 샘플링 온도입니다.
• top_p: 숫자; 에이전트 스트림 매개변수 채널을 통해 업스트림 공급자에 전달되는 최선 노력 nucleus 샘플링입니다.
• frequency_penalty: 숫자; 에이전트 스트림 매개변수 채널을 통해 업스트림 공급자에 전달되는 최선 노력 빈도 페널티입니다. 검증 범위: -2.0~2.0. 범위를 벗어난 값에는 400 invalid_request_error를 반환합니다.
• presence_penalty: 숫자; 에이전트 스트림 매개변수 채널을 통해 업스트림 공급자에 전달되는 최선 노력 존재 페널티입니다. 검증 범위: -2.0~2.0. 범위를 벗어난 값에는 400 invalid_request_error를 반환합니다.
• seed: 숫자(정수); 에이전트 스트림 매개변수 채널을 통해 업스트림 공급자에 전달되는 최선 노력 시드입니다. 정수가 아닌 값에는 400 invalid_request_error를 반환합니다.
• stop: 문자열 또는 최대 4개 문자열의 배열; 에이전트 스트림 매개변수 채널을 통해 업스트림 공급자에 전달되는 최선 노력 중지 시퀀스입니다. 4개를 초과하는 시퀀스 또는 문자열이 아니거나 비어 있는 항목에는 400 invalid_request_error를 반환합니다.

토큰 상한 필드 중 하나라도 설정되면, 해당 값은 에이전트 stream-param 채널을 통해 업스트림 제공자에 전달됩니다. 업스트림 제공자에 전송되는 실제 와이어 필드 이름은 제공자 전송 계층이 선택합니다. OpenAI 계열 엔드포인트에는 max_completion_tokens가 사용되고, Mistral 및 Chutes처럼 레거시 이름만 허용하는 제공자에는 max_tokens가 사용됩니다. 샘플링 필드(temperature, top_p, frequency_penalty, presence_penalty, seed)도 동일한 stream-param 채널을 따릅니다. ChatGPT 기반 Codex Responses 백엔드는 고정 샘플링을 사용하므로 서버 측에서 이 필드들을 제거합니다. stop도 stream-param 채널을 통해 전달되며 전송 계층의 stop 필드(Chat Completions 백엔드의 경우 stop, Anthropic의 경우 stop_sequences)로 매핑됩니다. OpenAI Responses API에는 stop 매개변수가 없으므로 Responses 기반 모델에는 stop이 적용되지 않습니다.

지원되지 않는 변형

엔드포인트는 다음을 포함한 지원되지 않는 도구 변형에 대해 400 invalid_request_error를 반환합니다.

• 배열이 아닌 tools
• function이 아닌 도구 항목
• 누락된 tool.function.name
• allowed_tools 및 custom 같은 tool_choice 변형
• 제공된 tools와 일치하지 않는 tool_choice.function.name 값

tool_choice: "required" 및 function으로 고정된 tool_choice의 경우, 엔드포인트는 노출된 클라이언트 function-tool 집합을 좁히고, 런타임에 응답 전에 클라이언트 도구를 호출하도록 지시하며, 에이전트 응답에 일치하는 구조화된 클라이언트 도구 호출이 포함되지 않으면 오류를 반환합니다. 이 계약은 호출자가 제공한 HTTP tools 목록에 적용되며, 모든 내부 OpenClaw 에이전트 도구에 적용되는 것은 아닙니다.

비스트리밍 도구 응답 형태

에이전트가 도구를 호출하기로 결정하면 응답은 다음을 사용합니다.

• choices[0].finish_reason = "tool_calls"
• 다음을 포함하는 choices[0].message.tool_calls[] 항목:
  • id
  • type: "function"
  • function.name
  • function.arguments (JSON 문자열)

도구 호출 전의 어시스턴트 설명은 choices[0].message.content에 반환됩니다(비어 있을 수 있음).

스트리밍 도구 응답 형태

stream: true일 때 도구 호출은 증분 SSE 청크로 방출됩니다.

• 초기 어시스턴트 역할 델타
• 선택적 어시스턴트 설명 델타
• 도구 ID와 인수 조각을 전달하는 하나 이상의 delta.tool_calls 청크
• finish_reason: "tool_calls"가 포함된 최종 청크
• data: [DONE]

stream_options.include_usage=true이면 [DONE] 전에 후행 사용량 청크가 방출됩니다.

도구 후속 루프

tool_calls를 받은 후 클라이언트는 요청된 function을 실행하고 다음을 포함하는 후속 요청을 보내야 합니다.

• 이전 어시스턴트 도구 호출 메시지
• 일치하는 tool_call_id가 있는 하나 이상의 role: "tool" 메시지

이를 통해 Gateway 에이전트 실행은 동일한 추론 루프를 계속하고 최종 어시스턴트 답변을 생성할 수 있습니다.

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로 사용해야 합니다.
• 해당 에이전트에 특정 백엔드 제공자/모델을 사용하려면 에이전트의 일반 기본 모델을 설정하거나, 공유 비밀 호출자 또는 operator.admin을 가진 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",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"Summarize my tasks for today"}]  }'

해당 대화에서 나중에 호출할 때 동일한 user 값을 재사용하면 같은 에이전트 세션을 계속할 수 있습니다.

비스트리밍:

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에 둡니다. ID를 포함하는 HTTP 인증 경로에서는 이 헤더에 operator.admin이 필요합니다.
• /v1/embeddings는 input을 문자열 또는 문자열 배열로 지원합니다.

관련 항목

• 구성 참조
• OpenAI