콘텐츠로 이동
OpenClaw

OpenClaw에 OpenAI API 및 Codex 구독 연동하기

개발을 하다 보면 OpenAI API를 직접 호출해서 쓸지, 아니면 이미 결제 중인 ChatGPT 구독 권한을 활용할지 고민되는 순간이 많죠. 비용 효율성과 성능 사이에서 최적의 균형을 찾는 건 모든 개발자의 숙제이기도 해요. OpenClaw는 이런 고민을 해결할 수 있도록 두 가지 방식 모두를 깔끔하게 지원하고 있어요.

OpenAI

섹션 제목: “OpenAI”

OpenAI는 GPT 모델을 위한 개발자 API를 제공해요. Codex는 구독형 접근을 위한 ChatGPT sign-in 방식과 사용량 기반 결제를 위한 API key 로그인 방식을 모두 지원하죠. Codex cloud를 사용하려면 ChatGPT sign-in이 필요해요. OpenAI는 OpenClaw와 같은 외부 도구에서 구독형 OAuth를 사용하는 것을 공식적으로 지원하고 있어요.

옵션 A: OpenAI API key (OpenAI Platform)

섹션 제목: “옵션 A: OpenAI API key (OpenAI Platform)”

추천 대상: API에 직접 접근하고 사용한 만큼만 비용을 지불하고 싶을 때 가장 좋아요. OpenAI 대시보드에서 API key를 발급받으세요.

CLI setup

섹션 제목: “CLI setup”
Terminal window
openclaw onboard --auth-choice openai-api-key
# or non-interactive
openclaw onboard --openai-api-key "$OPENAI_API_KEY"

Config snippet

섹션 제목: “Config snippet”
{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}

