OpenClaw Gateway에서 OpenAI 호환 API 사용하기

새로운 AI 도구를 도입할 때마다 매번 다른 API 규격에 맞춰 코드를 수정하는 일은 꽤 번거롭습니다. 이미 익숙한 OpenAI 라이브러리를 그대로 활용하면서 내부적으로는 OpenClaw의 에이전트를 호출할 수 있다면 개발 프로세스가 훨씬 단순해질 거예요.

OpenClaw Gateway는 OpenAI와 호환되는 Chat Completions 엔드포인트를 제공합니다. 이를 통해 기존에 사용하던 OpenAI SDK나 도구들을 큰 수정 없이 OpenClaw와 연결할 수 있습니다.

필요한 것

• 설정 파일 수정이 가능한 OpenClaw Gateway 인스턴스
• Gateway 인증 설정 정보 (token 또는 password)
• Gateway가 실행 중인 호스트 주소와 포트 정보

빠른 시작

이 엔드포인트는 보안을 위해 기본적으로 비활성화되어 있습니다. 5분 안에 설정을 마치고 첫 메시지를 보내는 방법은 다음과 같습니다.

1. 엔드포인트 활성화하기

json5 구성 파일에서 chatCompletions 활성화 옵션을 true로 변경하세요.

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

2. 인증 방식 확인하기

Gateway의 auth.mode 설정에 따라 Bearer 토큰으로 보낼 값을 준비하세요.

• mode="token"인 경우: gateway.auth.token 사용
• mode="password"인 경우: gateway.auth.password 사용

3. 에이전트 호출하기

cURL을 사용하여 main 에이전트에게 요청을 보내보세요. 엔드포인트는 Gateway와 동일한 포트를 사용합니다.

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

4. 스트리밍 응답 받기

실시간 응답이 필요하다면 stream: true를 추가하세요. text/event-stream 규격에 맞는 데이터를 받을 수 있습니다.

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 인스턴스에 대한 **전체 관리자 권한(full operator-access)**을 가집니다.

• 사용자별로 권한을 잘게 나누는 모델이 아닙니다. 이 API에 접근할 수 있는 토큰을 가진 사람은 Gateway의 소유자와 동일한 권한을 가집니다.
• 에이전트 정책이 민감한 도구 사용을 허용하고 있다면, 이 엔드포인트를 통해서도 해당 도구들을 실행할 수 있습니다.
• 이 엔드포인트를 공용 인터넷에 직접 노출하지 마세요. 반드시 loopback, tailnet 또는 프라이빗 인그레스 환경에서만 운영해야 합니다.

에이전트 선택 방법

OpenAI의 model 필드에 에이전트 ID를 넣거나 전용 헤더를 사용할 수 있습니다.

• model: "openclaw:<agentId>" 또는 model: "agent:<agentId>"
• 헤더 사용 시: x-openclaw-agent-id: <agentId> (기본값: main)

세션 관리

기본적으로 각 요청은 Stateless하게 처리되며 매번 새로운 세션 키가 생성됩니다. 하지만 OpenAI 요청 바디에 user 문자열을 포함하면, Gateway가 이를 기반으로 고정된 세션 키를 생성하여 에이전트 세션을 유지할 수 있게 해줍니다.

문제 해결

• 429 Too Many Requests: 인증 실패가 너무 자주 발생하여 gateway.auth.rateLimit에 걸린 경우입니다. 응답 헤더의 Retry-After 시간을 확인한 뒤 다시 시도하세요.
• 엔드포인트 접속 불가: gateway.http.endpoints.chatCompletions.enabled 설정이 true로 되어 있는지 다시 한번 확인해 보세요.

더 자세한 설정 방법이 궁금하다면 AI Setup Assistant의 도움을 받아보세요.

다음 단계

• Security
• Remote access