OpenClaw Codex 하네스: 세션, 자격 증명 및 결제

OpenClaw Codex 하네스는 공식 @openclaw/codex 플러그인입니다. OpenClaw 에이전트 턴을 OpenAI의 Codex app-server에 넘겨 Codex가 모델 루프, 스레드 재개, 도구 연속 실행 및 압축을 담당하게 합니다. 이는 코딩 위임 제품도, 청구 계층도 아니며, 대부분의 설정에서 혼동을 일으키는 부분인 타사 API 엔드포인트에서 Codex를 실행하는 방법도 아닙니다. 실제로 필요한 것이 무엇인지 판단하는 것이 이 페이지의 목적입니다.

먼저 날짜를 확인해 두므로 여기에는 날짜가 빠진 내용이 없습니다. npm 패키지 openclaw는 2026.9.5이며 Node >=24.16.0 <25 || >=26.1.0가 필요합니다. @openclaw/codex도 2026.9.5이며 2026년 9월 18일에 게시되었습니다. 둘 다 2026년 9월 21일 레지스트리에서 확인했습니다. 서로 무관한 세 프로젝트가 이 이름을 공유하며, 그 어느 숫자도 여기와 관련이 없습니다. pjasicek/OpenClaw는 1997년 플랫폼 게임 Captain Claw의 재구현이라고 설명하고, 스코프가 없는 npm 패키지 codex는 2012년에 마지막으로 게시된 "정적 사이트 및 코드 문서 생성기"이며, OpenAI의 CLI는 @openai/codex입니다(같은 날짜에 0.155.1).

OpenClaw의 다섯 가지 표면이 "Codex"라는 이름을 공유합니다

OpenClaw의 agent-runtimes 문서는 이들이 "의도적으로 독립적"이라고 설명합니다. 잘못된 것을 선택하면 구성이 올바르게 보이는데도 아무 일도 일어나지 않는 것이 가장 흔한 이유입니다.

여섯 번째 이름은 OpenClaw의 이름이 아닙니다. openclaw-code-agent는 계획 승인과 worktree 격리를 통해 백그라운드 코딩 세션을 실행하는 타사 플러그인입니다. 자체 README에서는 OpenClaw에 번들된 acpx 런타임 플러그인 및 번들된 핵심 codex 플러그인과 별개라고 설명합니다. 런타임 교체가 아니라 위임을 원해서 여기 왔다면, 이는 다른 구성 키를 사용하는 다른 제품입니다.

하네스 활성화 및 활성화 여부 확인

문서화된 경로는 두 명령입니다. 플러그인을 설치한 다음 로그인합니다.

openclaw plugins install @openclaw/codex
openclaw models auth login --provider openai

그다음 최소 구성을 적용합니다. plugins.allow 목록을 사용하는 경우 "codex"도 목록에 추가하세요.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      // The docs' own example ref. Legacy codex-cli/* refs are
      // repaired to the same openai/<model> route by doctor --fix.
      model: "openai/gpt-6-astra",
    },
  },
}

하네스 문서에는 두 가지 세부 사항이 명시되어 있습니다. 하이브리드 재로드 모드에서는 플러그인 구성 변경 사항이 자동으로 적용되지만, 기존 채팅에서는 먼저 /new 또는 /reset가 필요합니다. 그래야 다음 턴이 현재 구성에서 하네스를 확인합니다. 또한 유효한 도구 프로필은 네이티브 셸 및 파일 시스템 기능을 허용해야 합니다. coding와 full는 이를 허용하지만 messaging와 minimal는 네이티브 표면을 비활성화합니다. 일반 OpenClaw 샌드박스 또는 제한된 도구 정책은 같은 문서에서 더 좁은 제한으로 설명됩니다. 실험적 샌드박스 exec-server 경로를 선택하지 않는 한 네이티브 코드 모드를 비활성화하며, 샌드박싱으로 네이티브 표면이 비활성화된 경우 허용된 셸 명령은 sandbox_exec를 통해 계속 접근할 수 있습니다.

