Codex 하네스 참조 자료

이 참조 문서에서는 공식 codex plugin의 세부 구성을 다룹니다. 설정 및 라우팅을 결정하려면 Codex 하네스부터 확인하십시오.

Plugin 구성 표면

모든 Codex 하네스 설정은 plugins.entries.codex.config 아래에 있습니다.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },          appServer: {            mode: "guardian",          },        },      },    },  },}

최상위 필드:

감독

네이티브 세션 검색은 기본적으로 Gateway 컴퓨터와 옵트인된 페어링 Node에서 보관되지 않은 Codex 세션을 나열합니다. 해당 카탈로그만 비활성화하려면 다음과 같이 설정하십시오.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          sessionCatalog: {            enabled: false,          },        },      },    },  },}

supervision은 에이전트용 도구를 별도로 제어합니다.

엔드포인트 항목에는 다음 필드를 사용할 수 있습니다.

Codex Sessions 페이지는 plugin의 감독 App Server를 사용하며 보관되지 않은 세션만 표시합니다. 명시적인 appServer 연결 설정이 없으면 해당 연결은 관리형 사용자 홈 stdio입니다. 저장되었거나 유휴 상태인 행에서는 마지막 터미널 영구 저장 소스 턴까지의 제한된 사용자 및 어시스턴트 기록을 사용하여 모델이 고정된 채팅을 만들 수 있습니다. 비공개 바인딩은 스냅샷 포크, 정규 appServer 소스 브랜치, 기록 삽입 및 이후 턴을 해당 연결에 유지합니다. 첫 번째 정규 시작에서는 포크가 반환한 쌍을 사용합니다. 이후 재개 시에는 OpenClaw 모델 및 공급자 재정의를 생략하여 Codex가 정규 스레드에 영구 저장된 쌍을 복원하도록 합니다. 별도의 네이티브 변경으로 해당 쌍을 업데이트할 수 있지만 외부 모델과 대체 체인은 이를 대체하지 않습니다. 저장된 행과 유휴 행은 다른 실행자가 없다는 확인 후 보관할 수 있습니다. 단, 다른 활성 OpenClaw 바인딩이 정확한 대상 또는 그 대상에서 생성되어 보관되지 않은 하위 항목 중 하나를 소유하는 경우는 제외됩니다. OpenClaw는 Codex의 하위 항목 페이지 매김을 따르며 열거 오류, 순환 또는 안전 제한 소진 시 안전을 위해 작업을 중단합니다. 확인 절차는 여전히 알 수 없는 네이티브 클라이언트와 상태에서 보관으로 전환되는 과정의 경합을 다룹니다. 감독되는 모델 고정 채팅이 네이티브 바인딩을 보호하는 동안에는 해당 채팅을 삭제할 수 없습니다. 활성 소스에서는 브랜치를 만들거나 보관할 수 없지만, 기존에 감독되는 채팅은 계속 열 수 있습니다. 페어링된 Node의 모든 행은 읽기 전용으로 유지됩니다. Node 전송은 아직 하네스에 필요한 스트리밍 수명 주기를 제공하지 않습니다.

appServer.homeScope: "user"만으로는 관리형 하네스 프로세스가 사용하는 Codex 홈만 변경되며, 플릿 카탈로그를 게시하지는 않습니다. 감독을 활성화해도 하네스 기본값은 변경되지 않습니다. 대신 별도의 감독 연결은 명시적인 appServer 연결 설정이 없을 때 관리형 사용자 홈 stdio를 기본값으로 사용합니다. 명시적 설정이 있으면 해당 연결에 적용됩니다. 보류 중이거나 커밋된 감독 바인딩은 모든 턴에서 해당 연결을 유지합니다. 감독이 비활성화되거나 연결/수명 주기가 불일치하면 에이전트 홈 하네스로 대체하지 않고 안전을 위해 작업을 중단합니다. 기본 연결은 네이티브 Codex 클라이언트와 저장된 세션을 공유하지만, 해당 클라이언트의 프로세스 로컬 활동 상태는 공유하지 않습니다.

레거시 plugins.entries.codex-supervisor 설정은 폐기되었습니다. 이전 항목, 엔드포인트 정의, 정책 플래그 및 plugin 허용/거부 참조를 이 블록으로 마이그레이션하려면 openclaw doctor --fix을 실행하십시오. 충돌 시 명시적인 정규 codex.config.supervision 값이 우선합니다.

