메인 콘텐츠로 건너뛰기

​
OpenAI

OpenAI는 GPT 모델용 개발자 API를 제공합니다. Codex는 구독 기반 액세스를 위한 ChatGPT 로그인과 사용량 기반 액세스를 위한 API 키 로그인을 지원합니다. Codex cloud는 ChatGPT 로그인이 필요합니다. OpenAI는 OpenClaw 같은 외부 도구/워크플로우에서 구독 OAuth를 사용하는 방식을 명시적으로 지원합니다.

​
옵션 A: OpenAI API 키 (OpenAI Platform)

적합한 경우: 직접 API에 접근하고 사용량 기반으로 과금할 때. API 키는 OpenAI 대시보드에서 발급받으세요.

​
CLI 설정

openclaw onboard --auth-choice openai-api-key
# or non-interactive
openclaw onboard --openai-api-key "$OPENAI_API_KEY"

​
설정 예시

{
  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 경로로 전달합니다.

​
옵션 B: OpenAI Code (Codex) 구독

적합한 경우: API 키 대신 ChatGPT/Codex 구독 액세스를 사용할 때. Codex cloud는 ChatGPT 로그인이 필요하고, Codex CLI는 ChatGPT 로그인 또는 API 키 로그인을 지원합니다.

​
CLI 설정 (Codex OAuth)

# Run Codex OAuth in the wizard
openclaw onboard --auth-choice openai-codex

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

​
설정 예시 (Codex subscription)

{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}
OpenAI의 현재 Codex 문서에는 현재 Codex 모델로 gpt-5.4가 나열되어 있습니다. OpenClaw는 이를 ChatGPT/Codex OAuth 용도에 맞게 openai-codex/gpt-5.4로 매핑합니다.

​
기본 전송 방식

OpenClaw는 모델 스트리밍에 pi-ai를 사용합니다. openai/*와 openai-codex/* 모두에서 기본 transport는 "auto"입니다(WebSocket 우선, 이후 SSE 폴백). agents.defaults.models.<provider/model>.params.transport를 설정할 수 있습니다.
  • "sse": SSE 강제 사용
  • "websocket": WebSocket 강제 사용
  • "auto": WebSocket을 시도한 뒤 SSE로 폴백
openai/*(Responses API)의 경우 WebSocket transport를 쓸 때 OpenClaw가 기본적으로 WebSocket 워밍업(openaiWsWarmup: true)도 활성화합니다. 관련 OpenAI 문서: 
{
  agents: {
    defaults: {
      model: { primary: "openai-codex/gpt-5.4" },
      models: {
        "openai-codex/gpt-5.4": {
          params: {
            transport: "auto",
          },
        },
      },
    },
  },
}

​
OpenAI WebSocket 워밍업

OpenAI 문서는 워밍업을 선택 사항으로 설명합니다. OpenClaw는 WebSocket transport 사용 시 첫 턴 지연 시간을 줄이기 위해 openai/*에 기본적으로 이를 활성화합니다.

​
워밍업 비활성화

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: false,
          },
        },
      },
    },
  },
}

​
워밍업 명시적 활성화

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

​
OpenAI 우선 처리

OpenAI API는 service_tier=priority를 통해 우선 처리을 노출합니다. OpenClaw에서는 agents.defaults.models["openai/<model>"].params.serviceTier를 설정해 직접 openai/* Responses 요청에 그 값을 전달합니다. 
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
      },
    },
  },
}
지원되는 값은 auto, default, flex, priority입니다.

​
OpenAI Responses 서버 측 compaction

직접 OpenAI Responses 모델(api.openai.com의 baseUrl과 api: "openai-responses"를 쓰는 openai/*)에서는 OpenClaw가 이제 OpenAI 서버 측 compaction payload hint를 자동으로 활성화합니다.
  • store: true를 강제합니다(model compat에서 supportsStore: false를 지정하지 않은 경우).
  • context_management: [{ type: "compaction", compact_threshold: ... }]를 주입합니다.
기본적으로 compact_threshold는 모델 contextWindow의 70%이며, 값을 알 수 없으면 80000을 사용합니다.

​
서버 측 compaction 명시적 활성화

호환되는 Responses 모델(예: Azure OpenAI Responses)에 context_management 주입을 강제로 적용하려면 다음과 같이 설정하세요. 
{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
          },
        },
      },
    },
  },
}

​
Enable with a custom threshold

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

​
Disable 서버 측 compaction

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: false,
          },
        },
      },
    },
  },
}
responsesServerCompaction은 context_management 주입만 제어합니다. 직접 OpenAI Responses 모델은 compat에서 supportsStore: false를 지정하지 않는 한 여전히 store: true를 강제합니다.

​
참고 사항

  • 모델 ref는 항상 provider/model 형식을 사용합니다(/concepts/models 참고).
  • 인증 세부 사항과 재사용 규칙은 /concepts/oauth에 있습니다.