OpenClaw 한국어 문서

Appearance

번들된 codex 플러그인은 OpenClaw가 내장 PI harness 대신 Codex app-server를 통해 임베디드 agent 턴을 실행할 수 있도록 합니다.

Codex가 저수준 agent 세션(모델 discovery, 네이티브 thread resume, 네이티브 compaction, app-server 실행)을 소유하도록 하고 싶을 때 사용하십시오. OpenClaw는 여전히 채팅 채널, 세션 파일, 모델 선택, 도구, 승인(approval), 미디어 전달 및 가시적인 transcript mirror를 소유합니다.

네이티브 Codex 턴은 OpenClaw 플러그인 훅을 공개 호환성 계층(public compatibility layer)으로 유지합니다. 이들은 in-process OpenClaw 훅이며, Codex hooks.json 커맨드 훅이 아닙니다:

  • before_prompt_build
  • before_compaction, after_compaction
  • llm_input, llm_output
  • after_tool_call
  • mirror된 transcript 레코드를 위한 before_message_write
  • agent_end

번들된 플러그인은 비동기 tool_result 미들웨어를 추가하기 위해 Codex app-server 확장 팩토리(extension factory)를 등록할 수도 있습니다. 해당 미들웨어는 OpenClaw 동적 도구에 대해 OpenClaw가 도구를 실행한 후, 결과가 Codex에 반환되기 전에 실행됩니다. 이는 OpenClaw가 소유한 transcript tool-result 쓰기를 변환하는 공개 tool_result_persist 플러그인 훅과는 별개입니다.

