--- read_when: - 공식 Codex app-server 하네스를 사용하려고 합니다 - Codex 하네스 구성 예제가 필요합니다 - Codex 전용 배포가 OpenClaw로 대체되지 않고 실패하도록 하려는 경우 summary: 공식 Codex app-server 하네스를 통해 OpenClaw 임베디드 에이전트 턴 실행하기 title: Codex 하네스 x-i18n: generated_at: "2026-07-12T15:29:20Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 15 provider: openai source_hash: 5f6705dad9fa3bbe45c2f4eaf079ecb861b7911142bda1301c4d64a1f21a8ec5 source_path: plugins/codex-harness.md workflow: 16 --- 공식 `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 암시적 에이전트 런타임](/ko/providers/openai#implicit-agent-runtime)을 참조하십시오. 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 코드 모드](/ko/reference/code-mode)와 별개입니다. 더 광범위한 모델/제공자/런타임 구분은 [에이전트 런타임](/ko/concepts/agent-runtimes)에서 시작하십시오. `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 하네스 참조](/ko/plugins/codex-harness-reference)를 참조하십시오. ## 빠른 시작 공식 Plugin을 설치한 다음 Codex OAuth로 로그인하십시오. ```bash openclaw plugins install @openclaw/codex openclaw models auth login --provider openai ``` `codex` Plugin을 활성화하고 OpenAI 에이전트 모델을 선택하십시오. ```json5 { plugins: { entries: { codex: { enabled: true, }, }, }, agents: { defaults: { model: "openai/gpt-5.6-sol", }, }, } ``` 구성에서 `plugins.allow`를 사용하는 경우 여기에 `codex`도 추가하십시오. ```json5 { plugins: { allow: ["codex"], entries: { codex: { enabled: true, }, }, }, } ``` Plugin 구성을 변경한 후 Gateway를 다시 시작하십시오. 채팅에 이미 세션이 있는 경우 먼저 `/new` 또는 `/reset`을 실행하여 다음 턴에서 현재 구성에 따라 하네스를 결정하도록 하십시오. ## Codex Desktop 및 CLI와 스레드 공유 기본값인 `appServer.homeScope: "agent"`는 각 OpenClaw 에이전트를 운영자의 네이티브 Codex 상태와 격리합니다. 소유자가 Codex Desktop과 Codex CLI에 표시되는 동일한 네이티브 스레드를 검사하고 관리할 수 있도록 하려면 사용자 Codex 홈을 사용하도록 설정하십시오. ```json5 { 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 세션 감독](/plugins/codex-supervision)을 참조하십시오. ## 구성 | 요구 사항 | 설정 | 위치 | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------- | | 하네스 활성화 | `plugins.entries.codex.enabled: true` | OpenClaw 구성 | | 보관되지 않은 Codex 세션 표시 | `plugins.entries.codex.config.supervision.enabled: true` | Codex plugin 구성 | | 허용 목록에 포함된 plugin 설치 유지 | `plugins.allow`에 `codex` 포함 | OpenClaw 구성 | | 적격 OpenAI 턴에서 Codex를 암시적으로 사용하도록 허용 | 정확한 공식 HTTPS Responses/ChatGPT 경로, 작성된 요청 재정의 없음, 런타임 미설정/`auto` | OpenAI 제공자/모델 구성 | | ChatGPT/Codex OAuth로 로그인 | `openclaw models auth login --provider openai` | CLI 인증 프로필 | | Codex 실행을 위한 API 키 백업 추가 | `auth.order.openai`에서 구독 인증 뒤에 나열된 `openai:*` API 키 프로필 | CLI 인증 프로필 + OpenClaw 구성 | | Codex를 사용할 수 없을 때 실패로 종료 | 제공자 또는 모델 `agentRuntime.id: "codex"` | OpenClaw 모델/제공자 구성 | | 직접 OpenAI API 트래픽 사용 | 일반 OpenAI 인증을 사용하는 제공자 또는 모델 `agentRuntime.id: "openclaw"` | OpenClaw 모델/제공자 구성 | | 앱 서버 동작 조정 | `plugins.entries.codex.config.appServer.*` | Codex plugin 구성 | | 네이티브 Codex plugin 앱 활성화 | `plugins.entries.codex.config.codexPlugins.*` | Codex plugin 구성 | | Codex Computer Use 활성화 | `plugins.entries.codex.config.computerUse.*` | Codex plugin 구성 | 구독 우선/API 키 백업 순서에는 `auth.order.openai`를 권장합니다. 기존 레거시 Codex 인증 프로필 ID와 레거시 Codex 인증 순서는 doctor 전용 레거시 상태입니다. 새로운 레거시 Codex GPT 참조를 작성하지 마십시오. ```json5 { 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 하네스 참조](/ko/plugins/codex-harness-reference)를 참조하십시오. ## Codex 런타임 확인 Codex가 예상되는 Chat에서 `/status`를 사용하십시오. Codex 기반 OpenAI 에이전트 턴에는 다음이 표시됩니다. ```text 런타임: OpenAI Codex ``` 그런 다음 Codex 앱 서버 상태를 확인하십시오: ```text /codex status /codex models ``` `/codex status`는 app-server 연결, 계정, 사용량 제한, MCP 서버 및 Skills를 보고합니다. `/codex models`는 하네스와 계정에 대한 실시간 Codex app-server 카탈로그를 나열합니다. `/status`가 예상과 다르다면 [문제 해결](#troubleshooting)을 참조하십시오. ## 라우팅 및 모델 선택 제공자 참조와 런타임 정책을 분리하여 관리하십시오. - 표준 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 또는 외부 하네스 어댑터를 요청한 경우에만 사용하십시오. | 사용자 의도 | 사용 | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | 현재 채팅 연결 | `/codex bind [thread-id] [--cwd ] [--model ] [--provider ]` | | 기존 Codex 스레드 재개 | `/codex resume ` | | Codex 스레드 나열 또는 필터링 | `/codex threads [filter]` | | 네이티브 Codex Plugin 나열 | `/codex plugins list` | | 구성된 네이티브 Codex Plugin 활성화 또는 비활성화 | `/codex plugins enable `, `/codex plugins disable ` | | 저장된 Codex CLI 세션을 페어링된 Node 턴으로 재개 | `/codex sessions --host [filter]`, 이어서 `/codex resume --host --bind here` | | 여러 컴퓨터의 보관되지 않은 Codex 세션 보기 | Codex 감독을 활성화하고 **Codex 세션**을 여십시오 | | 연결된 스레드의 모델, 고속 모드 또는 권한 변경 | `/codex model `, `/codex fast [on\|off\|status]`, `/codex permissions [default\|yolo\|status]` | | 활성 턴 중지 또는 조정 | `/codex stop`, `/codex steer ` | | 현재 연결 해제 | `/codex detach` (별칭 `/codex unbind`) | | Codex 피드백만 전송 | `/codex diagnostics [note]` | | ACP/acpx 작업 시작 | `/codex`가 아닌 ACP/acpx 세션 명령 | | 사용 사례 | 구성 | 확인 | 참고 | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------ | | 네이티브 Codex 런타임을 사용할 수 있는 OpenAI 경로 | 작성된 요청 재정의가 없는 정확한 공식 HTTPS Responses/ChatGPT 경로와 활성화된 `codex` Plugin | `/status`에 `Runtime: OpenAI Codex` 표시 | 런타임이 설정되지 않았거나 `auto`일 때의 암시적 경로 | | Codex를 사용할 수 없으면 폴백 없이 실패 | 제공자 또는 모델의 `agentRuntime.id: "codex"` | 내장 런타임으로 폴백하지 않고 턴 실패 | Codex 전용 배포에 사용 | | OpenClaw를 통한 직접 OpenAI API 키 트래픽 | 제공자 또는 모델의 `agentRuntime.id: "openclaw"` 및 일반 OpenAI 인증 | `/status`에 OpenClaw 런타임 표시 | OpenClaw 사용이 의도된 경우에만 사용 | | 레거시 구성 | 레거시 Codex GPT 참조 | `openclaw doctor --fix`가 재작성 | 새 구성을 이 방식으로 작성하지 마십시오 | | ACP/acpx Codex 어댑터 | ACP `sessions_spawn({ runtime: "acp" })` | ACP 작업/세션 상태 | 네이티브 Codex 하네스와 별개 | `agents.defaults.imageModel`에도 동일한 접두사 구분이 적용됩니다. 일반 OpenAI 경로에는 `openai/gpt-*`를 사용하고, 이미지 이해를 제한된 Codex app-server 턴을 통해 실행해야 하는 경우에만 `codex/gpt-*`를 사용하십시오. Doctor는 레거시 Codex GPT 참조를 `openai/gpt-*`로 재작성합니다. ## 배포 패턴 ### 기본 Codex 배포 유효한 공식 HTTPS 경로에서 Codex를 암시적으로 선택할 수 있는 OpenAI 모델에 빠른 시작 구성을 사용하십시오. ```json5 { plugins: { entries: { codex: { enabled: true, }, }, }, agents: { defaults: { model: "openai/gpt-5.6-sol", }, }, } ``` ### 혼합 제공자 배포 Claude를 기본 에이전트로 유지하고 이름이 지정된 Codex 에이전트를 추가하십시오. ```json5 { 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를 선택할 수 있습니다. 명시적인 폴백 없는 실패 규칙을 설정하려면 런타임 정책을 추가하십시오. ```json5 { 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 전송을 사용하십시오. ```json5 { 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 모드를 사용하십시오. ```json5 { 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 권한과 모드 수준에서 비교하려면 [권한 모드](/ko/tools/permission-modes)를 참조하십시오. 모든 app-server 필드, 인증 순서, 환경 격리 및 시간 제한 동작은 [Codex 하네스 참조](/ko/plugins/codex-harness-reference)를 참조하십시오. ## 명령 및 진단 `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 `는 현재 OpenClaw 세션을 기존 Codex 스레드에 연결합니다. - `/codex bind [thread-id] [--cwd ] [--model ] [--provider ]` 는 현재 채팅을 연결합니다. - `/codex detach`(또는 `/codex unbind`)는 현재 연결을 해제합니다. - `/codex binding`은 현재 연결을 설명합니다. - `/codex stop`은 활성 턴을 중지하고, `/codex steer `는 활성 턴을 조정합니다. - `/codex 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 ` 및 `/codex plugins disable `은 구성된 네이티브 Codex Plugin을 관리합니다. - `/codex computer-use [status|install]`은 Codex Computer Use를 관리합니다. - `/codex help`는 전체 명령 트리를 나열합니다. 대부분의 지원 보고에서는 버그가 발생한 대화에서 `/diagnostics [note]`로 시작하십시오. 이 명령은 하나의 Gateway 진단 보고서를 생성하고, Codex 하네스 세션의 경우 관련 Codex 피드백 번들을 전송할 수 있도록 승인을 요청합니다. 개인정보 보호 모델과 그룹 채팅 동작은 [진단 내보내기](/ko/gateway/diagnostics)를 참조하십시오. 전체 Gateway 진단 번들 없이 현재 연결된 스레드의 Codex 피드백 업로드만 특별히 원하는 경우에만 `/codex diagnostics [note]`를 사용하십시오. ### 로컬에서 Codex 스레드 검사 문제가 있는 Codex 실행을 검사하는 가장 빠른 방법은 네이티브 Codex 스레드를 직접 여는 것입니다. ```bash codex resume ``` 완료된 `/diagnostics` 응답, `/codex binding` 또는 `/codex threads [filter]`에서 스레드 ID를 확인하십시오. 업로드 방식과 런타임 수준의 진단 경계는 [Codex 하네스 런타임](/ko/plugins/codex-harness-runtime#codex-feedback-upload)을 참조하십시오. ### 인증 순서 기본 에이전트별 홈에서 인증은 다음 순서로 선택됩니다. 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`에 추가하십시오. ```json5 { 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 필드는 다음과 같습니다. | 필드 | 기본값 | 의미 | | -------------------------- | -------------- | -------------------------------------------------------------------------------------------- | | `codexDynamicToolsLoading` | `"searchable"` | OpenClaw 동적 도구를 초기 Codex 도구 컨텍스트에 직접 넣으려면 `"direct"`를 사용하십시오. | | `codexDynamicToolsExclude` | `[]` | Codex 앱 서버 턴에서 생략할 추가 OpenClaw 동적 도구 이름입니다. | | `codexPlugins` | 비활성화 | 마이그레이션된 소스 설치형 선별 Plugin을 위한 네이티브 Codex Plugin/앱 지원입니다. | | `supervision` | 비활성화 | 보관되지 않은 네이티브 세션 카탈로그, 로컬 브랜치 연속 실행 및 에이전트 도구 정책입니다. | 지원되는 `appServer` 필드는 다음과 같습니다. | 필드 | 기본값 | 의미 | | --------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `transport` | `"stdio"` | `"stdio"`는 Codex를 실행합니다. 명시적인 `"unix"`는 로컬 제어 소켓에 연결하고, `"websocket"`은 `url`에 연결합니다. | | `homeScope` | `"agent"` | `"agent"`는 일반 하네스 상태를 OpenClaw 에이전트별로 격리합니다. `"user"`는 명시적으로 사용해야 하는 옵션으로, 네이티브 `$CODEX_HOME` 또는 `~/.codex`를 공유하고 네이티브 인증을 사용하며 소유자 전용 스레드 관리를 활성화합니다. 사용자 범위는 로컬 stdio 또는 Unix 전송을 지원합니다. 별도의 감독 연결에서는 설정되지 않은 값이 stdio 또는 Unix의 경우 `"user"`로, WebSocket의 경우 `"agent"`로 결정됩니다. | | `command` | 관리되는 Codex 바이너리 | stdio 전송에 사용할 실행 파일입니다. 관리되는 바이너리를 사용하려면 설정하지 마십시오. 명시적으로 재정의해야 할 때만 설정하십시오. | | `args` | `["app-server", "--listen", "stdio://"]` | stdio 전송에 사용할 인수입니다. | | `url` | 설정되지 않음 | WebSocket App Server URL 또는 `unix://` URL입니다. 명시적으로 빈 Unix 경로를 지정하면 표준 사용자 홈 제어 소켓이 선택됩니다. | | `authToken` | 설정되지 않음 | WebSocket 전송용 Bearer 토큰입니다. 리터럴 문자열 또는 `${CODEX_APP_SERVER_TOKEN}` 같은 SecretInput을 허용합니다. | | `headers` | `{}` | 추가 WebSocket 헤더입니다. 헤더 값에는 리터럴 문자열 또는 SecretInput 값을 사용할 수 있습니다. 예: `x-codex-client-session-token: "${CODEX_CLIENT_SESSION_TOKEN}"`. | | `clearEnv` | `[]` | OpenClaw가 상속 환경을 구성한 후 생성된 stdio app-server 프로세스에서 제거할 추가 환경 변수 이름입니다. OpenClaw는 로컬 실행 시 선택된 `CODEX_HOME`과 상속된 `HOME`을 유지합니다. | | `codeModeOnly` | `false` | Codex의 코드 모드 전용 도구 표면을 사용하도록 설정합니다. 일반 OpenClaw 동적 도구는 중첩된 `tools.*` 호출을 통해 계속 사용할 수 있으며, `openclaw_direct` 도구는 모델에 계속 직접 표시됩니다. | | `remoteWorkspaceRoot` | 설정되지 않음 | 원격 Codex app-server 작업 공간 루트입니다. 설정하면 OpenClaw는 결정된 OpenClaw 작업 공간에서 로컬 작업 공간 루트를 추론하고, 현재 cwd의 접미 경로를 이 원격 루트 아래에 유지하며, 최종 app-server cwd만 Codex에 전송합니다. cwd가 결정된 OpenClaw 작업 공간 루트 밖에 있으면 OpenClaw는 Gateway 로컬 경로를 원격 app-server로 전송하지 않고 안전하게 실패합니다. | | `requestTimeoutMs` | `60000` | app-server 제어 영역 호출의 제한 시간입니다. | | `turnCompletionIdleTimeoutMs` | `60000` | Codex가 턴을 수락한 후 또는 턴 범위 app-server 요청 후 OpenClaw가 `turn/completed`를 기다리는 동안 적용되는 무응답 대기 시간입니다. | | `postToolRawAssistantCompletionIdleTimeoutMs` | `300000` | OpenClaw가 `turn/completed`를 기다리는 동안 도구 전달, 네이티브 도구 완료, 도구 사용 후 원시 어시스턴트 진행, 원시 추론 완료 또는 추론 진행 이후에 사용하는 완료 유휴 및 진행 보호 시간입니다. 도구 사용 후 종합 과정이 최종 어시스턴트 응답 허용 시간보다 정당하게 더 오래 조용할 수 있는 신뢰할 수 있거나 무거운 워크로드에 사용하십시오. | | `mode` | 로컬 Codex 요구 사항이 YOLO를 허용하지 않는 경우를 제외하고 `"yolo"` | YOLO 또는 가디언 검토 실행을 위한 프리셋입니다. `danger-full-access`, `never` 승인 또는 `user` 검토자를 생략하는 로컬 stdio 요구 사항에서는 암시적 기본값이 가디언이 됩니다. | | `approvalPolicy` | `"never"` 또는 허용된 가디언 승인 정책 | 스레드 시작/재개/턴에 전송되는 네이티브 Codex 승인 정책입니다. 가디언 기본값은 허용되는 경우 `"on-request"`를 우선합니다. | | `sandbox` | `"danger-full-access"` 또는 허용된 가디언 샌드박스 | 스레드 시작/재개에 전송되는 네이티브 Codex 샌드박스 모드입니다. 가디언 기본값은 허용되는 경우 `"workspace-write"`를 우선하며, 그렇지 않으면 `"read-only"`를 사용합니다. OpenClaw 샌드박스가 활성화되어 있으면 `danger-full-access` 턴은 OpenClaw 샌드박스의 이그레스 설정에서 파생된 네트워크 접근 권한과 함께 Codex `workspace-write`를 사용합니다. | | `approvalsReviewer` | `"user"` 또는 허용된 가디언 검토자 | 허용되는 경우 Codex가 네이티브 승인 프롬프트를 검토하도록 하려면 `"auto_review"`를 사용하고, 그렇지 않으면 `guardian_subagent` 또는 `user`를 사용합니다. `guardian_subagent`는 레거시 별칭으로 유지됩니다. | | `serviceTier` | 설정되지 않음 | 선택적 Codex app-server 서비스 등급입니다. `"priority"`는 빠른 모드 라우팅을 활성화하고, `"flex"`는 flex 처리를 요청하며, `null`은 재정의를 해제하고, 레거시 `"fast"`는 `"priority"`로 허용됩니다. | | `networkProxy` | 비활성화됨 | app-server 명령에 Codex 권한 프로필 네트워킹을 사용하도록 설정합니다. OpenClaw는 `sandbox`를 전송하는 대신 선택한 `permissions..network` 구성을 정의하고 `default_permissions`로 선택합니다. | | `experimental.sandboxExecServer` | `false` | 네이티브 Codex 실행이 활성 OpenClaw 샌드박스 내부에서 실행될 수 있도록, 지원되는 Codex app-server에 OpenClaw 샌드박스 기반 환경을 등록하는 미리 보기 옵트인입니다. | `appServer.networkProxy`는 Codex 샌드박스 계약을 변경하므로 명시적으로 설정해야 합니다. 활성화하면 OpenClaw는 Codex 스레드 구성에 `features.network_proxy.enabled`와 `default_permissions`도 설정하여 생성된 권한 프로필이 Codex 관리형 네트워킹을 시작할 수 있도록 합니다. 기본적으로 OpenClaw는 프로필 본문에서 충돌 방지 `openclaw-network-` 프로필 이름을 생성합니다. 안정적인 로컬 이름이 필요한 경우에만 `profileName`을 사용하십시오. ```json5 { 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 대화 바인딩 또는 다른 하네스에는 영향을 주지 않습니다. 최소 마이그레이션 설정: ```json5 { 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](/ko/plugins/codex-native-plugins)을 참조하십시오. OpenAI 측 앱 및 Plugin 접근은 로그인한 Codex 계정에 의해 제어되며, Business 및 Enterprise/Edu 워크스페이스의 경우 워크스페이스 앱 제어의 영향도 받습니다. OpenAI의 계정 및 워크스페이스 제어 개요는 [ChatGPT 플랜으로 Codex 사용하기](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)를 참조하십시오. ## Computer Use Computer Use에는 별도의 설정 가이드가 있습니다. [Codex Computer Use](/ko/plugins/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 하네스 런타임](/ko/plugins/codex-harness-runtime)을 참조하십시오. ## 문제 해결 **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 호스트에서 다음 읽기 전용 명령을 실행하도록 요청하십시오. ```bash ( 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 하네스 참조](/ko/plugins/codex-harness-reference#model-discovery)를 참조하십시오. **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](/ko/plugins/codex-computer-use#troubleshooting)를 참조하십시오. ## 관련 문서 - [Codex 하니스 참조](/ko/plugins/codex-harness-reference) - [Codex 하니스 런타임](/ko/plugins/codex-harness-runtime) - [Codex 감독](/plugins/codex-supervision) - [네이티브 Codex Plugin](/ko/plugins/codex-native-plugins) - [Codex Computer Use](/ko/plugins/codex-computer-use) - [에이전트 런타임](/ko/concepts/agent-runtimes) - [모델 프로바이더](/ko/concepts/model-providers) - [OpenAI 프로바이더](/ko/providers/openai) - [OpenAI Codex 도움말](https://help.openai.com/en/collections/14937394-codex) - [에이전트 하니스 Plugin](/ko/plugins/sdk-agent-harness) - [Plugin 훅](/ko/plugins/hooks) - [진단 내보내기](/ko/gateway/diagnostics) - [상태](/ko/cli/status) - [테스트](/ko/help/testing-live#live-codex-app-server-harness-smoke)