--- read_when: - Codex 모드 OpenClaw 에이전트가 Codex Computer Use를 사용하게 하려는 경우 - Codex Computer Use, PeekabooBridge, 직접 cua-driver MCP 중에서 결정하고 있습니다 - Codex Computer Use와 직접 cua-driver MCP 설정 중에서 선택하고 있습니다 - 번들 Codex Plugin의 computerUse를 구성하고 있습니다 - /codex computer-use 상태 또는 설치 문제를 해결하고 있습니다 summary: Codex 모드 OpenClaw 에이전트를 위한 Codex Computer Use 설정 title: Codex 컴퓨터 사용 x-i18n: generated_at: "2026-05-10T19:42:07Z" model: gpt-5.5 provider: openai source_hash: 5e1637ad13a96324aebbf97fb179b8c846b27541e917fd56e586c75e79eea7bb source_path: plugins/codex-computer-use.md workflow: 16 --- Computer Use는 로컬 데스크톱 제어를 위한 Codex 네이티브 MCP Plugin입니다. OpenClaw는 데스크톱 앱을 벤더링하지 않고, 데스크톱 동작을 직접 실행하지 않으며, Codex 권한을 우회하지 않습니다. 번들된 `codex` Plugin은 Codex app-server만 준비합니다. Codex Plugin 지원을 활성화하고, 구성된 Codex Computer Use Plugin을 찾거나 설치하며, `computer-use` MCP 서버를 사용할 수 있는지 확인한 다음, Codex 모드 턴 중에는 Codex가 네이티브 MCP 도구 호출을 소유하도록 합니다. OpenClaw가 이미 네이티브 Codex 하네스를 사용하고 있을 때 이 페이지를 사용하세요. 런타임 설정 자체는 [Codex 하네스](/ko/plugins/codex-harness)를 참조하세요. ## OpenClaw.app 및 Peekaboo OpenClaw.app의 Peekaboo 통합은 Codex Computer Use와 별개입니다. macOS 앱은 PeekabooBridge 소켓을 호스트하여 `peekaboo` CLI가 Peekaboo 자체 자동화 도구를 위해 앱의 로컬 손쉬운 사용 및 화면 기록 권한을 재사용할 수 있게 합니다. 이 브리지는 Codex Computer Use를 설치하거나 프록시하지 않으며, Codex Computer Use는 PeekabooBridge 소켓을 통해 호출하지 않습니다. OpenClaw.app을 Peekaboo CLI 자동화를 위한 권한 인식 호스트로 사용하려면 [Peekaboo 브리지](/ko/platforms/mac/peekaboo)를 사용하세요. Codex 모드 OpenClaw 에이전트가 턴이 시작되기 전에 Codex의 네이티브 `computer-use` MCP Plugin을 사용할 수 있어야 할 때 이 페이지를 사용하세요. ## iOS 앱 iOS 앱은 Codex Computer Use와 별개입니다. 이 앱은 Codex `computer-use` MCP 서버를 설치하거나 프록시하지 않으며 데스크톱 제어 백엔드가 아닙니다. 대신 iOS 앱은 OpenClaw 노드로 연결되고 `canvas.*`, `camera.*`, `screen.*`, `location.*`, `talk.*` 같은 노드 명령을 통해 모바일 기능을 노출합니다. 에이전트가 Gateway를 통해 iPhone 노드를 구동하게 하려면 [iOS](/ko/platforms/ios)를 사용하세요. Codex 모드 에이전트가 Codex의 네이티브 Computer Use Plugin을 통해 로컬 macOS 데스크톱을 제어해야 할 때 이 페이지를 사용하세요. ## 직접 cua-driver MCP Codex Computer Use만 데스크톱 제어를 노출하는 방법은 아닙니다. OpenClaw 관리 런타임이 TryCua의 드라이버를 직접 호출하게 하려면 Codex 전용 마켓플레이스 흐름 대신 OpenClaw의 MCP 레지스트리를 통해 업스트림 `cua-driver mcp` 서버를 사용하세요. `cua-driver`를 설치한 후, OpenClaw 명령을 요청하거나 다음을 실행합니다. ```bash cua-driver mcp-config --client openclaw ``` 또는 stdio 서버를 직접 등록합니다. ```bash openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}' ``` 이 경로는 드라이버 스키마와 구조화된 MCP 응답을 포함해 업스트림 MCP 도구 표면을 그대로 유지합니다. CUA 드라이버를 일반 OpenClaw MCP 서버로 사용할 수 있게 하려면 이 경로를 사용하세요. Codex app-server가 Codex 모드 턴 안에서 Plugin 설치, MCP 다시 로드, 네이티브 도구 호출을 소유해야 할 때는 이 페이지의 Codex Computer Use 설정을 사용하세요. CUA의 드라이버는 macOS 전용이며, 손쉬운 사용 및 화면 기록처럼 해당 앱이 요청하는 로컬 macOS 권한이 여전히 필요합니다. OpenClaw는 `cua-driver`를 설치하거나, 해당 권한을 부여하거나, 업스트림 드라이버의 안전 모델을 우회하지 않습니다. ## 빠른 설정 Codex 모드 턴에서 스레드가 시작되기 전에 Computer Use를 사용할 수 있어야 하면 `plugins.entries.codex.config.computerUse`를 설정하세요. ```json5 { plugins: { entries: { codex: { enabled: true, config: { computerUse: { autoInstall: true, }, }, }, }, }, agents: { defaults: { model: "openai/gpt-5.5", }, }, } ``` 이 구성으로 OpenClaw는 각 Codex 모드 턴 전에 Codex app-server를 확인합니다. Computer Use가 없지만 Codex app-server가 설치 가능한 마켓플레이스를 이미 발견한 경우, OpenClaw는 Codex app-server에 Plugin을 설치하거나 다시 활성화하고 MCP 서버를 다시 로드하도록 요청합니다. macOS에서는 일치하는 마켓플레이스가 등록되어 있지 않고 표준 Codex 앱 번들이 존재하는 경우, OpenClaw가 실패하기 전에 `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`에서 번들된 Codex 마켓플레이스를 등록하려고도 시도합니다. 설정으로도 MCP 서버를 사용할 수 없게 만들 수 없으면 스레드가 시작되기 전에 턴이 실패합니다. Computer Use 구성을 변경한 후 기존 Codex 스레드가 이미 시작된 경우, 테스트하기 전에 영향을 받는 채팅에서 `/new` 또는 `/reset`을 사용하세요. ## 명령 `codex` Plugin 명령 표면을 사용할 수 있는 모든 채팅 표면에서 `/codex computer-use` 명령을 사용하세요. 이들은 OpenClaw 채팅/런타임 명령이며 `openclaw codex ...` CLI 하위 명령이 아닙니다. ```text /codex computer-use status /codex computer-use install /codex computer-use install --source /codex computer-use install --marketplace-path /codex computer-use install --marketplace ``` `status`는 읽기 전용입니다. 마켓플레이스 소스를 추가하거나, Plugin을 설치하거나, Codex Plugin 지원을 활성화하지 않습니다. `install`은 Codex app-server Plugin 지원을 활성화하고, 선택적으로 구성된 마켓플레이스 소스를 추가하며, Codex app-server를 통해 구성된 Plugin을 설치하거나 다시 활성화하고, MCP 서버를 다시 로드하며, MCP 서버가 도구를 노출하는지 확인합니다. ## 마켓플레이스 선택 OpenClaw는 Codex 자체가 노출하는 것과 동일한 app-server API를 사용합니다. 마켓플레이스 필드는 Codex가 `computer-use`를 어디에서 찾아야 하는지 선택합니다. | 필드 | 사용 시점 | 설치 지원 | | -------------------- | --------------------------------------------------------------- | -------------------------------------------------------- | | 마켓플레이스 필드 없음 | Codex app-server가 이미 아는 마켓플레이스를 사용하게 하려는 경우. | 예, app-server가 로컬 마켓플레이스를 반환할 때. | | `marketplaceSource` | Codex app-server가 추가할 수 있는 Codex 마켓플레이스 소스가 있는 경우. | 예, 명시적 `/codex computer-use install`에 대해. | | `marketplacePath` | 호스트의 로컬 마켓플레이스 파일 경로를 이미 알고 있는 경우. | 예, 명시적 설치 및 턴 시작 자동 설치에 대해. | | `marketplaceName` | 이름으로 이미 등록된 마켓플레이스 하나를 선택하려는 경우. | 선택한 마켓플레이스에 로컬 경로가 있을 때만 예. | 새 Codex 홈은 공식 마켓플레이스를 시드하는 데 짧은 시간이 필요할 수 있습니다. 설치 중 OpenClaw는 최대 `marketplaceDiscoveryTimeoutMs` 밀리초 동안 `plugin/list`를 폴링합니다. 기본값은 60초입니다. 알려진 마켓플레이스 여러 개에 Computer Use가 포함되어 있으면 OpenClaw는 `openai-bundled`, 그다음 `openai-curated`, 그다음 `local`을 선호합니다. 알 수 없는 모호한 일치는 닫힌 상태로 실패하며 `marketplaceName` 또는 `marketplacePath`를 설정하라고 요청합니다. ## 번들된 macOS 마켓플레이스 최근 Codex 데스크톱 빌드는 여기에 Computer Use를 번들합니다. ```text /Applications/Codex.app/Contents/Resources/plugins/openai-bundled/plugins/computer-use ``` `computerUse.autoInstall`이 true이고 `computer-use`를 포함하는 마켓플레이스가 등록되어 있지 않으면, OpenClaw는 표준 번들 마켓플레이스 루트를 자동으로 추가하려고 시도합니다. ```text /Applications/Codex.app/Contents/Resources/plugins/openai-bundled ``` Codex와 함께 셸에서 명시적으로 등록할 수도 있습니다. ```bash codex plugin marketplace add /Applications/Codex.app/Contents/Resources/plugins/openai-bundled ``` 비표준 Codex 앱 경로를 사용하는 경우 `computerUse.marketplacePath`를 로컬 마켓플레이스 파일 경로로 설정하거나 `/codex computer-use install --source `를 한 번 실행하세요. ## 원격 카탈로그 제한 Codex app-server는 원격 전용 카탈로그 항목을 나열하고 읽을 수 있지만, 현재 원격 `plugin/install`은 지원하지 않습니다. 즉 `marketplaceName`은 상태 확인을 위해 원격 전용 마켓플레이스를 선택할 수 있지만, 설치 및 재활성화에는 여전히 `marketplaceSource` 또는 `marketplacePath`를 통한 로컬 마켓플레이스가 필요합니다. 상태에서 원격 Codex 마켓플레이스에서 Plugin을 사용할 수 있지만 원격 설치가 지원되지 않는다고 표시되면, 로컬 소스 또는 경로로 설치를 실행하세요. ```text /codex computer-use install --source /codex computer-use install --marketplace-path ``` ## 구성 참조 | 필드 | 기본값 | 의미 | | ------------------------------- | -------------- | ------------------------------------------------------------------------------ | | `enabled` | 추론됨 | Computer Use를 요구합니다. 다른 Computer Use 필드가 설정되면 기본값은 true입니다. | | `autoInstall` | false | 턴 시작 시 이미 발견된 마켓플레이스에서 설치하거나 다시 활성화합니다. | | `marketplaceDiscoveryTimeoutMs` | 60000 | 설치가 Codex app-server 마켓플레이스 발견을 기다리는 시간입니다. | | `marketplaceSource` | 설정되지 않음 | Codex app-server `marketplace/add`에 전달되는 소스 문자열입니다. | | `marketplacePath` | 설정되지 않음 | Plugin을 포함하는 로컬 Codex 마켓플레이스 파일 경로입니다. | | `marketplaceName` | 설정되지 않음 | 선택할 등록된 Codex 마켓플레이스 이름입니다. | | `pluginName` | `computer-use` | Codex 마켓플레이스 Plugin 이름입니다. | | `mcpServerName` | `computer-use` | 설치된 Plugin이 노출하는 MCP 서버 이름입니다. | 턴 시작 자동 설치는 구성된 `marketplaceSource` 값을 의도적으로 거부합니다. 새 소스를 추가하는 것은 명시적 설정 작업이므로 `/codex computer-use install --source `를 한 번 사용한 다음, 이후에는 발견된 로컬 마켓플레이스에서 `autoInstall`이 재활성화를 처리하게 하세요. 턴 시작 자동 설치는 구성된 `marketplacePath`를 사용할 수 있습니다. 이는 이미 호스트의 로컬 경로이기 때문입니다. ## OpenClaw가 확인하는 것 OpenClaw는 내부적으로 안정적인 설정 이유를 보고하고 채팅용 사용자 표시 상태를 형식화합니다. | 이유 | 의미 | 다음 단계 | | ---------------------------- | ------------------------------------------------------ | --------------------------------------------- | | `disabled` | `computerUse.enabled`가 false로 해석되었습니다. | `enabled` 또는 다른 Computer Use 필드를 설정하세요. | | `marketplace_missing` | 일치하는 마켓플레이스를 사용할 수 없었습니다. | 소스, 경로 또는 마켓플레이스 이름을 구성하세요. | | `plugin_not_installed` | 마켓플레이스는 있지만 Plugin이 설치되어 있지 않습니다. | 설치를 실행하거나 `autoInstall`을 활성화하세요. | | `plugin_disabled` | Plugin이 설치되어 있지만 Codex 구성에서 비활성화되어 있습니다. | 설치를 실행하여 다시 활성화하세요. | | `remote_install_unsupported` | 선택한 마켓플레이스가 원격 전용입니다. | `marketplaceSource` 또는 `marketplacePath`를 사용하세요. | | `mcp_missing` | Plugin은 활성화되어 있지만 MCP 서버를 사용할 수 없습니다. | Codex Computer Use 및 OS 권한을 확인하세요. | | `ready` | Plugin과 MCP 도구를 사용할 수 있습니다. | Codex 모드 턴을 시작하세요. | | `check_failed` | 상태 확인 중 Codex app-server 요청이 실패했습니다. | app-server 연결 및 로그를 확인하세요. | | `auto_install_blocked` | 턴 시작 설정에 새 소스 추가가 필요합니다. | 먼저 명시적 설치를 실행하세요. | 채팅 출력에는 Plugin 상태, MCP 서버 상태, 마켓플레이스, 사용 가능한 경우 도구, 그리고 실패한 설정 단계에 대한 구체적 메시지가 포함됩니다. ## macOS 권한 Computer Use는 macOS 전용입니다. Codex가 소유한 MCP 서버는 앱을 검사하거나 제어하기 전에 로컬 OS 권한이 필요할 수 있습니다. OpenClaw가 Computer Use가 설치되어 있지만 MCP 서버를 사용할 수 없다고 말하는 경우, 먼저 Codex 쪽 Computer Use 설정을 확인하세요: - Codex app-server가 데스크톱 제어가 이루어져야 하는 동일한 호스트에서 실행 중입니다. - Codex config에서 Computer Use Plugin이 활성화되어 있습니다. - `computer-use` MCP server가 Codex app-server MCP status에 표시됩니다. - macOS가 데스크톱 제어 앱에 필요한 권한을 부여했습니다. - 현재 호스트 세션이 제어 대상 데스크톱에 접근할 수 있습니다. OpenClaw는 `computerUse.enabled`가 true일 때 의도적으로 닫힌 상태로 실패합니다. Codex 모드 턴은 config에서 요구한 네이티브 데스크톱 도구 없이 조용히 진행되어서는 안 됩니다. ## 문제 해결 **Status에 설치되지 않았다고 표시됩니다.** `/codex computer-use install`을 실행하세요. marketplace가 발견되지 않으면 `--source` 또는 `--marketplace-path`를 전달하세요. **Status에 설치되었지만 비활성화되었다고 표시됩니다.** `/codex computer-use install`을 다시 실행하세요. Codex app-server install은 Plugin config를 다시 활성화된 상태로 씁니다. **Status에 원격 설치가 지원되지 않는다고 표시됩니다.** 로컬 marketplace 소스나 경로를 사용하세요. 원격 전용 catalog 항목은 검사할 수 있지만 현재 app-server API를 통해 설치할 수는 없습니다. **Status에 MCP server를 사용할 수 없다고 표시됩니다.** MCP server가 다시 로드되도록 install을 한 번 다시 실행하세요. 계속 사용할 수 없다면 Codex Computer Use 앱, Codex app-server MCP status 또는 macOS 권한을 수정하세요. **Status 또는 probe가 `computer-use.list_apps`에서 시간 초과됩니다.** Plugin과 MCP server는 존재하지만 로컬 Computer Use 브리지가 응답하지 않았습니다. Codex Computer Use를 종료하거나 재시작하고, 필요하면 Codex Desktop을 다시 실행한 뒤 새 OpenClaw 세션에서 다시 시도하세요. **Computer Use 도구에 `Native hook relay unavailable`이 표시됩니다.** Codex 네이티브 도구 hook이 로컬 브리지 또는 Gateway fallback을 통해 활성 OpenClaw 릴레이에 도달할 수 없었습니다. `/new` 또는 `/reset`으로 새 OpenClaw 세션을 시작하세요. 계속 발생하면 gateway를 재시작하여 오래된 app-server thread와 hook 등록을 제거한 뒤 다시 시도하세요. **턴 시작 자동 설치가 소스를 거부합니다.** 이는 의도된 동작입니다. 먼저 명시적으로 `/codex computer-use install --source `를 사용해 소스를 추가하세요. 그러면 이후 턴 시작 자동 설치가 발견된 로컬 marketplace를 사용할 수 있습니다. ## 관련 항목 - [Codex 하네스](/ko/plugins/codex-harness) - [Peekaboo 브리지](/ko/platforms/mac/peekaboo) - [iOS 앱](/ko/platforms/ios)