App-server 전송

일반 하네스 턴의 경우 OpenClaw는 공식 plugin에 포함된 관리형 Codex 바이너리 (현재 @openai/codex 0.144.3)를 시작합니다.

codex app-server --listen stdio://

이렇게 하면 app-server 버전이 로컬에 별도로 설치된 Codex CLI가 아니라 공식 codex plugin에 연결됩니다. 의도적으로 다른 실행 파일을 사용하려는 경우에만 appServer.command을 설정하십시오. 기본적으로 격리된 에이전트 홈을 사용하는 일반 관리형 턴은 macOS 데스크톱 번들이 설치되어 있어도 이 고정 패키지를 우선합니다. Computer Use가 활성화되어 있거나 homeScope가 "user"이고 네이티브 Computer Use 상태를 로드할 수 있으면, 관리형 시작은 대신 필요한 macOS 권한을 소유한 데스크톱 앱 바이너리를 우선합니다. 격리된 에이전트 홈의 유효 Codex 구성이 네이티브 Computer Use를 활성화하는 경우에도 같은 데스크톱 우선 규칙이 적용됩니다. 데스크톱 앱 번들이 설치되어 있지 않으면 OpenClaw는 고정 패키지 바이너리로 대체합니다.

실행 파일 인계와 네이티브 구성 펜싱은 실행 중인 하나의 Gateway 프로세스 내부에서 클라이언트를 조정합니다. 다른 프로세스가 네이티브 Codex plugin 구성을 변경한 후에는 Gateway를 다시 시작하십시오.

감독은 별도의 연결을 해석합니다. 명시적인 appServer 연결 설정이 없으면 homeScope: "user"을 사용하는 관리형 stdio를 사용하며, 일반 하네스는 homeScope: "agent"을 사용하는 관리형 stdio로 유지됩니다. 명시적 연결 설정은 두 경로 모두에서 적용됩니다. 일반 하네스가 네이티브 클라이언트와 $CODEX_HOME(또는 ~/.codex)을 공유해야 하는 경우 homeScope: "user"을 명시적으로 설정하십시오. 비공개 감독 바인딩은 일반 하네스 기본값과 관계없이 감독 연결을 사용합니다. 독립적인 App Server 프로세스는 각각 별도의 실시간 상태와 승인 상태를 유지합니다.

이미 실행 중인 app-server에는 WebSocket 전송을 사용하십시오.

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

appServer 필드:

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

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

일반 앱 서버 런타임이 danger-full-access인 경우, networkProxy을 활성화하면 생성된 권한 프로필에 대신 워크스페이스 방식의 파일 시스템 접근을 사용합니다. Codex 관리 네트워크 적용은 샌드박스 네트워킹이므로 전체 접근 프로필은 아웃바운드 트래픽을 보호하지 못합니다.

Plugin은 이전 버전이거나 버전이 지정되지 않은 앱 서버 핸드셰이크를 차단합니다. Codex 앱 서버는 안정 버전 0.143.0 이상을 보고해야 합니다.

OpenClaw는 루프백이 아닌 WebSocket 앱 서버 URL을 원격으로 취급하며 appServer.authToken 또는 Authorization 헤더를 통한 ID 포함 WebSocket 인증을 요구합니다. appServer.authToken 및 각 appServer.headers.* 값에는 SecretInput을 사용할 수 있습니다. 시크릿 런타임은 OpenClaw가 앱 서버 시작 옵션을 구성하기 전에 SecretRef와 환경 변수 축약형을 확인하며, 확인되지 않은 구조화된 SecretRef는 토큰이나 헤더가 전송되기 전에 실패합니다. 네이티브 Codex Plugin이 구성되어 있으면 OpenClaw는 연결된 앱 서버의 Plugin 제어 영역을 사용하여 해당 Plugin을 설치하거나 새로 고친 다음, Plugin 소유 앱이 Codex 스레드에 표시되도록 앱 인벤토리를 새로 고칩니다. app/list은 여전히 신뢰할 수 있는 인벤토리 및 메타데이터 소스이지만, Codex가 현재 비활성화된 것으로 표시하더라도 목록에 있는 접근 가능한 앱에 대해 thread/start이 config.apps[appId].enabled = true을 전송할지는 OpenClaw 정책이 결정합니다. 알 수 없거나 누락된 앱 ID는 계속 실패 시 닫힌 상태로 유지됩니다. 이 경로는 plugin/install을 통해 마켓플레이스 Plugin을 활성화하고 인벤토리를 새로 고치기만 합니다. OpenClaw 관리 Plugin 설치 및 앱 인벤토리 새로 고침을 수락하도록 신뢰할 수 있는 원격 앱 서버에만 OpenClaw를 연결하십시오.

