OpenClaw에서 이미지 모델을 지정할 때 값은 openai/gpt-image-2입니다. 하지만 모델명을 넣었다고 해서 실제 GPT Image 2 경로가 통과한 것은 아닙니다. 먼저 인증 경로를 정해야 합니다. 운영, 청구, 조직 제어, 로그 추적이 필요하면 OPENAI_API_KEY; 이미 Codex profile을 쓰고 있고 가벼운 검증만 필요하면 Codex OAuth를 검토합니다.
첫 이미지가 생성되었다고 바로 믿으면 안 됩니다. OpenClaw에는 fallback provider가 있을 수 있고, OpenAI 경로가 실패한 뒤 다른 provider가 이미지를 반환할 수 있습니다. OAuth profile도 오래된 token, 다른 account, 예상과 다른 workspace를 가리킬 수 있습니다.
| 경로 | 쓰는 상황 | 검증 방법 | 전환 신호 |
|---|---|---|---|
OPENAI_API_KEY | 운영 청구, 조직 제어, 팀 로그, 지원 책임이 필요 | 로그가 OpenAI provider와 openai/gpt-image-2를 보여줌 | 비용, quota, 조직 정책 때문에 경로를 바꿀 때 |
| Codex OAuth | Codex profile 기반의 개인 검증이나 가벼운 테스트 | active profile, account/workspace, provider 출력, no-fallback 테스트가 일치 | 403, stale profile, workspace 불명, OpenAI route 미표시 |
| fallback provider | OpenAI 실패 뒤 백업 이미지 경로로 의도적으로 사용 | non-OpenAI fallback으로 표시 | GPT Image 2 자체를 검증하는 중 |
Codex OAuth에서 HTTP 403이 나오면 prompt를 더 고치지 말고 멈춥니다. OpenClaw version, OAuth token, active account, workspace, provider output, fallback 설정을 확인하세요. 투명 배경이 필요하다면 gpt-image-2에 계속 요청하지 말고 지원되는 모델이나 후처리로 분리합니다.
openai/gpt-image-2 설정
OpenAI의 모델 ID는 gpt-image-2입니다. OpenClaw에서는 provider prefix가 붙어 openai/gpt-image-2가 됩니다. 이 openai/는 장식이 아니라 image request를 OpenAI provider layer로 보내는 경로 지정입니다.
처음에는 최소 설정만 사용합니다. provider, auth, fallback, prompt를 동시에 바꾸면 성공해도 무엇이 맞았는지 알 수 없고, 실패해도 어디가 막혔는지 읽기 어렵습니다.
hljs json{
"agents": {
"defaults": {
"imageGenerationModel": {
"primary": "openai/gpt-image-2"
}
}
}
}
API Key 경로에서는 OpenClaw가 실행되는 환경에 OPENAI_API_KEY를 둡니다. 이 경로의 장점은 OpenAI Platform에서 billing, project, organization, quota, API response를 확인하기 쉽다는 점입니다.
hljs bashexport OPENAI_API_KEY="sk-..."
Codex OAuth 경로에서는 가짜 API Key를 만들지 않습니다. OpenClaw의 OAuth flow로 OpenAI Codex profile을 인증하고, 현재 account와 workspace가 무엇인지 확인한 뒤 같은 openai/gpt-image-2를 사용합니다. 편하지만 token refresh와 profile 선택이 운영 입력값이 됩니다.
| 질문 | API Key 경로 | Codex OAuth 경로 |
|---|---|---|
| 요청의 owner | OPENAI_API_KEY와 연결된 OpenAI organization/project | OpenClaw OAuth profile 뒤의 OpenAI/Codex account |
| quota와 billing 확인 위치 | OpenAI Platform | OpenClaw profile과 해당 account/workspace |
| 경로 증거 | provider 출력에 OpenAI와 openai/gpt-image-2가 보임 | OAuth-backed OpenAI와 fallback 없음이 보임 |
이미지를 믿기 전에 경로부터 확인
먼저 provider inventory를 봅니다. OpenClaw의 image generation은 provider-aware이므로 최종 파일만으로는 충분하지 않습니다. provider path, selected model, auth owner, fallback state가 필요합니다.
hljs bashimage_generate action=list
그다음 작은 명시 테스트를 실행합니다. prompt는 단순해야 합니다. 텍스트 렌더링, 투명 배경, 큰 size, 복잡한 edit을 넣으면 경로 검증이 아니라 모델 능력 테스트가 됩니다.
hljs bashimage_generate model=openai/gpt-image-2 prompt="A simple product icon on a white desk, no text"
결과는 운영 로그처럼 읽습니다. 이미지가 성공했지만 provider가 OpenAI가 아니면 fallback입니다. Codex OAuth에서 403이면 profile, account, workspace, token을 봅니다. model not found라면 provider prefix, OpenClaw version, model access를 확인합니다.
| 결과 | 의미 | 다음 조치 |
|---|---|---|
이미지 성공, 로그에 openai/gpt-image-2 | 의도한 경로가 동작 | 설정 저장 후 필요한 fallback을 label과 함께 복구 |
| 이미지 성공, provider가 OpenAI가 아님 | fallback이 처리 | non-OpenAI 출력으로 표시하고 OpenAI 경로 격리 |
| Codex OAuth 403 | OAuth-backed route 차단 | 재인증, workspace 확인, OpenClaw update, API Key 전환 |
| model not found | provider가 모델을 노출하지 않음 | prefix, version, model access 확인 |
| 투명 배경 실패 | unsupported option | transparency 제거 또는 별도 workflow 사용 |
운영 환경은 API Key가 더 명확함
OPENAI_API_KEY는 고객 작업, batch job, 내부 승인, 장애 대응, 팀 공유가 있을 때 더 다루기 쉽습니다. 실패하면 OpenClaw log와 OpenAI API response를 함께 볼 수 있고, 성공하면 청구와 account owner를 설명할 수 있습니다.
API Key가 항상 더 싸다는 뜻은 아닙니다. 장점은 감사 가능성입니다. 어떤 organization, project, quota, billing 상태에서 어떤 model request가 나갔는지 기록하기 쉽습니다.
| 운영 요구 | API Key가 깔끔한 이유 |
|---|---|
| 청구 귀속 | usage가 OpenAI API project/org에 남음 |
| 장애 대응 | OpenClaw log와 API response를 대조 가능 |
| 반복 생성 | quota, cost, retry policy owner가 안정적 |
| 여러 사용자 | 개인 OAuth profile보다 중앙 제어가 쉬움 |
| account 경계 | platform route가 감사 기록에 적합 |
비용이 핵심이라면 OpenClaw 설정 글이 아니라 비용 비교로 이동합니다. 저렴한 GPT Image 2 API 경로는 provider 비용과 tradeoff를 다루는 곳입니다.
Codex OAuth는 profile 증거가 있을 때만
Codex OAuth는 이미 Codex login을 쓰는 OpenClaw 사용자에게 가볍게 느껴집니다. 별도 API Key 관리 없이 supported path를 시험할 수 있어 개인 검증에는 편합니다.
하지만 OAuth는 공식 무료 API 권한이 아닙니다. 인증된 profile입니다. stale token, wrong account, wrong workspace, image route 미지원, OpenClaw version mismatch가 모두 prompt 문제처럼 보일 수 있습니다.
| 체크 | 확인할 것 |
|---|---|
| active profile | OpenClaw가 의도한 OpenAI/Codex account를 가리킴 |
| token state | OAuth storage와 refresh가 정상이고 오래된 인증이 없음 |
| workspace/account | image route가 예상치 못한 workspace에서 실행되지 않음 |
| provider output | OpenAI와 openai/gpt-image-2로 resolve됨 |
| no-fallback test | 다른 provider가 OAuth 실패를 가리지 못함 |
403은 route diagnosis입니다. 재인증하고 오래된 profile state를 지우고 OpenClaw build를 확인하고 model availability를 본 뒤 fallback 없이 다시 시도하세요. 같은 403이 계속되면 API Key로 전환합니다.
403, fallback, 미지원 옵션 분리
대부분의 실패는 auth, provider selection, unsupported parameter, environment readiness 중 하나입니다. 이 순서로 분리해야 다음 성공이 무엇을 해결했는지 알 수 있습니다.
| 증상 | 첫 분기 | 첫 확인 | 더 나은 조치 |
|---|---|---|---|
| Codex OAuth 403 | auth/profile | account, workspace, token, OpenClaw version | 재인증 후 fallback 없이 재실행 |
| 이미지 성공 but OpenAI 아님 | provider selection | fallback note와 provider output | fallback 끄고 model=openai/gpt-image-2 강제 |
image_generate 없음 | environment/tooling | image provider 설정 여부 | provider 설정 먼저 완료 |
openai/gpt-image-2 거부 | model reference | prefix와 docs version | model ref와 access 확인 |
| 투명 배경 실패 | unsupported parameter | background option | transparency 제거 또는 별도 단계 |
| 느리거나 불안정 | route/capacity | quota, fallback, size, quality | retry 전에 route proof 확보 |
투명 배경은 중단 조건입니다. gpt-image-2로 직접 transparent output을 기대하지 말고, 생성 후 다른 모델이나 편집 단계로 분리합니다. 4K도 별도입니다. OpenClaw 검증은 누가 생성했는지, 고해상도 검증은 어떤 파일 크기로 저장됐는지를 답합니다.
경로 승인 기록
운영 체크리스트
동료나 자동화에 넘기기 전에 운영 계약을 기록합니다. model reference, auth owner, route proof, fallback policy, failure branch, switch trigger가 있어야 합니다.
| 항목 | API Key 경로 | Codex OAuth 경로 |
|---|---|---|
| model reference | openai/gpt-image-2 | openai/gpt-image-2 |
| auth owner | OPENAI_API_KEY의 OpenAI project/org | OpenAI Codex OAuth profile |
| route proof | provider 출력 또는 log가 OpenAI를 표시 | provider 출력이 OAuth-backed OpenAI 표시 |
| fallback policy | 검증 중 off, 운영 중 label 표시 | 검증 중 off, 운영 중 label 표시 |
| failure branch | OpenAI API response + OpenClaw logs | OAuth profile/account + OpenClaw logs |
| switch trigger | cost, quota, org policy, provider strategy | 403, stale profile, workspace 불명, audit 필요 |
작은 smoke prompt도 보관합니다. text, transparency, 큰 size, 복잡한 edit은 피합니다. smoke test는 품질 평가가 아니라 경로 건강 확인입니다.
자주 묻는 질문
OpenClaw 모델명은 무엇을 써야 하나요?
openai/gpt-image-2를 사용합니다. OpenAI 모델 ID는 gpt-image-2이고, OpenClaw는 OpenAI provider로 보내기 위해 openai/ prefix를 붙입니다.
Codex OAuth면 GPT Image 2 API가 무료인가요?
아닙니다. Codex OAuth는 인증 경로이지 공식 무료 API 권리가 아닙니다. 무료 경계와 안전한 테스트는 GPT Image 2 API 무료 경계에서 확인합니다.
API Key와 Codex OAuth 중 무엇을 선택하나요?
운영은 API Key가 더 명확합니다. 청구, 조직 제어, 로그, 지원 책임이 분명합니다. Codex OAuth는 profile과 no-fallback 증거가 있을 때 가벼운 검증에 씁니다.
Codex OAuth에서 HTTP 403이 나는 이유는?
auth/profile 문제로 봅니다. OpenClaw version, OAuth token, active account, workspace, model access, fallback config를 확인합니다.
fallback이 이미지를 만든 게 아님을 어떻게 증명하나요?
fallback을 끄고 model=openai/gpt-image-2를 강제한 뒤 provider output 또는 log를 봅니다. 다른 provider가 보이면 OpenAI route 성공이 아닙니다.
투명 배경을 직접 만들 수 있나요?
gpt-image-2를 transparent background 출력 전제로 쓰지 마세요. 생성 후 별도 모델이나 편집 단계로 처리합니다.
OpenClaw에서 4K도 가능한가요?
먼저 OpenClaw가 openai/gpt-image-2로 보냈음을 증명하고, 그 뒤 size 설정과 저장된 pixel을 별도 workflow에서 확인합니다.
