Codex 하네스

공식 codex Plugin은 내장 OpenClaw 하네스 대신 Codex app-server를 통해 임베디드 OpenAI 에이전트 턴을 실행합니다. Codex는 네이티브 스레드 재개, 네이티브 도구 연속 실행, 네이티브 Compaction, app-server 실행을 포함하는 저수준 에이전트 세션을 소유합니다. OpenClaw는 계속해서 채팅 채널, 세션 파일, 모델 선택, OpenClaw 동적 도구, 승인, 미디어 전달 및 표시되는 트랜스크립트 미러를 소유합니다.

openai/gpt-5.6-sol과 같은 표준 OpenAI 모델 참조를 사용하십시오. 레거시 Codex GPT 참조를 구성하지 말고 OpenAI 에이전트 인증 순서를 auth.order.openai 아래에 두십시오. 레거시 Codex 인증 프로필 ID와 레거시 Codex 인증 순서 항목은 openclaw doctor --fix로 복구됩니다.

공급자/모델 런타임 정책이 설정되지 않았거나 auto인 경우 openai/* 접두사만으로는 이 하네스가 선택되지 않습니다. 작성된 요청 재정의가 없는 정확한 공식 HTTPS Platform Responses 또는 ChatGPT Responses 경로에서만 OpenAI가 Codex를 암시적으로 선택할 수 있습니다. OpenAI 암시적 에이전트 런타임을 참조하십시오. Platform과 ChatGPT 중 어느 쪽으로 라우팅되는지 확인되기 전에 Codex가 인증을 소유하는 경우에도 OpenClaw는 모든 후보 경로가 Codex 호환성을 선언하도록 요구합니다. 네이티브 인증 소유권만으로는 이 경로 검사를 우회할 수 없습니다.

OpenClaw 샌드박스가 활성화되지 않은 경우 OpenClaw는 Codex 네이티브 코드 모드를 활성화하여 Codex app-server 스레드를 시작하며(code-mode-only는 기본적으로 꺼져 있음), 네이티브 작업 공간/코드 기능을 app-server item/tool/call 브리지를 통해 라우팅되는 OpenClaw 동적 도구와 함께 계속 사용할 수 있습니다. 활성 OpenClaw 샌드박스 또는 제한된 도구 정책은 실험적 샌드박스 exec-server 경로를 사용하도록 명시적으로 설정하지 않는 한 네이티브 코드 모드를 완전히 비활성화합니다.

기본값인 tools.exec.host: "auto"를 사용하고 활성 OpenClaw 샌드박스가 없는 경우 Codex는 페어링된 Node에서 명령을 실행하기 위한 node_exec 및 node_process 도구도 받습니다. 네이티브 셸은 Codex app-server 호스트와 작업 공간 (기본 stdio 배포에서는 Gateway 로컬)에 유지되며, node_exec은 이름 또는 ID로 Node를 선택하고 OpenClaw의 Node 승인 정책을 계속 적용합니다.

이 Codex 네이티브 기능은 일반 OpenClaw 실행을 위한 옵트인 QuickJS-WASI 런타임이며 다른 exec 입력 형식을 사용하는 OpenClaw 코드 모드와 별개입니다. 더 광범위한 모델/제공자/런타임 구분은 에이전트 런타임에서 시작하십시오. openai/gpt-5.6-sol은 모델 참조이고, codex는 런타임이며, Telegram, Discord, Slack 또는 다른 채널은 통신 표면입니다.

요구 사항

• 공식 @openclaw/codex Plugin이 설치되어 있어야 합니다. 구성에서 허용 목록을 사용하는 경우 plugins.allow에 codex를 포함하십시오.
• Codex 앱 서버 0.143.0 이상이 필요합니다. Plugin은 기본적으로 호환되는 바이너리를 관리하므로 PATH의 codex 명령은 정상적인 시작에 영향을 주지 않습니다.
• openclaw models auth login --provider openai를 통한 Codex 인증, 에이전트의 Codex 홈에 이미 존재하는 앱 서버 계정 또는 명시적인 Codex API 키 인증 프로필이 필요합니다.

인증 우선순위, 환경 격리, 사용자 지정 앱 서버 명령, 모델 검색 및 전체 구성 필드 목록은 Codex 하네스 참조를 참조하십시오.

빠른 시작

공식 Plugin을 설치한 다음 Codex OAuth로 로그인하십시오.

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

codex Plugin을 활성화하고 OpenAI 에이전트 모델을 선택하십시오.

{  plugins: {    entries: {      codex: {        enabled: true,      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },}

구성에서 plugins.allow를 사용하는 경우 여기에 codex도 추가하십시오.

{  plugins: {    allow: ["codex"],    entries: {      codex: {        enabled: true,      },    },  },}

Plugin 구성을 변경한 후 Gateway를 다시 시작하십시오. 채팅에 이미 세션이 있는 경우 먼저 /new 또는 /reset을 실행하여 다음 턴에서 현재 구성에 따라 하네스를 결정하도록 하십시오.

Codex Desktop 및 CLI와 스레드 공유

기본값인 appServer.homeScope: "agent"는 각 OpenClaw 에이전트를 운영자의 네이티브 Codex 상태와 격리합니다. 소유자가 Codex Desktop과 Codex CLI에 표시되는 동일한 네이티브 스레드를 검사하고 관리할 수 있도록 하려면 사용자 Codex 홈을 사용하도록 설정하십시오.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            homeScope: "user",          },        },      },    },  },}

사용자 홈 모드는 로컬 관리형 stdio 프로세스 또는 공유 Unix 소켓 전송을 지원합니다. $CODEX_HOME이 설정되어 있으면 이를 사용하고, 그렇지 않으면 ~/.codex를 사용하며, 해당 홈의 네이티브 Codex 인증, 구성, plugins 및 스레드 저장소가 포함됩니다. OpenClaw는 이 앱 서버에 OpenClaw 인증 프로필을 삽입하지 않습니다.

소유자 턴에는 codex_threads 도구가 제공됩니다. 네이티브 스레드를 나열, 검색, 읽기, 포크, 이름 변경, 보관 및 복원할 수 있습니다. OpenClaw에서 계속하려면 스레드를 포크하십시오. 포크는 현재 OpenClaw 세션에 연결되며 다른 네이티브 Codex 클라이언트에도 계속 표시됩니다. 보관하려면 해당 스레드가 다른 곳에서 닫혔음을 명시적으로 확인해야 합니다. 감독도 활성화된 경우 대화 기록 필드와 변경 작업에는 각각 supervision.allowRawTranscripts 또는 supervision.allowWriteControls 옵트인이 필요합니다.

독립적인 관리형 stdio 앱 서버를 통해 동일한 스레드를 동시에 재개하거나 쓰지 마십시오. Codex는 하나의 앱 서버 내부에서 활성 작성자를 조정하지만, 별도 프로세스 간에는 조정하지 않습니다. 일반적인 사용자 홈 stdio 세션에서는 포크가 안전하게 공존하는 방법입니다.

appServer.homeScope: "user"만으로는 플릿 카탈로그가 활성화되지 않습니다. 네이티브 세션을 OpenClaw 사이드바에 표시하려면 supervision.enabled: true를 사용하십시오. 감독은 별도의 감독 연결을 사용합니다. 명시적인 appServer 연결 설정이 없으면 해당 연결은 기본적으로 관리형 사용자 홈 stdio를 사용하지만, 일반 하네스는 에이전트 범위로 유지됩니다. 명시적인 appServer 설정은 두 경로 모두에 적용됩니다. 일반 하네스도 네이티브 상태를 공유해야 하는 경우 위와 같이 homeScope: "user"를 명시적으로 설정하십시오.

Codex 세션 감독

동일한 codex plugin은 Gateway 컴퓨터와 옵트인된 페어링 Node에서 보관되지 않은 Codex 세션을 나열할 수 있습니다. 저장되었거나 유휴 상태인 Gateway 로컬 세션은 범위가 제한된 영구 사용자 및 어시스턴트 기록을 미러링하는 모델 고정 Chat을 생성할 수 있습니다. 비공개 바인딩은 네이티브 스냅샷, 정식 브랜치 및 후속 턴에 감독 연결을 사용하는 반면, 일반 Codex 세션은 에이전트 범위로 유지됩니다. 첫 정식 시작에서는 Codex가 스냅샷 포크에 대해 반환한 모델과 제공자를 정확히 사용합니다. 이후 재개 시 선택은 Codex의 네이티브 구성에 맡겨지며, 외부 OpenClaw 모델과 폴백 체인은 이를 대체하지 않습니다. 저장 및 유휴 행은 다른 실행기가 없다는 명시적 확인 후 보관할 수 있습니다. 활성 소스에서는 브랜치를 생성하거나 보관할 수 없지만, 기존의 감독 대상 Chat은 계속 열 수 있습니다. 페어링 Node 세션은 메타데이터 전용으로 유지됩니다.

설정, 브랜치 규칙, 페어링 Node 제한, 메타데이터 노출 및 문제 해결에 대해서는 Codex 세션 감독을 참조하십시오.

구성

구독 우선/API 키 백업 순서에는 auth.order.openai를 권장합니다. 기존 레거시 Codex 인증 프로필 ID와 레거시 Codex 인증 순서는 doctor 전용 레거시 상태입니다. 새로운 레거시 Codex GPT 참조를 작성하지 마십시오.

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

Codex 호환 유효 경로에서는 위의 두 프로필 모두 동일한 Codex 실행의 후보로 유지됩니다. 프로필 순서는 런타임이 아니라 자격 증명을 선택합니다. 인증 순서를 변경해도 사용자 지정, Completions, HTTP 또는 요청으로 재정의된 경로가 Codex 호환으로 바뀌지는 않습니다.

Compaction

Codex 기반 에이전트에 compaction.model 또는 compaction.provider를 설정하지 마십시오. Codex는 네이티브 앱 서버 스레드 상태를 통해 Compaction을 수행하므로, OpenClaw는 런타임에 해당 로컬 요약기 재정의를 무시하며 에이전트가 Codex를 사용할 때 openclaw doctor --fix가 이를 제거합니다.

Lossless는 Codex 턴 주변의 조립, 수집 및 유지 관리를 위한 컨텍스트 엔진으로 계속 지원되며, agents.defaults.compaction.provider가 아니라 plugins.slots.contextEngine: "lossless-claw" 및 plugins.entries.lossless-claw.config.summaryModel을 통해 구성합니다. Codex가 활성 런타임인 경우 openclaw doctor --fix는 이전 compaction.provider: "lossless-claw" 형식을 Lossless 컨텍스트 엔진 슬롯으로 마이그레이션하지만, Compaction은 여전히 네이티브 Codex가 담당합니다. 네이티브 앱 서버 하네스는 프롬프트 전 조립이 필요한 컨텍스트 엔진을 지원하지만, codex-cli를 포함한 일반 CLI 백엔드는 해당 호스트 기능을 제공하지 않습니다.

Codex 기반 에이전트에서 /compact는 바인딩된 스레드에 대해 네이티브 Codex 앱 서버 Compaction을 시작합니다. OpenClaw는 완료를 기다리거나, OpenClaw 시간 제한을 적용하거나, 공유 앱 서버를 다시 시작하거나, 컨텍스트 엔진 또는 공개 OpenAI 요약기로 폴백하지 않습니다. 네이티브 Codex 스레드 바인딩이 없거나 오래된 경우 명령은 Compaction 백엔드를 자동으로 전환하지 않고 실패로 종료됩니다.

이 페이지의 나머지 부분에서는 배포 형태, 실패 시 종료 라우팅, 가디언 승인 정책, 네이티브 Codex plugins 및 Computer Use를 다룹니다. 전체 옵션 목록, 기본값, 열거형, 검색, 환경 격리, 시간 제한 및 앱 서버 전송 필드는 Codex 하네스 참조를 참조하십시오.

Codex 런타임 확인

Codex가 예상되는 Chat에서 /status를 사용하십시오. Codex 기반 OpenAI 에이전트 턴에는 다음이 표시됩니다.

런타임: OpenAI Codex

그런 다음 Codex 앱 서버 상태를 확인하십시오:

/codex status/codex models

/codex status는 app-server 연결, 계정, 사용량 제한, MCP 서버 및 Skills를 보고합니다. /codex models는 하네스와 계정에 대한 실시간 Codex app-server 카탈로그를 나열합니다. /status가 예상과 다르다면 문제 해결을 참조하십시오.

라우팅 및 모델 선택

제공자 참조와 런타임 정책을 분리하여 관리하십시오.

• 표준 OpenAI 모델을 선택하려면 openai/gpt-*를 사용하십시오. 접두사만으로는 Codex가 선택되지 않습니다.
• 런타임이 설정되지 않았거나 auto인 경우, 작성된 요청 재정의가 없는 정확한 공식 HTTPS Platform Responses 또는 ChatGPT Responses 경로만 Codex를 암시적으로 선택할 수 있습니다.
• 구성에서 레거시 Codex GPT 참조를 사용하지 마십시오. openclaw doctor --fix를 실행하여 레거시 참조와 오래된 세션 경로 고정을 복구하십시오.
• agentRuntime.id: "codex"는 호환되는 경로에서 Codex를 폴백 없이 반드시 사용하도록 합니다. 호환되지 않는 유효 경로를 호환 가능하게 만들지는 않습니다.
• agentRuntime.id: "openclaw"는 의도적인 경우 제공자 또는 모델이 내장 OpenClaw 런타임을 사용하도록 지정합니다.
• /codex ...는 채팅에서 네이티브 Codex app-server 대화를 제어합니다.
• ACP/acpx는 별도의 외부 하네스 경로입니다. 사용자가 ACP/acpx 또는 외부 하네스 어댑터를 요청한 경우에만 사용하십시오.

agents.defaults.imageModel에도 동일한 접두사 구분이 적용됩니다. 일반 OpenAI 경로에는 openai/gpt-*를 사용하고, 이미지 이해를 제한된 Codex app-server 턴을 통해 실행해야 하는 경우에만 codex/gpt-*를 사용하십시오. Doctor는 레거시 Codex GPT 참조를 openai/gpt-*로 재작성합니다.

배포 패턴

기본 Codex 배포

유효한 공식 HTTPS 경로에서 Codex를 암시적으로 선택할 수 있는 OpenAI 모델에 빠른 시작 구성을 사용하십시오.

{  plugins: {    entries: {      codex: {        enabled: true,      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },}

혼합 제공자 배포

Claude를 기본 에이전트로 유지하고 이름이 지정된 Codex 에이전트를 추가하십시오.

{  plugins: {    entries: {      codex: {        enabled: true,      },    },  },  agents: {    defaults: {      model: "anthropic/claude-opus-4-6",    },    list: [      {        id: "main",        default: true,        model: "anthropic/claude-opus-4-6",      },      {        id: "codex",        name: "Codex",        model: "openai/gpt-5.6-sol",      },    ],  },}

main 에이전트는 일반 제공자 경로를 사용합니다. codex 에이전트는 유효한 OpenAI 경로가 계속 호환되는 경우 Codex app-server를 사용합니다. 이를 폴백 없이 반드시 사용해야 하는 경우 모델 범위에 명시적 agentRuntime.id: "codex"를 추가하십시오.

폴백 없이 실패하는 Codex 배포

번들 Plugin을 사용할 수 있으면 정확한 공식 HTTPS OpenAI 경로에서 Codex를 선택할 수 있습니다. 명시적인 폴백 없는 실패 규칙을 설정하려면 런타임 정책을 추가하십시오.

{  models: {    providers: {      openai: {        agentRuntime: {          id: "codex",        },      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },  plugins: {    entries: {      codex: {        enabled: true,      },    },  },}

Codex 사용이 강제된 경우, 유효한 경로가 Codex 호환으로 선언되지 않았거나, Plugin이 비활성화되었거나, app-server가 너무 오래되었거나, app-server를 시작할 수 없으면 OpenClaw가 조기에 실패합니다.

App-server 정책

기본적으로 Plugin은 stdio 전송을 사용하여 OpenClaw에서 관리하는 Codex 바이너리를 로컬로 시작합니다. 다른 실행 파일을 의도적으로 실행하는 경우에만 appServer.command를 설정하십시오. app-server가 이미 다른 위치에서 실행 중인 경우에만 WebSocket 전송을 사용하십시오.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",          },        },      },    },  },}

로컬 stdio app-server 세션은 신뢰할 수 있는 로컬 운영자 태세를 기본값으로 사용합니다: approvalPolicy: "never", approvalsReviewer: "user" 및 sandbox: "danger-full-access". 로컬 Codex 요구 사항이 이러한 암시적 YOLO 태세를 허용하지 않으면 OpenClaw가 대신 허용된 보호자 권한을 선택합니다. 세션에 OpenClaw 샌드박스가 활성화되면, OpenClaw는 Codex 호스트 측 샌드박스에 의존하는 대신 해당 턴에서 Codex 네이티브 코드 모드, 사용자 MCP 서버 및 앱 기반 Plugin 실행을 비활성화합니다. 일반 exec/process 도구를 사용할 수 있는 경우 셸 접근은 대신 sandbox_exec 및 sandbox_process와 같은 OpenClaw 샌드박스 기반 동적 도구를 통해 이루어집니다.

샌드박스 탈출이나 추가 권한보다 먼저 Codex 네이티브 자동 검토를 사용하려면 정규화된 OpenClaw exec 모드를 사용하십시오.

{  tools: {    exec: {      mode: "auto",    },  },  plugins: {    entries: {      codex: {        enabled: true,      },    },  },}

Codex app-server 세션에서 tools.exec.mode: "auto"는 Codex Guardian이 검토하는 승인으로 매핑됩니다. 로컬 요구 사항이 해당 값을 허용하는 경우 일반적으로 approvalPolicy: "on-request", approvalsReviewer: "auto_review" 및 sandbox: "workspace-write"가 사용됩니다. tools.exec.mode: "auto"에서 OpenClaw는 레거시의 안전하지 않은 Codex approvalPolicy: "never" 또는 sandbox: "danger-full-access" 재정의를 유지하지 않습니다. 승인이 필요 없는 Codex 태세를 의도적으로 사용하려면 tools.exec.mode: "full"을 사용하십시오. 레거시 plugins.entries.codex.config.appServer.mode: "guardian" 프리셋도 계속 작동하지만, tools.exec.mode: "auto"가 정규화된 OpenClaw 표면입니다.

호스트 exec 승인 및 ACPX 권한과 모드 수준에서 비교하려면 권한 모드를 참조하십시오. 모든 app-server 필드, 인증 순서, 환경 격리 및 시간 제한 동작은 Codex 하네스 참조를 참조하십시오.

명령 및 진단

codex Plugin은 OpenClaw 텍스트 명령을 지원하는 모든 채널에서 /codex를 슬래시 명령으로 등록합니다.

네이티브 실행 및 제어에는 소유자 또는 operator.admin Gateway 클라이언트가 필요합니다. 여기에는 스레드 연결 또는 재개, 턴 전송 또는 중지, 모델·고속 모드· 권한 상태 변경, 압축 또는 검토, 연결 해제가 포함됩니다. 권한이 있는 다른 발신자는 상태, 도움말, 계정, 모델, 스레드, MCP 서버, Skill 및 연결을 검사하는 읽기 전용 명령만 사용할 수 있습니다.

일반적인 형식:

• /codex status는 app-server 연결, 모델, 계정, 사용량 제한, MCP 서버 및 Skills를 확인합니다.
• /codex models는 실시간 Codex app-server 모델을 나열합니다.
• /codex threads [filter]는 최근 Codex app-server 스레드를 나열합니다.
• /codex resume <thread-id>는 현재 OpenClaw 세션을 기존 Codex 스레드에 연결합니다.
• /codex bind [thread-id] [--cwd <path>] [--model <model>] [--provider <provider>] 는 현재 채팅을 연결합니다.
• /codex detach(또는 /codex unbind)는 현재 연결을 해제합니다.
• /codex binding은 현재 연결을 설명합니다.
• /codex stop은 활성 턴을 중지하고, /codex steer <text>는 활성 턴을 조정합니다.
• /codex model <model>, /codex fast [on|off|status] 및 /codex permissions [default|yolo|status]는 대화별 상태를 변경합니다.
• /codex compact는 Codex app-server에 연결된 스레드를 압축하도록 요청합니다.
• /codex review는 연결된 스레드에 대해 Codex 네이티브 검토를 시작합니다.
• /codex diagnostics [note]는 연결된 스레드에 대한 Codex 피드백을 전송하기 전에 확인을 요청합니다.
• /codex account는 계정 및 사용량 제한 상태를 표시합니다.
• /codex mcp는 Codex app-server MCP 서버 상태를 나열합니다.
• /codex skills는 Codex app-server Skills를 나열합니다.
• /codex plugins list, /codex plugins enable <name> 및 /codex plugins disable <name>은 구성된 네이티브 Codex Plugin을 관리합니다.
• /codex computer-use [status|install]은 Codex Computer Use를 관리합니다.
• /codex help는 전체 명령 트리를 나열합니다.

대부분의 지원 보고에서는 버그가 발생한 대화에서 /diagnostics [note]로 시작하십시오. 이 명령은 하나의 Gateway 진단 보고서를 생성하고, Codex 하네스 세션의 경우 관련 Codex 피드백 번들을 전송할 수 있도록 승인을 요청합니다. 개인정보 보호 모델과 그룹 채팅 동작은 진단 내보내기를 참조하십시오. 전체 Gateway 진단 번들 없이 현재 연결된 스레드의 Codex 피드백 업로드만 특별히 원하는 경우에만 /codex diagnostics [note]를 사용하십시오.

로컬에서 Codex 스레드 검사

문제가 있는 Codex 실행을 검사하는 가장 빠른 방법은 네이티브 Codex 스레드를 직접 여는 것입니다.

codex resume <thread-id>

완료된 /diagnostics 응답, /codex binding 또는 /codex threads [filter]에서 스레드 ID를 확인하십시오.

업로드 방식과 런타임 수준의 진단 경계는 Codex 하네스 런타임을 참조하십시오.

인증 순서

기본 에이전트별 홈에서 인증은 다음 순서로 선택됩니다.

1. 에이전트에 대해 순서가 지정된 OpenAI 인증 프로필이며, 가급적 auth.order.openai 아래에 둡니다. 이전 레거시 Codex 인증 프로필 ID와 레거시 Codex 인증 순서를 마이그레이션하려면 openclaw doctor --fix를 실행하십시오.
2. 해당 에이전트의 Codex 홈에 있는 앱 서버의 기존 계정입니다.
3. 로컬 stdio 앱 서버 실행에만 해당하며, 앱 서버 계정이 없고 OpenAI 인증이 여전히 필요할 때 CODEX_API_KEY, 그다음 OPENAI_API_KEY 순서입니다.

OpenClaw가 ChatGPT 구독 방식의 Codex 인증 프로필을 감지하면, 생성된 Codex 자식 프로세스에서 CODEX_API_KEY와 OPENAI_API_KEY를 제거합니다. 이를 통해 Gateway 수준 API 키는 임베딩이나 직접 OpenAI 모델에 계속 사용할 수 있으면서, 네이티브 Codex 앱 서버 턴이 실수로 API를 통해 과금되는 것을 방지합니다. 명시적 Codex API 키 프로필과 로컬 stdio 환경 키 폴백은 상속된 자식 프로세스 환경 대신 앱 서버 로그인을 사용합니다. WebSocket 앱 서버 연결에는 Gateway 환경 API 키 폴백이 제공되지 않습니다. 명시적 인증 프로필이나 원격 앱 서버의 자체 계정을 사용하십시오.

구독 프로필이 Codex 사용량 한도에 도달하면 OpenClaw는 Codex가 재설정 시간을 보고한 경우 이를 기록하고, 동일한 Codex 실행에 대해 순서상 다음 인증 프로필을 시도합니다. 재설정 시간이 지나면 선택된 openai/gpt-* 모델이나 Codex 런타임을 변경하지 않아도 해당 구독 프로필을 다시 사용할 수 있습니다.

네이티브 Codex Plugin이 구성되어 있으면 OpenClaw는 Plugin이 소유한 앱을 Codex 스레드에 노출하기 전에 연결된 앱 서버를 통해 해당 Plugin을 설치하거나 새로 고칩니다. 앱 ID, 접근 가능 여부 및 메타데이터의 기준 정보는 계속 app/list이지만, 스레드별 활성화 결정은 OpenClaw가 소유합니다. 정책에서 목록에 있고 접근 가능한 앱을 허용하면, 현재 app/list에서 해당 앱이 비활성화된 것으로 보고하더라도 OpenClaw는 thread/start.config.apps[appId].enabled = true를 전송합니다. 이 경로는 알 수 없는 ID의 앱이 설치되어 있다고 가정하지 않습니다. OpenClaw는 plugin/install을 사용하여 마켓플레이스 Plugin만 활성화한 다음 인벤토리를 새로 고칩니다.

환경 격리

로컬 stdio 앱 서버 실행의 경우 OpenClaw는 CODEX_HOME을 에이전트별 디렉터리로 설정하여, Codex 구성, 인증/계정 파일, Plugin 캐시/데이터 및 네이티브 스레드 상태가 기본적으로 운영자의 개인 ~/.codex를 읽거나 쓰지 않도록 합니다. OpenClaw는 일반 프로세스 HOME을 유지합니다. Codex 실행 하위 프로세스는 계속 사용자 홈의 구성과 토큰을 찾을 수 있으며, Codex는 공유 $HOME/.agents/skills 및 $HOME/.agents/plugins/marketplace.json 항목을 검색할 수 있습니다. appServer.homeScope: "user"를 사용하면 OpenClaw는 OpenClaw 인증 프로필을 주입하지 않고 대신 네이티브 사용자 Codex 홈과 그 기존 계정을 사용합니다.

배포에 추가 환경 격리가 필요한 경우 해당 변수를 appServer.clearEnv에 추가하십시오.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],          },        },      },    },  },}

appServer.clearEnv는 생성된 Codex 앱 서버 자식 프로세스에만 영향을 줍니다. OpenClaw는 로컬 실행 정규화 중 이 목록에서 CODEX_HOME과 HOME을 제거합니다. CODEX_HOME은 선택된 에이전트 또는 사용자 범위를 계속 가리키며, HOME은 하위 프로세스가 일반 사용자 홈 상태를 사용할 수 있도록 계속 상속됩니다.

동적 도구와 웹 검색

Codex 동적 도구는 기본적으로 searchable 로딩을 사용합니다. OpenClaw는 Codex 네이티브 작업 공간 작업과 중복되는 동적 도구인 read, write, edit, apply_patch, exec, process, update_plan, tool_call, tool_describe, tool_search, tool_search_code를 노출하지 않습니다. 메시징, 미디어, cron, 브라우저, 노드, Gateway, heartbeat_respond 등 나머지 대부분의 OpenClaw 통합 도구는 Codex 도구 검색을 통해 openclaw 네임스페이스에서 사용할 수 있으므로 초기 모델 컨텍스트가 더 작게 유지됩니다.

OpenClaw computer 도구를 포함하여 catalogMode: "direct-only"로 표시된 도구는 대신 openclaw_direct 네임스페이스를 사용합니다. Codex는 이 네임스페이스를 DirectModelOnly로 취급하므로, 이러한 도구는 중첩된 Code Mode tools.* 호출을 거치지 않고 일반 스레드와 코드 모드 전용 스레드에서 모델에 직접 표시됩니다.

검색이 활성화되어 있고 관리형 공급자가 선택되지 않은 경우 웹 검색은 기본적으로 Codex의 호스팅 web_search 도구를 사용합니다. 관리형 검색이 네이티브 도메인 제한을 우회하지 못하도록 네이티브 호스팅 검색과 OpenClaw의 관리형 web_search 동적 도구는 상호 배타적으로 작동합니다. 호스팅 검색을 사용할 수 없거나 명시적으로 비활성화했거나 선택한 관리형 공급자로 대체한 경우 OpenClaw는 관리형 도구를 사용합니다. 프로덕션 앱 서버 트래픽은 사용자 정의 web 네임스페이스를 거부하므로 OpenClaw는 Codex의 독립형 web.run 확장을 비활성화된 상태로 유지합니다. tools.web.search.enabled: false는 두 경로를 모두 비활성화하며, 도구가 비활성화된 LLM 전용 실행도 마찬가지입니다. Codex는 "cached"를 선호 설정으로 취급하고 제한 없는 앱 서버 턴에서는 이를 실시간 외부 접근으로 해석합니다. 네이티브 allowedDomains가 설정된 경우 허용 목록을 우회할 수 없도록 자동 관리형 폴백은 실패 시 닫힙니다. 지속적인 유효 검색 정책 변경이 발생하면 다음 턴 전에 연결된 Codex 스레드를 교체합니다. 일시적인 턴별 제한은 임시 제한 스레드를 사용하고 나중에 재개할 수 있도록 기존 연결을 유지합니다.

sessions_yield와 메시지 도구 전용 소스 응답은 턴 제어 계약이므로 직접 실행 상태를 유지합니다. Codex의 네이티브 spawn_agent가 기본 Codex 하위 에이전트 표면으로 유지되도록 sessions_spawn은 검색 가능 상태를 유지하며, 명시적인 OpenClaw 또는 ACP 위임도 openclaw 동적 도구 네임스페이스를 통해 계속 사용할 수 있습니다. Heartbeat 협업 지침은 도구가 아직 로드되지 않은 경우 Heartbeat 턴을 종료하기 전에 heartbeat_respond를 검색하도록 Codex에 지시합니다.

지연된 동적 도구를 검색할 수 없는 사용자 정의 Codex 앱 서버에 연결하거나 전체 도구 페이로드를 디버깅하는 경우에만 codexDynamicToolsLoading: "direct"를 설정하십시오.

구성 필드

지원되는 최상위 Codex Plugin 필드는 다음과 같습니다.

지원되는 appServer 필드는 다음과 같습니다.

appServer.networkProxy는 Codex 샌드박스 계약을 변경하므로 명시적으로 설정해야 합니다. 활성화하면 OpenClaw는 Codex 스레드 구성에 features.network_proxy.enabled와 default_permissions도 설정하여 생성된 권한 프로필이 Codex 관리형 네트워킹을 시작할 수 있도록 합니다. 기본적으로 OpenClaw는 프로필 본문에서 충돌 방지 openclaw-network-<fingerprint> 프로필 이름을 생성합니다. 안정적인 로컬 이름이 필요한 경우에만 profileName을 사용하십시오.

{  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              unixSockets: {                "/tmp/proxy.sock": "allow",                "/tmp/blocked.sock": "none",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },}

일반적인 app-server 런타임이 danger-full-access를 사용하는 경우 networkProxy를 활성화하면 생성된 권한 프로필에 워크스페이스 스타일 파일 시스템 접근이 사용됩니다. Codex 관리형 네트워크 적용은 샌드박스화된 네트워킹이므로 전체 접근 프로필로는 아웃바운드 트래픽을 보호할 수 없습니다. 도메인 항목에는 allow 또는 deny를 사용하고, Unix 소켓 항목에는 Codex의 allow 또는 none 값을 사용합니다.

동적 도구 호출 시간 제한

OpenClaw 소유의 동적 도구 호출에는 appServer.requestTimeoutMs와 별도로 제한이 적용됩니다. Codex item/tool/call 요청에는 기본적으로 90초의 OpenClaw 워치독이 사용됩니다. 호출별로 양수인 timeoutMs 인수를 지정하면 해당 도구의 시간 예산이 늘어나거나 줄어들며, 상한은 600000 ms입니다. 도구 호출에 자체 시간 제한이 없으면 image_generate 도구는 agents.defaults.imageGenerationModel.timeoutMs를 사용하고, 그렇지 않으면 이미지 생성 기본값인 120초를 사용합니다. 미디어 이해 image 도구는 tools.media.image.timeoutSeconds 또는 미디어 기본값인 60초를 사용합니다. 이미지 이해의 경우 이 시간 제한은 요청 자체에 적용되며 앞선 준비 작업으로 인해 줄어들지 않습니다. 시간 제한이 발생하면 OpenClaw는 지원되는 경우 도구 신호를 중단하고 실패한 동적 도구 응답을 Codex에 반환하여, 세션이 processing 상태로 남는 대신 턴을 계속할 수 있게 합니다. 이 워치독은 동적 item/tool/call의 외부 시간 예산이며, 제공자별 요청 시간 제한은 해당 호출 내부에서 실행되고 각자의 시간 제한 의미 체계를 유지합니다.

Codex가 턴을 수락한 후와 OpenClaw가 턴 범위 app-server 요청에 응답한 후, 하네스는 Codex가 현재 턴을 진행하고 최종적으로 turn/completed를 통해 네이티브 턴을 완료할 것으로 예상합니다. app-server가 appServer.turnCompletionIdleTimeoutMs 동안 아무 활동 없이 멈추면 OpenClaw는 최선형 방식으로 Codex 턴을 중단하고 진단용 시간 제한을 기록한 다음 OpenClaw 세션 레인을 해제하여 후속 채팅 메시지가 오래된 네이티브 턴 뒤에서 대기열에 쌓이지 않도록 합니다. 동일한 턴에 대한 대부분의 비종료 알림은 Codex가 해당 턴이 아직 활성 상태임을 입증하므로 이 짧은 워치독을 해제합니다.

도구 핸드오프에는 더 긴 도구 후 유휴 시간 예산을 사용합니다. 이는 OpenClaw가 item/tool/call 응답을 반환한 후, commandExecution과 같은 네이티브 도구 항목이 완료된 후, 원시 custom_tool_call_output 완료 후, 그리고 도구 후 원시 어시스턴트 진행, 원시 추론 완료 또는 추론 진행 후에 적용됩니다. 이 가드는 설정된 경우 appServer.postToolRawAssistantCompletionIdleTimeoutMs를 사용하고, 그렇지 않으면 기본적으로 5분을 사용합니다. 또한 동일한 시간 예산으로 Codex가 현재 턴의 다음 이벤트를 내보내기 전 무응답 합성 구간의 진행 워치독도 연장합니다. 속도 제한 업데이트와 같은 전역 app-server 알림은 턴 유휴 진행 상태를 재설정하지 않습니다. 추론 완료, commentary agentMessage 완료, 도구 전 원시 추론 또는 어시스턴트 진행 뒤에는 자동 최종 응답이 이어질 수 있으므로 세션 레인을 즉시 해제하는 대신 진행 후 응답 가드를 사용합니다.

최종/비-commentary 완료 agentMessage 항목과 도구 전 원시 어시스턴트 완료만 어시스턴트 출력 해제를 설정합니다. 이후 Codex가 turn/completed 없이 아무 활동도 하지 않으면 OpenClaw는 최선형 방식으로 네이티브 턴을 중단하고 세션 레인을 해제합니다. 다른 턴 감시가 해제 경쟁에서 이긴 경우에도 활성 상태인 네이티브 요청, 항목 또는 동적 도구 완료가 더 이상 없고, 어시스턴트 출력 해제가 여전히 가장 최근에 완료된 항목에 속하며, 이후의 항목 완료가 없다면 OpenClaw는 완료된 최종 어시스턴트 항목을 계속 수락합니다. 이를 통해 턴을 재실행하지 않고도 완료된 도구 작업 후의 최종 답변을 보존할 수 있습니다. 부분 어시스턴트 델타, 오래된 이전 응답 및 비어 있는 후속 완료는 해당되지 않습니다.

어시스턴트, 도구, 활성 항목 또는 부작용의 증거 없이 발생한 턴 완료 유휴 시간 제한을 포함하여 재실행에 안전한 stdio app-server 실패는 새 app-server 시도에서 한 번 재시도됩니다. 안전하지 않은 시간 제한에서는 멈춘 app-server 클라이언트를 계속 폐기하고 OpenClaw 세션 레인을 해제하며, 자동으로 재실행하는 대신 오래된 네이티브 스레드 바인딩도 제거합니다. 완료 감시 시간 제한은 Codex 전용 시간 제한 텍스트로 표시됩니다. 재실행에 안전한 경우에는 응답이 불완전할 수 있다고 안내하고, 안전하지 않은 경우에는 다시 시도하기 전에 현재 상태를 확인하라고 사용자에게 안내합니다. 공개 시간 제한 진단에는 마지막 app-server 알림 메서드, 원시 어시스턴트 응답 항목의 ID/유형/역할, 활성 요청/항목 수, 설정된 감시 상태 등의 구조적 필드가 포함됩니다. 마지막 알림이 원시 어시스턴트 응답 항목이면 제한된 길이의 어시스턴트 텍스트 미리 보기도 포함됩니다. 원시 프롬프트나 도구 콘텐츠는 포함되지 않습니다.

로컬 테스트 환경 재정의

• appServer.command가 설정되지 않은 경우 OPENCLAW_CODEX_APP_SERVER_BIN은 관리형 바이너리를 우회합니다.
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1은 제거되었습니다. 대신 plugins.entries.codex.config.appServer.mode: "guardian"을 사용하거나, 일회성 로컬 테스트에는 OPENCLAW_CODEX_APP_SERVER_MODE=guardian을 사용하십시오. 반복 가능한 배포에는 설정을 사용하는 것이 좋습니다. 이렇게 하면 Plugin 동작이 나머지 Codex 하네스 설정과 동일한 검토 대상 파일에 유지됩니다.

네이티브 Codex Plugin

네이티브 Codex Plugin 지원은 OpenClaw 하네스 턴과 동일한 Codex 스레드에서 Codex app-server 자체의 앱 및 Plugin 기능을 사용합니다. OpenClaw는 Codex Plugin을 합성 codex_plugin_* OpenClaw 동적 도구로 변환하지 않습니다.

codexPlugins는 네이티브 Codex 하네스를 선택하는 세션에만 영향을 줍니다. 내장 하네스 실행, 일반 OpenAI 제공자 실행, ACP 대화 바인딩 또는 다른 하네스에는 영향을 주지 않습니다.

최소 마이그레이션 설정:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_destructive_actions: true,            plugins: {              "google-calendar": {                enabled: true,                marketplaceName: "openai-curated",                pluginName: "google-calendar",              },            },          },        },      },    },  },}

스레드 앱 설정은 OpenClaw가 Codex 하네스 세션을 설정하거나 오래된 Codex 스레드 바인딩을 교체할 때 계산되며, 매 턴마다 다시 계산되지 않습니다. codexPlugins를 변경한 후에는 /new, /reset을 사용하거나 gateway를 다시 시작하여 이후의 Codex 하네스 세션이 업데이트된 앱 세트로 시작되도록 하십시오.

마이그레이션 자격, 앱 인벤토리, 파괴적 작업 정책, 추가 정보 요청 및 네이티브 Plugin 진단에 대해서는 네이티브 Codex Plugin을 참조하십시오.

OpenAI 측 앱 및 Plugin 접근은 로그인한 Codex 계정에 의해 제어되며, Business 및 Enterprise/Edu 워크스페이스의 경우 워크스페이스 앱 제어의 영향도 받습니다. OpenAI의 계정 및 워크스페이스 제어 개요는 ChatGPT 플랜으로 Codex 사용하기를 참조하십시오.

Computer Use

Computer Use에는 별도의 설정 가이드가 있습니다. Codex Computer Use.

요약하면 OpenClaw는 데스크톱 제어 앱을 번들로 제공하거나 데스크톱 작업을 직접 실행하지 않습니다. OpenClaw는 Codex app-server를 준비하고 computer-use MCP 서버가 사용 가능한지 확인한 다음, Codex 모드 턴 중 네이티브 MCP 도구 호출을 Codex가 담당하도록 합니다.

런타임 경계

Codex 하네스는 저수준 임베디드 에이전트 실행기만 변경합니다.

• OpenClaw 동적 도구가 지원됩니다. Codex가 OpenClaw에 해당 도구 실행을 요청하므로 OpenClaw는 실행 경로에 계속 남습니다.
• Codex 네이티브 셸, 패치, MCP 및 네이티브 앱 도구는 Codex가 소유합니다. OpenClaw는 지원되는 릴레이를 통해 선택된 네이티브 이벤트를 관찰하거나 차단할 수 있지만 네이티브 도구 인수는 다시 작성하지 않습니다.
• Codex는 네이티브 Compaction을 소유합니다. OpenClaw는 채널 기록, 검색, /new, /reset 및 향후 모델 또는 하네스 전환을 위해 트랜스크립트 미러를 유지하지만, Codex Compaction을 OpenClaw 또는 컨텍스트 엔진 요약기로 대체하지 않습니다.
• 미디어 생성, 미디어 이해, TTS, 승인 및 메시징 도구 출력은 계속해서 일치하는 OpenClaw 제공자/모델 설정을 통과합니다.
• tool_result_persist는 OpenClaw 소유의 트랜스크립트 도구 결과에 적용되며, Codex 네이티브 도구 결과 레코드에는 적용되지 않습니다.

훅 계층, 지원되는 V1 표면, 네이티브 권한 처리, 대기열 조정, Codex 피드백 업로드 메커니즘 및 Compaction 세부 정보는 Codex 하네스 런타임을 참조하십시오.

문제 해결

Codex가 일반 /model 제공자로 표시되지 않음: 새 설정에서는 예상되는 동작입니다. openai/gpt-* 모델을 선택하고 plugins.entries.codex.enabled를 활성화한 다음, plugins.allow에서 codex를 제외하는지 확인하십시오.

OpenClaw가 Codex 대신 내장 하네스를 사용함: 유효 경로가 공식 HTTPS Platform Responses 또는 ChatGPT Responses 경로와 정확히 일치하고, 작성된 요청 재정의가 없으며, Codex Plugin이 설치되고 활성화되어 있는지 확인하십시오. openai/gpt-* 접두사만으로는 충분하지 않습니다. 테스트 중 엄격하게 증명하려면 제공자 또는 모델의 agentRuntime.id: "codex"를 설정하십시오. Codex를 강제하면 경로나 하네스가 호환되지 않을 때 폴백하는 대신 실패합니다.

OpenAI Codex 런타임이 API 키 경로로 폴백함: 모델, 런타임, 선택된 제공자 및 실패를 보여 주는 수정된 gateway 발췌문을 수집하십시오. 영향을 받는 협업자에게 OpenClaw 호스트에서 다음 읽기 전용 명령을 실행하도록 요청하십시오.

(  pattern='openai/gpt-5\.[45]|openai[-]codex|agentRuntime(\.id)?|harnessRuntime|Runtime: OpenAI Codex|legacy OpenAI Codex prefix|resolveSelectedOpenAIRuntimeProvider|candidateProvider[": ]+openai|status[": ]+401|Incorrect API key|No API key|api-key path|API-key path|OAuth'   if ls /tmp/openclaw/openclaw-*.log >/dev/null 2>&1; then    grep -E -i -n "$pattern" /tmp/openclaw/openclaw-*.log 2>/dev/null || true  else    journalctl --user -u openclaw-gateway --since today --no-pager 2>/dev/null \      | grep -E -i "$pattern" || true  fi) | sed -E \    -e 's/(Authorization: Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \    -e 's/(Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \    -e 's/(api[_ -]?key[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \    -e 's/(OPENAI_API_KEY[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \    -e 's/sk-[A-Za-z0-9_-]{12,}/sk-[REDACTED]/g' \    -e 's/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/[EMAIL-REDACTED]/g' \  | tail -200

유용한 발췌문에는 일반적으로 openai/gpt-5.6-sol 또는 openai/gpt-5.6-luna, Runtime: OpenAI Codex, agentRuntime.id 또는 harnessRuntime, candidateProvider: "openai", 그리고 401, Incorrect API key 또는 No API key 결과가 포함됩니다. 수정된 실행에서는 일반 OpenAI API 키 실패 대신 OpenAI OAuth 경로가 표시되어야 합니다.

레거시 Codex 모델 참조 설정이 남아 있음: openclaw doctor --fix를 실행하십시오. Doctor는 레거시 모델 참조를 openai/*로 다시 작성하고, 오래된 세션 및 전체 에이전트 런타임 고정을 제거하며, 기존 인증 프로필 재정의를 보존합니다.

app-server가 거부됨: Codex app-server 0.143.0 이상을 사용하십시오. 0.143.0-alpha.2 또는 0.143.0+custom과 같이 동일 버전의 프리릴리스나 빌드 접미사가 붙은 버전은 OpenClaw가 안정 버전 0.143.0 프로토콜 하한을 검사하므로 거부됩니다.

/codex status가 연결할 수 없음: codex Plugin이 활성화되어 있고, 허용 목록을 설정한 경우 plugins.allow에 해당 Plugin이 포함되어 있으며, 사용자 지정 appServer.command, url, authToken 또는 헤더가 유효한지 확인하십시오.

모델 검색이 느림: plugins.entries.codex.config.discovery.timeoutMs를 낮추거나 검색을 비활성화하십시오. Codex 하네스 참조를 참조하십시오.

WebSocket 전송이 즉시 실패함: appServer.url, authToken, 헤더를 확인하고 원격 app-server가 동일한 Codex app-server 프로토콜 버전을 사용하는지 확인하십시오.

네이티브 셸 또는 패치 도구가 Native hook relay unavailable 오류와 함께 차단됨: Codex 스레드가 OpenClaw에 더 이상 등록되어 있지 않은 네이티브 훅 릴레이 id를 계속 사용하려고 합니다. 이는 ACP 백엔드, 프로바이더, GitHub 또는 셸 명령 실패가 아니라 네이티브 Codex 훅 전송 문제입니다. 영향을 받는 채팅에서 /new 또는 /reset으로 새 세션을 시작한 후 무해한 명령을 다시 시도하십시오. 한 번은 작동하지만 다음 네이티브 도구 호출이 다시 실패한다면 /new는 임시 해결 방법으로만 사용하십시오. Codex 앱 서버 또는 OpenClaw Gateway를 다시 시작한 후 프롬프트를 새 세션에 복사하여 이전 스레드를 제거하고 네이티브 훅 등록을 다시 생성하십시오.

Codex 이외의 모델이 기본 제공 하니스를 사용함: 프로바이더 또는 모델 런타임 정책에서 다른 하니스로 라우팅하지 않는 한 예상되는 동작입니다. 일반적인 OpenAI 이외의 프로바이더 참조는 auto 모드에서 해당 프로바이더의 정상 경로를 계속 사용합니다.

Computer Use가 설치되어 있지만 도구가 실행되지 않음: 새 세션에서 /codex computer-use status를 확인하십시오. 도구가 Native hook relay unavailable을 보고하면 위의 네이티브 훅 릴레이 복구 절차를 따르십시오. Codex Computer Use를 참조하십시오.

관련 문서

• Codex 하니스 참조
• Codex 하니스 런타임
• Codex 감독
• 네이티브 Codex Plugin
• Codex Computer Use
• 에이전트 런타임
• 모델 프로바이더
• OpenAI 프로바이더
• OpenAI Codex 도움말
• 에이전트 하니스 Plugin
• Plugin 훅
• 진단 내보내기
• 상태
• 테스트