승인 및 샌드박스 모드

로컬 stdio 앱 서버 세션은 기본적으로 YOLO 모드를 사용합니다. approvalPolicy: "never", approvalsReviewer: "user", 그리고 sandbox: "danger-full-access"입니다. 이 신뢰할 수 있는 로컬 운영자 태세를 통해 무인 OpenClaw 턴과 Heartbeat가 응답할 사람이 없는 네이티브 승인 프롬프트 없이 진행될 수 있습니다.

Codex의 로컬 시스템 요구 사항 파일에서 암시적 YOLO 승인, 검토자 또는 샌드박스 값을 허용하지 않으면 OpenClaw는 암시적 기본값을 대신 guardian으로 취급하고 허용된 guardian 권한을 선택합니다. tools.exec.mode: "auto"도 guardian 검토 방식의 Codex 승인을 강제하며 안전하지 않은 레거시 approvalPolicy: "never" 또는 sandbox: "danger-full-access" 재정의를 유지하지 않습니다. 의도적으로 승인하지 않는 태세를 사용하려면 tools.exec.mode: "full"을 설정하십시오. 같은 요구 사항 파일에서 호스트 이름과 일치하는 [[remote_sandbox_config]] 항목은 샌드박스 기본값 결정에 반영됩니다.

Codex guardian 검토 승인을 사용하려면 appServer.mode: "guardian"을 설정하십시오.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            mode: "guardian",            serviceTier: "priority",          },        },      },    },  },}

guardian 프리셋은 해당 값이 허용되는 경우 approvalPolicy: "on-request", approvalsReviewer: "auto_review", 그리고 sandbox: "workspace-write"으로 확장됩니다. 개별 정책 필드는 mode을 재정의합니다. 이전 guardian_subagent 검토자 값도 호환성 별칭으로 계속 허용되지만 새 구성에서는 auto_review을 사용해야 합니다.

OpenClaw 샌드박스가 활성화된 경우에도 로컬 Codex 앱 서버 프로세스는 Gateway 호스트에서 실행됩니다. 따라서 OpenClaw는 Codex 호스트 측 샌드박싱을 OpenClaw 샌드박스 백엔드와 동일하게 취급하지 않고, 해당 턴에서 Codex 네이티브 Code Mode, 사용자 MCP 서버 및 앱 기반 Plugin 실행을 비활성화합니다. 일반 exec/process 도구를 사용할 수 있는 경우 셸 접근은 sandbox_exec 및 sandbox_process과 같은 OpenClaw 샌드박스 기반 동적 도구를 통해 제공됩니다.

샌드박스 적용 네이티브 실행

안정적인 기본값은 실패 시 닫힘입니다. 활성 OpenClaw 샌드박싱은 Codex 앱 서버 호스트에서 실행되었을 Codex 네이티브 실행 표면을 비활성화합니다. OpenClaw의 샌드박스 백엔드에서 Codex의 원격 환경 지원을 시험하려는 경우에만 appServer.experimental.sandboxExecServer: true을 사용하십시오. 이 미리 보기 경로는 지원되는 모든 Codex 앱 서버 버전에서 작동합니다.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            experimental: {              sandboxExecServer: true,            },          },        },      },    },  },}

플래그가 켜져 있고 현재 OpenClaw 세션이 샌드박스 적용 상태이면 OpenClaw는 활성 샌드박스를 기반으로 하는 로컬 루프백 exec 서버를 시작하여 Codex 앱 서버에 등록하고, OpenClaw 소유 환경으로 Codex 스레드와 턴을 시작합니다. 앱 서버가 환경을 등록할 수 없으면 호스트 실행으로 조용히 대체하지 않고 실행이 실패 시 닫힙니다.