harness는 기본적으로 꺼져 있습니다. 새 설정은 OpenAI 모델 참조를 openai/gpt-*로 canonical하게 유지하고, 네이티브 app-server 실행을 원할 때 embeddedHarness.runtime: "codex" 또는 OPENCLAW_AGENT_RUNTIME=codex를 명시적으로 강제해야 합니다. 호환성을 위해 레거시 codex/* 모델 참조는 여전히 자동으로 harness를 선택합니다.

올바른 모델 prefix 선택 ​

OpenAI 계열 경로는 prefix별로 구분됩니다. PI를 통해 Codex OAuth를 원할 때는 openai-codex/*를 사용하고, 직접적인 OpenAI API 접근을 원하거나 네이티브 Codex app-server harness를 강제할 때는 openai/*를 사용하십시오:

Model refRuntime 경로사용 시점
openai/gpt-5.4OpenClaw/PI plumbing을 통한 OpenAI providerOPENAI_API_KEY로 현재 직접 OpenAI Platform API 접근을 원할 때.
openai-codex/gpt-5.5OpenClaw/PI를 통한 OpenAI Codex OAuth기본 PI runner와 함께 ChatGPT/Codex 구독 인증을 원할 때.
openai/gpt-5.5 + embeddedHarness.runtime: "codex"Codex app-server harness임베디드 agent 턴에 대해 네이티브 Codex app-server 실행을 원할 때.

GPT-5.5는 현재 OpenClaw에서 구독/OAuth 전용입니다. PI OAuth에는 openai-codex/gpt-5.5를 사용하거나, Codex app-server harness와 함께 openai/gpt-5.5를 사용하십시오. openai/gpt-5.5에 대한 직접 API-key 접근은 OpenAI가 공개 API에서 GPT-5.5를 활성화하면 지원됩니다.

레거시 codex/gpt-* 참조는 호환성 alias로 계속 수용됩니다. 새 PI Codex OAuth 설정은 openai-codex/gpt-*를 사용해야 하고, 새 네이티브 app-server harness 설정은 openai/gpt-* 및 embeddedHarness.runtime: "codex"를 사용해야 합니다.

agents.defaults.imageModel도 동일한 prefix 분기를 따릅니다. 이미지 이해를 OpenAI Codex OAuth provider 경로를 통해 실행하려면 openai-codex/gpt-*를 사용하십시오. 이미지 이해를 bounded Codex app-server 턴을 통해 실행하려면 codex/gpt-*를 사용하십시오. Codex app-server 모델은 이미지 입력 지원을 광고(advertise)해야 합니다. 텍스트 전용 Codex 모델은 미디어 턴이 시작되기 전에 실패합니다.

현재 세션에 적용된 harness를 확인하려면 /status를 사용하십시오. 선택이 예상과 다르면 agents/harness 서브시스템에 대해 디버그 로깅을 활성화하고 gateway의 구조화된 agent harness selected 레코드를 검사하십시오. 이 레코드에는 선택된 harness id, 선택 이유, runtime/fallback 정책, 그리고 auto 모드에서는 각 플러그인 후보의 지원 결과가 포함됩니다.

Harness 선택은 라이브 세션 제어가 아닙니다. 임베디드 턴이 실행되면 OpenClaw는 해당 세션에 선택된 harness id를 기록하고, 같은 세션 id의 이후 턴에 대해서도 계속 사용합니다. 향후 세션이 다른 harness를 사용하도록 하려면 embeddedHarness 설정 또는 OPENCLAW_AGENT_RUNTIME을 변경하십시오. 기존 대화를 PI와 Codex 간에 전환하려면 /new 또는 /reset을 사용해 새 세션을 시작하십시오. 이렇게 하면 하나의 transcript를 호환되지 않는 두 네이티브 세션 시스템을 통해 재생하는 것을 방지할 수 있습니다.

harness pin 이전에 만들어진 레거시 세션은 transcript history가 있으면 PI-pinned로 취급됩니다. 설정 변경 후 해당 대화를 Codex로 전환하려면 /new 또는 /reset을 사용하십시오.

/status는 유효한 non-PI harness를 Fast 옆에 표시합니다. 예: Fast · codex. 기본 PI harness는 Runner: pi (embedded)로 유지되며 별도의 harness 배지를 추가하지 않습니다.

요구 사항 ​

  • 번들된 codex 플러그인이 사용 가능한 OpenClaw.
  • Codex app-server 0.118.0 이상.
  • app-server 프로세스에서 사용 가능한 Codex 인증.

플러그인은 더 오래되었거나 버전이 없는 app-server 핸드셰이크를 차단합니다. 이는 OpenClaw가 테스트된 프로토콜 표면에 머물도록 합니다.

라이브 및 Docker smoke 테스트의 경우, 인증은 일반적으로 OPENAI_API_KEY와 ~/.codex/auth.json 및 ~/.codex/config.toml 같은 선택적 Codex CLI 파일에서 옵니다. 로컬 Codex app-server가 사용하는 것과 동일한 인증 자료를 사용하십시오.

최소 설정 ​

openai/gpt-5.5를 사용하고, 번들된 플러그인을 활성화하고, codex harness를 강제하십시오:

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

설정이 plugins.allow를 사용한다면 거기에도 codex를 포함하십시오:

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

agents.defaults.model 또는 agent 모델을 codex/<model>로 설정한 레거시 설정은 여전히 번들 codex 플러그인을 자동 활성화합니다. 새 설정은 openai/<model>과 위의 명시적 embeddedHarness 항목을 선호해야 합니다.

다른 모델을 교체하지 않고 Codex 추가하기 ​

레거시 codex/* 참조가 Codex를 선택하고 나머지는 PI를 사용하도록 하려면 runtime: "auto"를 유지하십시오. 새 설정의 경우, harness를 사용해야 하는 agent에 대해 명시적 runtime: "codex"를 선호하십시오.

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-5.5",
        fallbacks: ["openai/gpt-5.5", "anthropic/claude-opus-4-6"],
      },
      models: {
        "openai/gpt-5.5": { alias: "gpt" },
        "anthropic/claude-opus-4-6": { alias: "opus" },
      },
      embeddedHarness: {
        runtime: "codex",
        fallback: "pi",
      },
    },
  },
}

이 형태에서는:

  • /model gpt 또는 /model openai/gpt-5.5는 이 설정에서 Codex app-server harness를 사용합니다.
  • /model opus는 Anthropic provider 경로를 사용합니다.
  • non-Codex 모델이 선택되면 PI가 호환성 harness로 남습니다.

Codex 전용 배포 ​

모든 임베디드 agent 턴이 Codex harness를 사용한다는 것을 증명해야 한다면 PI fallback을 비활성화하십시오:

json5
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

환경 변수 오버라이드:

bash
OPENCLAW_AGENT_RUNTIME=codex \
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run

fallback을 비활성화하면 Codex 플러그인이 비활성화되었거나, app-server가 너무 오래되었거나, app-server를 시작할 수 없는 경우 OpenClaw는 조기 실패합니다.

agent별 Codex ​

기본 agent는 정상적인 자동 선택을 유지하면서 하나의 agent만 Codex 전용으로 만들 수 있습니다:

json5
{
  agents: {
    defaults: {
      embeddedHarness: {
        runtime: "auto",
        fallback: "pi",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        embeddedHarness: {
          runtime: "codex",
          fallback: "none",
        },
      },
    ],
  },
}

agent와 모델을 전환하려면 일반 세션 명령을 사용하십시오. /new는 새로운 OpenClaw 세션을 생성하고, Codex harness는 필요에 따라 사이드카 app-server thread를 생성하거나 재개합니다. /reset은 해당 thread에 대한 OpenClaw 세션 바인딩을 지우고, 다음 턴이 현재 설정에서 harness를 다시 결정하도록 합니다.

모델 discovery ​

기본적으로 Codex 플러그인은 app-server에 사용 가능한 모델을 요청합니다. discovery가 실패하거나 타임아웃되면 다음에 대해 번들된 fallback 카탈로그를 사용합니다:

  • GPT-5.5
  • GPT-5.4 mini
  • GPT-5.2

plugins.entries.codex.config.discovery에서 discovery를 튜닝할 수 있습니다:

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

시작 시 Codex probing을 피하고 fallback 카탈로그를 고수하려면 discovery를 비활성화하십시오:

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

app-server 연결 및 정책 ​

기본적으로 플러그인은 다음과 같이 Codex를 로컬에서 시작합니다:

bash
codex app-server --listen stdio://

기본적으로 OpenClaw는 로컬 Codex harness 세션을 YOLO 모드로 시작합니다: approvalPolicy: "never", approvalsReviewer: "user", sandbox: "danger-full-access". 이는 자율 heartbeat에 사용되는 신뢰된 로컬 운영자 자세(trusted local operator posture)입니다. Codex는 아무도 답할 수 없는 네이티브 승인 프롬프트에서 멈추지 않고 shell 및 네트워크 도구를 사용할 수 있습니다.

Codex guardian-reviewed 승인을 opt-in하려면 appServer.mode: "guardian"을 설정하십시오:

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

Guardian은 네이티브 Codex 승인 reviewer입니다. Codex가 sandbox를 벗어나거나, workspace 외부에 쓰거나, 네트워크 접근 같은 권한을 추가하도록 요청할 때, Codex는 해당 승인 요청을 사람에게 프롬프트하는 대신 reviewer subagent에 라우팅합니다. reviewer는 Codex의 risk framework를 적용하고 구체적인 요청을 승인 또는 거부합니다. YOLO 모드보다 더 많은 guardrail을 원하지만 여전히 무인 agent가 진행되어야 할 때 Guardian을 사용하십시오.

guardian 프리셋은 approvalPolicy: "on-request", approvalsReviewer: "guardian_subagent", sandbox: "workspace-write"로 확장됩니다. 개별 정책 필드는 여전히 mode를 오버라이드하므로, 고급 배포에서는 프리셋과 명시적 선택을 혼합할 수 있습니다.

이미 실행 중인 app-server의 경우 WebSocket transport를 사용하십시오:

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

지원되는 appServer 필드:

Field기본값의미
transport"stdio""stdio"는 Codex를 spawn하고, "websocket"은 url에 연결합니다.
command"codex"stdio transport용 실행 파일.
args["app-server", "--listen", "stdio://"]stdio transport용 인수.
url미설정WebSocket app-server URL.
authToken미설정WebSocket transport용 bearer 토큰.
headers{}추가 WebSocket header.
requestTimeoutMs60000app-server control-plane 호출에 대한 타임아웃.
mode"yolo"YOLO 또는 guardian-reviewed 실행을 위한 프리셋.
approvalPolicy"never"thread start/resume/turn에 전송되는 네이티브 Codex 승인 정책.
sandbox"danger-full-access"thread start/resume에 전송되는 네이티브 Codex sandbox 모드.
approvalsReviewer"user"Codex Guardian이 프롬프트를 review하도록 하려면 "guardian_subagent"를 사용하십시오.
serviceTier미설정선택적 Codex app-server 서비스 tier: "fast", "flex" 또는 null. 유효하지 않은 레거시 값은 무시됩니다.

이전 환경 변수는 일치하는 config 필드가 설정되지 않았을 때 로컬 테스팅용 fallback으로 여전히 작동합니다:

  • 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을 사용하십시오. config는 반복 가능한 배포에 선호됩니다. 플러그인 동작을 Codex harness 설정의 나머지와 동일한 review된 파일에 유지하기 때문입니다.

일반적인 레시피 ​

기본 stdio transport를 사용하는 로컬 Codex:

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

PI fallback이 비활성화된 Codex 전용 harness 검증:

json5
{
  embeddedHarness: {
    fallback: "none",
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}

Guardian-reviewed Codex 승인:

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            approvalPolicy: "on-request",
            approvalsReviewer: "guardian_subagent",
            sandbox: "workspace-write",
          },
        },
      },
    },
  },
}

명시적 header가 있는 원격 app-server:

json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            headers: {
              "X-OpenClaw-Agent": "main",
            },
          },
        },
      },
    },
  },
}

모델 전환은 OpenClaw가 제어합니다. OpenClaw 세션이 기존 Codex thread에 연결되어 있을 때, 다음 턴은 현재 선택된 OpenAI 모델, provider, 승인 정책, sandbox, service tier를 app-server에 다시 보냅니다. openai/gpt-5.5에서 openai/gpt-5.2로 전환하면 thread 바인딩은 유지되지만 새로 선택된 모델로 계속 진행하도록 Codex에 요청합니다.

Codex 명령 ​

번들된 플러그인은 /codex를 권한 부여된(authorized) slash 명령으로 등록합니다. 이는 일반적(generic)이며 OpenClaw 텍스트 명령을 지원하는 모든 채널에서 작동합니다.

일반적인 형식:

  • /codex status는 라이브 app-server 연결성, 모델, 계정, rate limit, MCP 서버, skills를 보여줍니다.
  • /codex models는 라이브 Codex app-server 모델을 나열합니다.
  • /codex threads [filter]는 최근 Codex thread를 나열합니다.
  • /codex resume <thread-id>는 현재 OpenClaw 세션을 기존 Codex thread에 연결합니다.
  • /codex compact는 연결된 thread를 compact하도록 Codex app-server에 요청합니다.
  • /codex review는 연결된 thread에 대해 Codex 네이티브 review를 시작합니다.
  • /codex account는 계정 및 rate-limit 상태를 보여줍니다.
  • /codex mcp는 Codex app-server MCP 서버 상태를 나열합니다.
  • /codex skills는 Codex app-server skills를 나열합니다.

/codex resume은 일반 턴에 대해 harness가 사용하는 것과 동일한 사이드카 바인딩 파일을 작성합니다. 다음 메시지에서 OpenClaw는 해당 Codex thread를 재개하고, 현재 선택된 OpenClaw 모델을 app-server에 전달하며, extended history를 활성화된 상태로 유지합니다.

명령 표면은 Codex app-server 0.118.0 이상이 필요합니다. 향후 또는 커스텀 app-server가 해당 JSON-RPC 메서드를 노출하지 않으면 개별 제어 메서드는 unsupported by this Codex app-server로 보고됩니다.

훅 경계(Hook boundaries) ​

Codex harness에는 세 가지 훅 계층이 있습니다:

LayerOwner목적
OpenClaw 플러그인 훅OpenClawPI와 Codex harness 간의 제품/플러그인 호환성.
Codex app-server 확장 미들웨어OpenClaw 번들 플러그인OpenClaw 동적 도구 주변의 turn별 adapter 동작.
Codex 네이티브 훅CodexCodex config의 저수준 Codex 생명주기 및 네이티브 도구 정책.

OpenClaw는 OpenClaw 플러그인 동작을 라우팅하기 위해 프로젝트 또는 글로벌 Codex hooks.json 파일을 사용하지 않습니다. Codex 네이티브 훅은 shell 정책, 네이티브 도구 결과 review, stop 처리, 네이티브 compaction/모델 생명주기 같은 Codex-소유 작업에는 유용하지만, OpenClaw 플러그인 API는 아닙니다.

OpenClaw 동적 도구의 경우, Codex가 호출을 요청한 후 OpenClaw가 도구를 실행하므로, OpenClaw는 harness adapter에서 자신이 소유한 플러그인 및 미들웨어 동작을 발화시킵니다. Codex-네이티브 도구의 경우, Codex가 canonical 도구 레코드를 소유합니다. OpenClaw는 선택된 이벤트를 mirror할 수 있지만, Codex가 app-server 또는 네이티브 훅 콜백을 통해 해당 작업을 노출하지 않는 한 네이티브 Codex thread를 재작성할 수 없습니다.

향후 Codex app-server 빌드가 네이티브 compaction 및 모델 생명주기 훅 이벤트를 노출하면, OpenClaw는 해당 프로토콜 지원을 버전 게이트(version-gate)하고 의미(semantics)가 정직한(honest) 경우 기존 OpenClaw 훅 계약으로 이벤트를 매핑해야 합니다. 그때까지는 OpenClaw의 before_compaction, after_compaction, llm_input, llm_output 이벤트는 adapter 수준의 관찰이며, Codex의 내부 요청 또는 compaction payload의 byte-for-byte 캡처가 아닙니다.

도구, 미디어, compaction ​

Codex harness는 저수준 임베디드 agent executor만 변경합니다.

OpenClaw는 여전히 도구 목록을 빌드하고 harness에서 동적 도구 결과를 받습니다. 텍스트, 이미지, 비디오, 음악, TTS, 승인, messaging-tool 출력은 계속 일반 OpenClaw 전달 경로를 통해 진행됩니다.

Codex MCP 도구 승인 elicitation은 Codex가 _meta.codex_approval_kind를 "mcp_tool_call"로 표시할 때 OpenClaw의 플러그인 승인 흐름을 통해 라우팅됩니다. Codex request_user_input 프롬프트는 원래 채팅으로 되돌려 보내지며, 다음 큐에 대기 중인 follow-up 메시지가 추가 컨텍스트로 steering되는 대신 해당 네이티브 서버 요청에 답합니다. 다른 MCP elicitation 요청은 여전히 fail-closed 처리됩니다.

선택된 모델이 Codex harness를 사용할 때, 네이티브 thread compaction은 Codex app-server에 위임됩니다. OpenClaw는 채널 히스토리, 검색, /new, /reset, 향후 모델 또는 harness 전환을 위해 transcript mirror를 유지합니다. mirror에는 사용자 프롬프트, 최종 assistant 텍스트, app-server가 emit할 때 경량(lightweight) Codex reasoning 또는 plan 레코드가 포함됩니다. 오늘날 OpenClaw는 네이티브 compaction 시작 및 완료 신호만 기록합니다. 아직 사람이 읽을 수 있는 compaction 요약이나 compaction 후 Codex가 유지한 항목의 감사 가능한(auditable) 목록을 노출하지 않습니다.

Codex가 canonical 네이티브 thread를 소유하기 때문에, tool_result_persist는 현재 Codex-네이티브 도구 결과 레코드를 재작성하지 않습니다. OpenClaw가 OpenClaw-소유 세션 transcript 도구 결과를 쓸 때만 적용됩니다.

미디어 생성은 PI를 필요로 하지 않습니다. 이미지, 비디오, 음악, PDF, TTS 및 미디어 이해는 agents.defaults.imageGenerationModel, videoGenerationModel, pdfModel, messages.tts 같은 일치하는 provider/모델 설정을 계속 사용합니다.

문제 해결 ​

/model에 Codex가 나타나지 않음: plugins.entries.codex.enabled를 활성화하고, embeddedHarness.runtime: "codex"가 있는 openai/gpt-* 모델(또는 레거시 codex/* 참조)을 선택하며, plugins.allow가 codex를 제외하는지 확인하십시오.

OpenClaw가 Codex 대신 PI를 사용함: Codex harness가 실행을 claim하지 않으면, OpenClaw는 호환성 백엔드로 PI를 사용할 수 있습니다. 테스팅 중 Codex 선택을 강제하려면 embeddedHarness.runtime: "codex"를 설정하거나, 일치하는 플러그인 harness가 없을 때 실패하도록 embeddedHarness.fallback: "none"을 설정하십시오. Codex app-server가 선택되면, 그 실패는 추가 fallback 설정 없이 바로 드러납니다.

app-server가 거부됨: app-server 핸드셰이크가 버전 0.118.0 이상을 보고하도록 Codex를 업그레이드하십시오.

모델 discovery가 느림: plugins.entries.codex.config.discovery.timeoutMs를 낮추거나 discovery를 비활성화하십시오.

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

non-Codex 모델이 PI를 사용함: embeddedHarness.runtime: "codex"를 강제하지 않는 한(또는 레거시 codex/* 참조를 선택하지 않는 한) 이는 예상된 동작입니다. 일반 openai/gpt-* 및 기타 provider 참조는 해당 provider의 일반 경로에 머뭅니다.

관련 문서 ​