OpenAI의 현재 API 모델 문서를 보면 직접적인 OpenAI API 사용을 위해 gpt-5.4와 gpt-5.4-pro가 나열되어 있어요. OpenClaw는 이 두 모델을 openai/* Responses 경로를 통해 전달해요. OpenClaw는 의도적으로 오래된 openai/gpt-5.3-codex-spark 행을 숨기는데, 실제 트래픽에서 직접적인 OpenAI API 호출이 이를 거부하기 때문이에요.

OpenClaw는 직접적인 OpenAI API 경로에서 openai/gpt-5.3-codex-spark를 노출하지 않아요. pi-ai에는 여전히 해당 모델을 위한 내장 행이 포함되어 있지만, 현재 실제 OpenAI API 요청은 이를 거부하고 있어요. Spark는 OpenClaw에서 Codex 전용으로 취급돼요.

옵션 B: OpenAI Code (Codex) 구독

섹션 제목: “옵션 B: OpenAI Code (Codex) 구독”

추천 대상: API key를 사용하는 대신 ChatGPT/Codex 구독 권한을 활용하고 싶을 때 가장 좋아요. Codex cloud는 ChatGPT sign-in이 필요하며, Codex CLI는 ChatGPT 또는 API key 로그인을 모두 지원해요.

CLI setup (Codex OAuth)

섹션 제목: “CLI setup (Codex OAuth)”
Terminal window
# Run Codex OAuth in the wizard
openclaw onboard --auth-choice openai-codex


# Or run OAuth directly
openclaw models auth login --provider openai-codex

Config snippet (Codex subscription)

섹션 제목: “Config snippet (Codex subscription)”
{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}

OpenAI의 현재 Codex 문서는 gpt-5.4를 최신 Codex 모델로 나열하고 있어요. OpenClaw는 ChatGPT/Codex OAuth 사용을 위해 이를 openai-codex/gpt-5.4로 매핑해요.

만약 Codex 계정에 Codex Spark 권한이 있다면, OpenClaw는 다음 모델도 지원해요:

  • openai-codex/gpt-5.3-codex-spark

OpenClaw는 Codex Spark를 Codex 전용으로 처리해요. 직접적인 openai/gpt-5.3-codex-spark API-key 경로는 제공하지 않아요.

또한 OpenClaw는 pi-ai가 발견한 openai-codex/gpt-5.3-codex-spark를 유지해요. 이 모델은 권한에 따라 사용 여부가 달라지는 실험적인 기능으로 생각하는 것이 좋아요. Codex Spark는 GPT-5.4 /fast와는 별개이며, 사용 가능 여부는 로그인된 Codex / ChatGPT 계정에 따라 달라져요.

Transport default

섹션 제목: “Transport default”

OpenClaw는 모델 스트리밍을 위해 pi-ai를 사용해요. openai/*와 openai-codex/* 모두 기본 transport는 "auto" (WebSocket 우선, 이후 SSE fallback)예요.

agents.defaults.models.<provider/model>.params.transport 설정을 통해 변경할 수 있어요:

  • "sse": SSE 강제 사용
  • "websocket": WebSocket 강제 사용
  • "auto": WebSocket을 먼저 시도하고 실패하면 SSE로 전환

openai/* (Responses API)의 경우, WebSocket transport를 사용할 때 OpenClaw는 기본적으로 WebSocket warm-up을 활성화해요 (openaiWsWarmup: true).

관련 OpenAI 문서:

{
  agents: {
    defaults: {
      model: { primary: "openai-codex/gpt-5.4" },
      models: {
        "openai-codex/gpt-5.4": {
          params: {
            transport: "auto",
          },
        },
      },
    },
  },
}

OpenAI WebSocket warm-up

섹션 제목: “OpenAI WebSocket warm-up”

OpenAI 문서는 warm-up을 선택 사항으로 설명하고 있어요. 하지만 OpenClaw는 WebSocket transport 사용 시 첫 번째 응답의 지연 시간을 줄이기 위해 openai/*에 대해 기본적으로 이 기능을 활성화해요.

Disable warm-up

섹션 제목: “Disable warm-up”
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: false,
          },
        },
      },
    },
  },
}

Enable warm-up explicitly

섹션 제목: “Enable warm-up explicitly”
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: true,
          },
        },
      },
    },
  },
}

OpenAI and Codex priority processing

섹션 제목: “OpenAI and Codex priority processing”

OpenAI API는 service_tier=priority를 통해 우선순위 처리를 지원해요. OpenClaw에서는 agents.defaults.models["<provider>/<model>"].params.serviceTier를 설정해서 네이티브 OpenAI/Codex Responses 엔드포인트에 해당 필드를 전달할 수 있어요.

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
        "openai-codex/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

지원되는 값은 auto, default, flex, priority예요.

OpenClaw는 모델이 네이티브 OpenAI/Codex 엔드포인트를 가리킬 때 params.serviceTier를 직접적인 openai/* Responses 요청과 openai-codex/* Codex Responses 요청 모두에 전달해요.

중요한 동작 규칙:

  • 직접적인 openai/* 호출은 반드시 api.openai.com을 대상으로 해야 해요.
  • openai-codex/* 호출은 반드시 chatgpt.com/backend-api를 대상으로 해야 해요.
  • 만약 다른 베이스 URL이나 프록시를 통해 라우팅하는 경우, OpenClaw는 service_tier 값을 수정하지 않고 그대로 둡니다.

OpenAI fast mode

섹션 제목: “OpenAI fast mode”

OpenClaw는 openai/*와 openai-codex/* 세션 모두에서 사용할 수 있는 공통 fast-mode 토글을 제공해요:

  • Chat/UI: /fast status|on|off
  • Config: agents.defaults.models["<provider>/<model>"].params.fastMode

fast mode가 활성화되면 OpenClaw는 이를 OpenAI priority processing에 매핑해요:

  • api.openai.com으로 보내는 직접적인 openai/* Responses 호출에 service_tier = "priority"를 전송해요.
  • chatgpt.com/backend-api로 보내는 openai-codex/* Responses 호출에도 service_tier = "priority"를 전송해요.
  • 기존 페이로드에 있는 service_tier 값은 유지돼요.
  • fast mode는 reasoning이나 text.verbosity를 다시 작성하지 않아요.

예시:

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            fastMode: true,
          },
        },
        "openai-codex/gpt-5.4": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}

세션 override 설정이 구성 파일 설정보다 우선순위가 높아요. 세션 UI에서 override를 해제하면 다시 구성 파일에 설정된 기본값으로 돌아가요.

OpenAI Responses server-side compaction

섹션 제목: “OpenAI Responses server-side compaction”

직접적인 OpenAI Responses 모델(api: "openai-responses"를 사용하고 baseUrl이 api.openai.com인 openai/*)의 경우, OpenClaw는 이제 OpenAI server-side compaction 페이로드 힌트를 자동으로 활성화해요:

  • store: true를 강제해요 (모델 호환성 설정에서 supportsStore: false인 경우는 제외).
  • context_management: [{ type: "compaction", compact_threshold: ... }]를 주입해요.

기본적으로 compact_threshold는 모델 contextWindow의 70%로 설정돼요 (정보가 없는 경우 80000으로 설정).

Enable server-side compaction explicitly

섹션 제목: “Enable server-side compaction explicitly”

Azure OpenAI Responses와 같이 호환되는 Responses 모델에서 context_management 주입을 강제하고 싶을 때 사용하세요:

{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
          },
        },
      },
    },
  },
}

Enable with a custom threshold

섹션 제목: “Enable with a custom threshold”
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
            responsesCompactThreshold: 120000,
          },
        },
      },
    },
  },
}

Disable server-side compaction

섹션 제목: “Disable server-side compaction”
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: false,
          },
        },
      },
    },
  },
}

responsesServerCompaction은 오직 context_management 주입만 제어해요. 직접적인 OpenAI Responses 모델은 호환성 설정에서 supportsStore: false로 되어 있지 않는 한 여전히 store: true를 강제해요.

참고 사항

섹션 제목: “참고 사항”
  • 모델 참조는 항상 provider/model 형식을 사용해요 (/concepts/models 참고).
  • 인증 세부 정보와 재사용 규칙은 /concepts/oauth에서 확인할 수 있어요.

다음 단계

섹션 제목: “다음 단계”

AI Setup Assistant

OpenClaw

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.