이 미리 보기 경로는 로컬 전용입니다. 원격 WebSocket 앱 서버는 동일한 호스트에서 실행되지 않는 한 루프백 exec 서버에 접근할 수 없으므로 OpenClaw는 이 조합을 거부합니다.

인증 및 환경 격리

기본 에이전트별 홈에서는 다음 순서로 인증을 선택합니다.

1. 에이전트에 대한 명시적 OpenClaw Codex 인증 프로필입니다.
2. 해당 에이전트의 Codex 홈에 있는 앱 서버의 기존 계정입니다.
3. 로컬 stdio 앱 서버 실행에만 해당하며, 앱 서버 계정이 없고 OpenAI 인증이 여전히 필요한 경우 CODEX_API_KEY, 그다음 OPENAI_API_KEY입니다.

OpenClaw가 ChatGPT 구독 방식의 Codex 인증 프로필(OAuth 또는 토큰 자격 증명 유형)을 감지하면 생성된 Codex 자식 프로세스에서 CODEX_API_KEY 및 OPENAI_API_KEY을 제거합니다. 이를 통해 Gateway 수준 API 키를 임베딩이나 직접 OpenAI 모델에 사용할 수 있게 유지하면서 네이티브 Codex 앱 서버 턴이 실수로 API를 통해 과금되는 것을 방지합니다.

명시적 Codex API 키 프로필 및 로컬 stdio 환경 키 대체는 상속된 자식 프로세스 환경 대신 앱 서버 로그인을 사용합니다. WebSocket 앱 서버 연결에는 Gateway 환경 API 키 대체가 전달되지 않습니다. 명시적 인증 프로필이나 원격 앱 서버 자체 계정을 사용하십시오.

stdio 앱 서버 실행은 기본적으로 OpenClaw의 프로세스 환경을 상속합니다. OpenClaw는 Codex 앱 서버 계정 브리지를 소유하며 CODEX_HOME을 해당 에이전트의 OpenClaw 상태 아래에 있는 에이전트별 디렉터리로 설정합니다. 이를 통해 Codex 구성, 계정, Plugin 캐시/데이터 및 스레드 상태의 범위가 운영자의 개인 ~/.codex 홈에서 유입되지 않고 OpenClaw 에이전트로 제한됩니다.

네이티브 Codex 상태를 Codex Desktop 및 CLI와 공유하려면 appServer.homeScope: "user"을 설정하십시오. 이 로컬 사용자 홈 모드는 관리형 stdio 및 명시적 Unix 전송을 지원합니다. 설정된 경우 $CODEX_HOME을 사용하고, 그렇지 않으면 ~/.codex을 사용하며 네이티브 인증, 구성, Plugin 및 스레드를 포함합니다. OpenClaw는 앱 서버에 대한 인증 프로필 브리지를 건너뜁니다. 확인된 소유자 턴은 codex_threads을 사용하여 해당 스레드를 목록 조회(선택적 search 필터 포함), 읽기, 포크, 이름 변경, 보관 및 보관 해제할 수 있습니다. OpenClaw에서 계속하기 전에 스레드를 포크하십시오. 독립적인 Codex 프로세스는 같은 스레드에 대한 동시 작성자를 조정하지 않습니다.

이 homeScope 옵트인은 일반 하네스 세션에 적용됩니다. Codex Sessions를 통해 생성된 Chat은 대신 전용 감독 연결을 사용하며, 이 연결은 정식 브랜치와 향후 재개를 위해 네이티브 연결의 인증 및 제공자 구성을 유지합니다.

모델이 잠긴 감독형 Chat에서 codex_threads은 다른 포크를 연결하거나 Chat에 바인딩된 네이티브 스레드를 보관할 수 없습니다. 목록 조회 및 메타데이터 전용 읽기는 계속 사용할 수 있습니다. 원시 대화 기록을 읽으려면 allowRawTranscripts이 필요합니다. 비활성화된 경우 네이티브 검색이 대화 기록 미리 보기와 일치할 수 있으므로 목록 검색도 거부됩니다. 다른 OpenClaw Chat이 소유하지 않은 관련 없는 스레드의 이름 변경, 보관 해제, 분리된 포크 및 보관에는 allowWriteControls이 필요합니다. 어느 옵션도 잠긴 바인딩을 우회하지 않습니다.