버전 요구 사항은 2026년 9월 21일 app-server 전송 참조를 기준으로 확인했습니다. 플러그인은 안정 버전 Codex app-server 0.154.0을 관리하지만, 명시적 사용자 지정 실행 파일, 원격 app-server 및 macOS 데스크톱 바이너리는 0.149.0 이상의 파싱 가능한 시맨틱 버전을 보고해야 합니다. 같은 날 npm의 최신 @openai/codex는 0.155.1이므로 관리되는 고정 버전은 패치 하나만큼 뒤처져 있습니다. 따라서 날짜 없이 "Codex 최신 버전"이라고 말하는 튜토리얼은 며칠 안에 오래됩니다. 이전 설정을 마이그레이션하는 것도 중요합니다. agent-runtimes 페이지에 따르면 OpenClaw에 번들된 Codex CLI 백엔드는 v2026.5.14에서 제거되었으며, 레거시 codex-cli/* 참조는 동일한 openai/<model> Codex app-server 경로로 복구됩니다. 이 복구는 레거시 Codex 경로 복구 전반을 담당하는 openclaw doctor --fix에서 수행됩니다.

확인하려면 Codex 기반 턴의 /status 아래에 Runtime: OpenAI Codex가 표시되며, /codex status, /codex models 및 /codex binding가 app-server 상태를 검사합니다. openclaw doctor --lint --only codex/managed-app-server --json 린트는 관리되는 바이너리를 검사하지만, 문서에서는 이를 읽기 전용으로 설명하며 선택된 Codex Desktop 바이너리, 명시적 사용자 지정 명령 및 원격 app-server는 해당 패키지 검사 범위 밖에 둡니다.

이 기능을 기반으로 구축하기 전에 알아둘 긴장이 하나 있습니다. OpenAI 자체의 app-server 문서에는 "app-server 명령과 WebSocket 전송은 실험적이며 프로덕션 워크로드를 지원하지 않습니다"라고 명시되어 있습니다. 이 경고가 전송뿐 아니라 명령도 지칭한다는 점에 유의하세요. OpenClaw는 해당 명령 위에 제공 기능을 구축하며, transport 필드의 기본값은 stdio이고 websocket는 url를 구성할 때만 사용됩니다. 두 진술은 동시에 참이므로, 양쪽을 모두 고려해 결정하세요.

위임 아티팩트, 권한, 취소 및 재개

하네스 문서는 네이티브 서브에이전트의 상태가 입증하는 범위의 한계를 솔직하게 설명합니다. 실행, 작업 결과 및 결과 전달은 서로 별개의 사실이며, 유휴 상태이거나 중단되었거나 언로드된 네이티브 스레드라고 해서 작업이 성공했다는 뜻은 아닙니다. 종료 확인을 사용할 수 없는 경우 작업에서 종료를 다시 시도하도록 요청합니다. 네이티브 Codex 서브에이전트는 Codex 자체의 메커니즘이며, 명시적인 OpenClaw 또는 ACP 위임은 여전히 sessions_spawn을 거칩니다.

플러그인의 구성 필드 표에 따르면 app-server가 생성하는 OpenClaw 프로세스의 실행 권한은 기본적으로 모드 yolo, 승인 정책 never, 샌드박스 danger-full-access으로 설정됩니다. 단, 로컬 Codex 요구 사항이 이 구성을 허용하지 않으면 guardian 기본값은 요청 시 승인과 workspace-write를 선호하고, 그렇지 않으면 read-only를 사용합니다. 또한 app-server 제어 플레인 호출의 제한 시간인 requestTimeoutMs의 기본값은 60000입니다. 이는 Codex CLI 자체의 기본값이 아니라 OpenClaw가 실행하는 프로세스의 기본값이며, 익숙하지 않은 저장소에서는 첫 실행 전에 검토해야 할 설정입니다.

턴 중 제어는 네이티브 방식으로 제공됩니다: /codex stop, /codex steer, /codex resume, /codex detach, /codex bind, /codex compact, /codex threads, /codex goal, /codex model, /codex fast 및 /codex permissions. 제한된 턴은 세션 모드가 아니라 턴별로 적용되며, 해당 턴에 한해서만 네이티브 Code Mode, 환경 선택, 구성된 MCP 서버 및 네이티브 훅 릴레이를 비활성화합니다. OpenClaw의 runtime v1 지원 계약에는 네이티브 도구 인수 변경(사전 도구 훅은 차단할 수 있지만 OpenClaw가 인수를 다시 작성하지는 않음), 편집 가능한 Codex 네이티브 대화 기록, 압축 개입, 바이트 단위의 모델 API 요청 캡처도 지원되지 않는 항목으로 명시되어 있습니다. 따라서 감사 요구 사항이 정확한 송신 요청이라면 이 런타임으로는 제공할 수 없습니다.

인증, 플랜 자격 및 토큰 사용량은 서로 다른 세 가지 항목입니다

2026년 9월 21일 OpenClaw의 Codex app-server 정책 페이지에서 확인했습니다. 여기에는 먼저 주의해야 할 명명상의 함정이 하나 있습니다. OpenAI의 API 가격 페이지에는 Priority processing이 2026년 7월 30일에 Fast mode로 이름이 변경되었으며 service_tier에 "priority" 또는 "fast"를 보낼 수 있다고 나와 있습니다. 반면 OpenClaw의 appServer.serviceTier는 "priority" 및 "flex"을 문서화하고 레거시 "fast"을 "priority"로 정규화합니다. 즉 방향이 반대입니다. 두 시스템에서 “빠른 모드 켜기”는 서로 다른 의미를 가집니다.

타사 엔드포인트가 하네스를 벗어나는 이유

이는 대부분의 타사 설명이 거꾸로 설명하는 핵심 사실입니다. 프로바이더 또는 모델 런타임이 설정되지 않았거나 auto인 경우 OpenClaw의 암시적 에이전트 런타임 표는 다음과 같습니다:

따라서 OpenClaw를 어떤 타사 base URL에 연결하든(여기에는 Kunavo도 포함됨) 의도적으로 OpenClaw의 내장 런타임에서 턴이 실행됩니다. openai/* 접두사만으로는 하네스가 선택되지 않으며, agentRuntime.id: "codex"을 강제로 지정해도 이를 되돌릴 수 없습니다. 런타임 페이지에 따르면 해당 설정은 “등록된 Codex 하네스가 필요하며, 지원되지 않는 라우트/인증은 실행 전에 작성된 요청 재정의가 Codex가 선언한 정확한 요청의 OpenClaw 폴백을 사용할 수 있는 경우를 제외하고 실패로 종료된다”고 되어 있습니다. 따라서 가능한 결과는 실패한 턴 또는 OpenClaw 턴이며, 어느 쪽도 사용자 지정 엔드포인트의 Codex가 아닙니다. 플러그인의 문서화된 구성 필드에도 모델 base URL 설정은 없습니다. 해당 문서의 url 필드는 app-server 자체의 WebSocket 또는 unix:// 주소입니다. appServer.args가 관리되는 app-server에 프로바이더 재정의를 몰래 전달할 수 있는지는 문서화되지 않았고 테스트되지 않았습니다. 이 페이지에서는 이를 해결 방법으로 제시하지 않습니다.

내장 런타임 라우트는 요청의 형태도 바꾸며, OpenClaw의 사용자 지정 프로바이더 페이지는 각 규칙의 적용 범위를 구체적으로 설명합니다. 네이티브가 아닌 엔드포인트에서 api: "openai-completions"에 대해, 즉 호스트가 api.openai.com가 아닌 비어 있지 않은 baseUrl로 정의되는 경우, OpenClaw는 compat.supportsDeveloperRole를 false로 강제하고 명시적인 true를 재정의합니다. 이와 별도로 프록시 방식의 OpenAI 호환 라우트는 “네이티브 OpenAI 전용 요청 형식 지정을 건너뜁니다”: service_tier 없음, Responses store 없음, Completions store 없음, 프롬프트 캐시 힌트 없음, OpenAI 추론 호환 페이로드 형식 지정 없음, 숨겨진 attribution 헤더 없음입니다. 유선상에 service_tier가 없으므로 이러한 라우트에서는 Fast mode와 Flex를 선택할 수 없습니다. 같은 페이지에서 대신 제공하는 기능은 OpenAI 호환 Completions 프록시에 대한 params.extra_body 전달, 프로바이더별 headers, 느리거나 원격인 호스트를 위한 models.providers.<id>.timeoutSeconds입니다.

Codex 자체가 이야기의 다른 절반이며, 더 허용적입니다. Codex의 고급 구성 페이지에는 ~/.codex/config.toml이 [model_providers.<id>]를 base_url 및 env_key와 함께 지원한다고 나와 있습니다. 그러나 엄격한 조건이 있습니다. 구성 참조에는 model_providers.<id>.wire_api의 경우 “responses만 지원되는 값이며 생략하면 기본값으로 사용된다”고 명시되어 있습니다. 따라서 Chat Completions만 제공하는 엔드포인트로는 Codex를 구동할 수 없습니다. 같은 고급 구성 페이지에서는 기본 제공 ID인 openai, ollama, lmstudio을 예약하고, 프로젝트 수준 .codex/config.toml에서 Codex가 무시하는 키로 model_provider 및 model_providers를 열거하므로 프로바이더 키는 사용자 수준 구성에 넣어야 합니다. Kunavo는 /v1/responses에서 네이티브 Responses 인터페이스를 구현하며, 이것이 Codex CLI 설정을 가능하게 합니다. 그러나 이는 독립 실행형 Codex CLI이며 OpenClaw 하네스가 아닙니다. 또한 Kunavo는 어느 클라이언트도 런타임 테스트하지 않았습니다.

소프트웨어 비용과 토큰 비용

OpenClaw 자체는 $0입니다. 문서 색인은 이 프로젝트가 MIT 라이선스이며, 커뮤니티 주도로 운영되고, 독립적인 501(c)(3) 재단이 개발하며, “유료 등급 없음”이라고 설명합니다. @openclaw/codex은 공개 npm 레지스트리에 무료로 게시되어 있습니다. 실제 비용은 Gateway를 실행하는 머신과 모델 사용량뿐이며, 모델 사용량은 세 가지 계약 중 하나에 따라 발생합니다.

2026년 9월 21일 확인한 OpenAI의 Codex 가격 페이지 기준입니다. 이 표와 함께 세 가지 주의 사항을 알아야 합니다. 가격 카드에는 Pro에 대해 “From $100”만 게시되어 있습니다. OpenAI의 별도 ChatGPT Pro 등급 정보 문서에는 더 높은 $200 등급이 명시되어 있지만, 2026년 9월 10일 현재 신규 가입과 업그레이드가 일시 중지되어 있으므로 이 페이지의 가격 카드에서 확인하지 못한 금액을 예산에 반영하지 말고 결제 시 확인하세요. 포함 사용량은 고정된 메시지 수가 아니라 5시간당 로컬 메시지의 추정 범위로만 게시되어 있습니다. 또한 포함 한도를 초과한 크레딧 요금은 100만 토큰당 크레딧으로 게시되어 있으며 해당 가격 페이지에는 크레딧의 달러 가치가 없으므로 해당 행에 대한 달러 환산을 제공하지 않습니다. 별도로 GPT-5.5는 2026년 10월 14일 모든 플랜의 ChatGPT, ChatGPT Work 및 Codex에서 종료되지만 OpenAI API에는 영향을 주지 않습니다.

세 번째 계약은 OpenClaw의 내장 런타임에 있는 게이트웨이입니다. 캐시되지 않은 입력 토큰 180,000개를 보내고 출력 토큰 9,000개를 받는 위임 턴 하나를 가정합니다. 요금은 100만 토큰당 Kunavo 카탈로그의 현재 가격입니다.

이는 측정된 작업 비용이나 청구 상한이 아닌 예시적인 토큰 계산입니다. 턴의 형태는 가정이며 실제 에이전트 턴은 모든 도구 왕복마다 컨텍스트를 다시 전송합니다. Kunavo의 카탈로그 금액은 상한이 아니라 청구 하한입니다. 업스트림에서 요금을 보고하면 청구액은 카탈로그 비용과 업스트림 비용에 해당 마크업을 곱한 금액 중 더 큰 값입니다. 캐시 요금과 외부 도구는 이 예시에 포함되지 않습니다. 최소 충전 금액은 선불 크레딧 $10이며, 이는 플랜을 구매하는 것이 아니라 잔액을 충전합니다. 결제 세부 정보를 참조하세요.

Kunavo는 임베딩 모델, 텍스트 음성 변환 모델 및 음성 텍스트 변환 모델을 제공하지 않습니다. 이러한 단계는 어떤 라우트에서도 Kunavo가 제공하지 않으므로 이를 제공하는 프로바이더를 이용하세요.

이 경계가 중요한 이유는 위의 인터페이스 표에서 비에이전트 OpenAI Platform 라우트를 하네스와 별도로 유지하고, Gateway 키가 Kunavo 카탈로그의 채팅 모델만 포함하기 때문입니다.

어떤 경우에 어떤 경로가 적합한가

답이 Gateway 행이라면 Responses API 형식은 Codex CLI 통합에서 시작하고, OpenClaw에 가장 적합한 API 및 Codex에 가장 적합한 API에서 옵션을 비교한 다음, 키에 자금을 충전할 준비가 되면 Kunavo 계정 생성으로 이동하세요. 자체 호스팅 어시스턴트의 예산 측면에서는 OpenClaw 가격에서 소프트웨어, 호스팅 및 모델 비용을 구분합니다.

자주 묻는 질문

위의 런타임 표, 인증 순서, app-server 경고, wire_api 게이트, 버전 고정 및 플랜 가격은 2026년 9월 21일 OpenClaw와 OpenAI의 자체 문서, OpenAI 도움말 센터 및 openclaw, @openclaw/codex, @openai/codex, codex 및 openclaw-code-agent의 npm 레지스트리 항목에서 가져왔습니다. 각 주장은 출처 페이지에 연결되어 있으며, 문서에서 질문에 대한 결론을 내리지 못한 경우에는 빈틈을 임의로 채우지 않고 그렇게 명시했습니다. Kunavo는 OpenClaw 또는 Codex 하네스에 대한 런타임 테스트를 수행하지 않았으므로 여기의 모든 구성은 Kunavo의 엔드포인트에서 시연된 것이 아니라 원본 문서와 대조하여 확인한 것입니다. Kunavo 토큰 요금은 현재 카탈로그에서 가져왔으며, 각 달러 수치는 예시적인 계산입니다.