OpenClaw는 일반 로컬 앱 서버 실행에서 HOME을 다시 작성하지 않습니다. openclaw, gh, git, 클라우드 CLI 및 셸 명령과 같은 Codex 실행 하위 프로세스는 일반 프로세스 홈을 보고 사용자 홈 구성 및 토큰을 찾을 수 있습니다. Codex는 $HOME/.agents/skills 및 $HOME/.agents/plugins/marketplace.json도 검색할 수 있습니다. 이 .agents 검색은 의도적으로 운영자 홈과 공유되며 격리된 ~/.codex 상태와는 별개입니다.

기본 에이전트 범위에서 OpenClaw Plugin 및 OpenClaw Skills 스냅샷은 계속 OpenClaw 자체 Plugin 레지스트리와 Skills 로더를 통해 전달되지만 개인 Codex ~/.codex 자산은 그렇지 않습니다. 격리된 OpenClaw 에이전트의 일부가 되어야 하는 Codex 홈의 유용한 Codex CLI Skills 또는 Plugin이 있다면 명시적으로 인벤토리를 작성하십시오.

openclaw migrate codex --dry-runopenclaw migrate apply codex --yes

배포에 추가 환경 격리가 필요한 경우 해당 변수를 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 로딩을 사용하며 deferLoading: true을 통해 openclaw 네임스페이스 아래에 노출됩니다. OpenClaw는 일반적으로 Codex 네이티브 워크스페이스 작업이나 Codex 자체 도구 검색 표면과 중복되는 동적 도구를 노출하지 않습니다.

• read
• write
• edit
• apply_patch
• exec
• process
• update_plan
• tool_call
• tool_describe
• tool_search
• tool_search_code

유한 런타임 허용 목록이 네이티브 Code Mode를 비활성화하면 OpenClaw는 빈 실행 환경 선택을 전송합니다. 이러한 직접적인 비샌드박스 상황에서 OpenClaw는 정책으로 필터링된 exec 및 process 도구를 셸 대체 수단으로 유지합니다. 런타임 허용 목록 및 codexDynamicToolsExclude은 계속 적용됩니다.

나머지 대부분의 OpenClaw 통합 도구(예: 메시징, 미디어, Cron, 브라우저, Node, Gateway, heartbeat_respond, web_search)는 해당 네임스페이스 아래의 Codex 도구 검색을 통해 사용할 수 있습니다. 이렇게 하면 초기 모델 컨텍스트가 더 작게 유지됩니다. Codex 도구 검색을 사용할 수 없거나 커넥터 전용 유니버스로 해석될 수 있으므로, 일부 도구는 codexDynamicToolsLoading와 관계없이 계속 직접 호출할 수 있습니다. 해당 도구는 agents_list, sessions_spawn, sessions_yield입니다. 개발자 지침은 Codex 네이티브 하위 에이전트 작업에서 일반 Codex 하위 에이전트가 네이티브 spawn_agent을 사용하도록 계속 유도하며, 명시적인 OpenClaw 또는 ACP 위임에는 sessions_spawn을 계속 사용할 수 있습니다. 메시지 도구만 사용하는 소스 응답 역시 직접 처리됩니다. 이는 턴 제어 계약이기 때문입니다.

OpenClaw computer 도구를 포함하여 catalogMode: "direct-only"로 표시된 도구는 openclaw_direct 아래에 그룹화됩니다. OpenClaw는 운영자가 제공한 항목을 대체하지 않고 해당 네임스페이스를 Codex의 code_mode.direct_only_tool_namespaces 목록에 추가합니다. 따라서 Codex는 이러한 도구를 중첩된 Code Mode tools.* 호출을 통해 라우팅하지 않고 일반 스레드와 코드 모드 전용 스레드에서 DirectModelOnly로 노출합니다. 이 경계는 이미지가 포함된 결과에 필요합니다. 중첩된 Code Mode 직렬화는 이미지 출력을 텍스트로 평면화하므로, 다음 컴퓨터 작업에 필요한 스크린샷이 손실되기 때문입니다.

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

시간 제한

OpenClaw가 소유한 동적 도구 호출은 appServer.requestTimeoutMs과 별도로 제한됩니다. 각 Codex item/tool/call 요청은 다음 순서로 처음 사용 가능한 시간 제한을 사용합니다.

• 호출별 양수 timeoutMs 인수.
• image_generate의 경우 agents.defaults.imageGenerationModel.timeoutMs.
• 시간 제한이 구성되지 않은 image_generate의 경우 120초 이미지 생성 기본값.
• 미디어 이해 image 도구의 경우 tools.media.image.timeoutSeconds을 밀리초로 변환한 값 또는 60초 미디어 기본값. 이미지 이해의 경우 이는 요청 자체에 적용되며 이전 준비 작업으로 인해 단축되지 않습니다.
• message 도구의 경우 고정된 120초 기본값.
• 90초 동적 도구 기본값.

이 감시 타이머는 외부 동적 item/tool/call 예산입니다. 공급자별 요청 시간 제한은 해당 호출 내에서 실행되며 자체 시간 제한 의미 체계를 유지합니다. 동적 도구 예산은 600000ms로 제한됩니다. 시간 초과 시 OpenClaw는 지원되는 경우 도구 신호를 중단하고 실패한 동적 도구 응답을 Codex에 반환하여 세션을 processing 상태로 남기지 않고 턴을 계속할 수 있게 합니다.

Codex가 턴을 수락한 후와 OpenClaw가 턴 범위 앱 서버 요청에 응답한 후, 하네스는 Codex가 현재 턴을 진행하고 결국 turn/completed을 사용해 네이티브 턴을 완료할 것으로 예상합니다. 앱 서버가 appServer.turnCompletionIdleTimeoutMs 동안 아무 응답도 하지 않으면 OpenClaw는 최선의 방식으로 Codex 턴을 중단하고 진단 시간 초과를 기록하며 OpenClaw 세션 레인을 해제하여 후속 채팅 메시지가 오래된 네이티브 턴 뒤에 대기하지 않도록 합니다.

동일한 턴에서 발생하는 대부분의 비종료 알림은 Codex가 턴이 아직 활성 상태임을 입증했으므로 이 짧은 감시 타이머를 해제합니다. 도구 핸드오프에는 더 긴 도구 실행 후 유휴 예산을 사용합니다. OpenClaw가 item/tool/call 응답을 반환한 후, commandExecution 같은 네이티브 도구 항목이 완료된 후, 원시 custom_tool_call_output 완료 후, 그리고 도구 실행 후 원시 어시스턴트 진행 상황, 원시 추론 완료 또는 추론 진행 상황 후가 이에 해당합니다. 가드는 구성된 경우 appServer.postToolRawAssistantCompletionIdleTimeoutMs을 사용하며, 그렇지 않으면 기본값으로 5분을 사용합니다. 동일한 도구 실행 후 예산은 Codex가 다음 현재 턴 이벤트를 내보내기 전의 조용한 종합 구간에도 진행 감시 타이머를 연장합니다. 추론 완료, 코멘터리 agentMessage 완료, 도구 실행 전 원시 추론 또는 어시스턴트 진행 상황 뒤에는 자동 최종 응답이 이어질 수 있으므로, 세션 레인을 즉시 해제하는 대신 진행 후 응답 가드를 사용합니다. 최종/비코멘터리 완료 agentMessage 항목과 도구 실행 전 원시 어시스턴트 완료만 어시스턴트 출력 해제를 활성화합니다. 이후 Codex가 turn/completed 없이 응답을 멈추면 OpenClaw는 최선의 방식으로 네이티브 턴을 중단하고 세션 레인을 해제합니다. 어시스턴트, 도구, 활성 항목 또는 부작용 증거가 없는 턴 완료 유휴 시간 초과를 포함한 재생 안전 stdio 앱 서버 실패는 새 앱 서버 시도에서 한 번 재시도됩니다. 안전하지 않은 시간 초과는 멈춘 앱 서버 클라이언트를 폐기하고 OpenClaw 세션 레인을 해제합니다. 또한 자동으로 재생하는 대신 오래된 네이티브 스레드 바인딩을 제거합니다. 완료 감시 시간 초과는 Codex 전용 시간 초과 문구를 표시합니다. 재생 안전 사례에서는 응답이 불완전할 수 있다고 안내하고, 안전하지 않은 사례에서는 재시도하기 전에 현재 상태를 확인하도록 사용자에게 안내합니다. 공개 시간 초과 진단에는 마지막 앱 서버 알림 메서드, 원시 어시스턴트 응답 항목 ID/유형/역할, 활성 요청/항목 수, 활성화된 감시 상태 같은 구조적 필드가 포함됩니다. 마지막 알림이 원시 어시스턴트 응답 항목이면 제한된 길이의 어시스턴트 텍스트 미리보기도 포함됩니다. 원시 프롬프트나 도구 콘텐츠는 포함되지 않습니다.

모델 검색

기본적으로 Codex Plugin은 앱 서버에 사용 가능한 모델을 요청합니다. 모델 가용성은 Codex 앱 서버가 관리하므로 OpenClaw가 번들 @openai/codex 버전을 업그레이드하거나 배포에서 appServer.command이 다른 Codex 바이너리를 가리키면 목록이 변경될 수 있습니다. 가용성은 계정별로 다를 수도 있습니다. 실행 중인 Gateway에서 /codex models을 사용하여 해당 하네스와 계정의 실시간 카탈로그를 확인하십시오.

검색이 실패하거나 시간 초과되면 OpenClaw는 번들 대체 카탈로그를 사용합니다.

plugins.entries.codex.config.discovery 아래에서 검색을 조정하십시오.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },        },      },    },  },}

시작 시 Codex 프로브를 피하고 대체 카탈로그만 사용하려면 검색을 비활성화하십시오.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: false,          },        },      },    },  },}

작업 공간 부트스트랩 파일

Codex는 네이티브 프로젝트 문서 검색을 통해 AGENTS.md을 직접 처리합니다. OpenClaw는 합성 Codex 프로젝트 문서 파일을 작성하거나 페르소나 파일에 Codex 대체 파일 이름을 사용하지 않습니다. Codex 대체 파일 이름은 AGENTS.md이 없을 때만 적용되기 때문입니다.

OpenClaw 작업 공간과의 동등성을 위해 Codex 하네스는 다른 부트스트랩 파일을 개발자 지침으로 전달하지만, 동일한 방식으로 전달하지는 않습니다.

• TOOLS.md은 상속되는 Codex 개발자 지침으로 전달되므로 턴 중에 생성된 네이티브 Codex 하위 에이전트도 이를 확인할 수 있습니다.
• SOUL.md, IDENTITY.md, USER.md은 턴 범위 협업 지침으로 전달됩니다. 네이티브 Codex 하위 에이전트는 이를 상속하지 않으므로 하위 에이전트 턴이 상위 에이전트의 페르소나와 사용자 프로필을 가져오지 않습니다.
• 간결하게 로드된 OpenClaw Skills 목록도 턴 범위 협업 개발자 지침으로 전달되므로 네이티브 Codex 하위 에이전트는 이 목록 역시 상속하지 않습니다.
• HEARTBEAT.md 콘텐츠는 주입되지 않습니다. Heartbeat 턴은 파일이 존재하고 비어 있지 않을 때 해당 파일을 읽으라는 협업 모드 포인터를 받습니다.
• 구성된 에이전트 작업 공간의 MEMORY.md 콘텐츠는 해당 작업 공간에서 메모리 도구를 사용할 수 있을 때 네이티브 Codex 턴 입력에 붙여 넣지 않습니다. 해당 콘텐츠가 존재하면 하네스가 작은 작업 공간 메모리 포인터를 턴 범위 협업 개발자 지침에 추가하며, 영구 메모리가 관련된 경우 Codex는 memory_search 또는 memory_get을 사용해야 합니다. 도구가 비활성화되어 있거나, 메모리 검색을 사용할 수 없거나, 활성 작업 공간이 에이전트 메모리 작업 공간과 다른 경우에는 MEMORY.md이 일반적인 제한된 턴 컨텍스트 경로를 사용합니다.
• BOOTSTRAP.md은 존재하는 경우 OpenClaw 턴 입력 참조 컨텍스트로 전달됩니다.

환경 재정의

로컬 테스트에는 환경 재정의를 계속 사용할 수 있습니다.

• 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

appServer.command이 설정되지 않은 경우 OPENCLAW_CODEX_APP_SERVER_BIN은 관리형 바이너리를 우회합니다.

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

관련 항목

• Codex 하네스
• Codex 하네스 런타임
• Codex 감독
• 네이티브 Codex Plugin
• Codex 컴퓨터 사용
• OpenAI 공급자
• 구성 참조