Claude Codex Computer Use

실험적이고 비공식적인 브리지로, Claude Code가 기존 OpenAI Computer Use 설치를 통해 로컬 macOS 애플리케이션을 제어할 수 있게 해줍니다.

이 패키지에는 OpenAI 바이너리가 포함되어 있지 않습니다. 사용자의 Mac에 이미 설치된 Computer Use 클라이언트를 시작하고, Claude Code와 해당 클라이언트 간의 작은 MCP 호환성 격차를 해소합니다.

요구 사항

• macOS. 설치된 OpenAI 런타임은 현재 macOS 14.4 이상을 요구합니다.

• 플러그인 지원이 있는 Claude Code. 버전 2.1.223이 확인되었습니다.

• ChatGPT 또는 Codex에 OpenAI Computer Use가 설치되어 작동 중이어야 함.

• OpenAI Computer Use 런타임에 대한 접근성 및 화면 녹화 권한이 부여되어 있어야 함.

브리지는 다음 경로에서 Computer Use 클라이언트를 찾습니다:

$CODEX_HOME/computer-use/Codex Computer Use.app/Contents/SharedSupport/
SkyComputerUseClient.app/Contents/MacOS/SkyComputerUseClient

CODEX_HOME이 설정되지 않은 경우 기본값은 ~/.codex입니다.

Related MCP server: mlx-mcp-server

Claude Code 플러그인으로 설치

Claude Code 세션에서:

/plugin marketplace add songkeys/claude-codex-computer-use
/plugin install claude-codex-computer-use@songkeys

또는 셸에서:

claude plugin marketplace add songkeys/claude-codex-computer-use
claude plugin install claude-codex-computer-use@songkeys

새 세션은 Computer Use Skill과 MCP 서버를 자동으로 로드합니다.

설치를 확인하려면:

/plugin
/mcp

npm에서 MCP 브리지 설치

플러그인 설치가 권장됩니다. MCP 브리지와 Computer Use Skill이 모두 포함되어 있기 때문입니다. npm 패키지는 독립형 stdio MCP 서버로도 사용할 수 있습니다:

claude mcp add computer-use -- npx -y claude-codex-computer-use@latest

또는 직접 .mcp.json 항목으로:

{
  "mcpServers": {
    "computer-use": {
      "command": "npx",
      "args": ["-y", "claude-codex-computer-use@latest"]
    }
  }
}

이 MCP 전용 설치는 번들 Skill을 로드하지 않습니다. MCP 클라이언트가 자체 Computer Use 지침을 제공하지 않는 한 플러그인을 선호하세요.

사용법

Claude에게 Computer Use를 명시적으로 사용하도록 요청하거나, 데스크톱 작업을 설명하세요:

Use Computer Use to inspect Calculator and enter 42.

Open System Settings with Computer Use and tell me what page is visible.

번들 Skill은 Claude에게 관찰 가능한 상태/동작/상태 루프를 사용하도록 지시합니다:

1. get_app_state로 대상 앱을 읽습니다.

2. 접근성 요소를 사용할 수 있으면 사용하고, 스크린샷 좌표는 대체 수단으로만 사용합니다.

3. 동작을 수행합니다.

4. 다음 동작을 결정하기 전에 새로운 앱 상태를 가져옵니다.

작동 방식

OpenAI Computer Use 서비스는 클라이언트 프로세스의 계보를 인증합니다. MCP 클라이언트를 Claude Code에서 직접 실행하면 인증되지 않은 발신자로 거부됩니다. 따라서 브리지는 ChatGPT 또는 Codex에 번들된 서명된 Codex 실행 파일을 프로세스 실행기로 사용합니다:

Claude Code
  -> claude-codex-computer-use bridge
  -> signed Codex launcher
  -> OpenAI Computer Use MCP client
  -> OpenAI Computer Use service

Codex는 에이전트로 사용되지 않으며 브리지에서 OpenAI 모델 요청을 하지 않습니다. 서명된 클라이언트가 일반 캐시, macOS 서비스 및 Unix 소켓에 접근할 수 있도록 Codex의 비활성화/제한 없음 권한 프로필로 codex sandbox를 실행합니다.

Computer Use 클라이언트는 MCP 클라이언트가 elicitation 기능을 광고하도록 요구하며, 이를 통해 앱 접근 승인을 응답합니다. 브리지는 initialize 시 해당 기능이 존재함을 보장하고 앱 접근 elicitation을 자동으로 수락하여 세션이 무인으로 작동하도록 합니다. 스크린샷 이미지 블록을 포함한 다른 모든 JSON-RPC 메시지는 변경 없이 통과됩니다.

Computer Use 서비스는 연결된 클라이언트를 제어되는 애플리케이션에 대한 활성 보류로 취급하며, 클라이언트가 종료되면 해제합니다. Codex는 대화가 끝나면 클라이언트를 종료하지만, Claude Code는 플러그인 MCP 서버를 세션 전체 동안 유지합니다. 따라서 브리지는 60초 동안 트래픽이 없으면 클라이언트를 종료하고 필요 시 다시 시작하며, 기록된 initialize 핸드셰이크를 투명하게 재생하여 작업 간에 앱이 유지되지 않도록 합니다.

서비스는 또한 사용자 시작 중지(오버레이의 Esc 취소)를 클라이언트의 현재 "턴"으로 범위를 지정하는데, 이는 장기 클라이언트의 경우 종료되지 않습니다. 도구 결과가 앱 세션이 사용자에 의해 중지되었음을 보고하면, 브리지는 클라이언트를 재활용하여 다음 요청이 동일한 중지에 다시 부딪히지 않고 새 세션을 시작하도록 합니다.

구성

환경 변수:

서명된 실행기는 다음 순서로 검색됩니다:

1. COMPUTER_USE_CODEX_LAUNCHER_PATH

2. /Applications/ChatGPT.app/Contents/Resources/codex

3. /Applications/Codex.app/Contents/Resources/codex

보안 및 데이터 흐름

이 패키지를 설치하면 Claude가 로컬 Computer Use 도구에 접근할 수 있게 되며, 이 도구는 스크린샷을 읽고, 클릭, 입력, 스크롤, 드래그 및 애플리케이션과 상호 작용할 수 있습니다.

브리지는 의도적으로:

• Computer Use MCP 앱 접근 elicitation을 자동으로 수락합니다.

• 제한 없는 Codex 권한 프로필로 서명된 클라이언트를 실행합니다.

• 접근성 텍스트와 스크린샷을 MCP 도구 결과로 Claude에 다시 전달합니다.

• 유휴 시간 초과 후 클라이언트를 해제하여 작업 간에 애플리케이션이 유지되지 않도록 하고, 필요 시 다시 시작합니다.

Claude Code는 해당 도구 결과를 대화의 일부로 구성된 모델 제공자에게 보낼 수 있습니다. 이 동작이 Mac의 애플리케이션 및 데이터에 대해 허용 가능하지 않은 경우 플러그인을 설치하지 마십시오.

호환성

초기 릴리스는 다음에서 확인되었습니다:

OpenAI Computer Use는 안정적인 타사 SDK가 아닌 내부 데스크톱 통합입니다. ChatGPT, Codex 또는 Computer Use 업데이트로 인해 바이너리 경로, 프로세스 인증 규칙 또는 프로토콜 동작이 변경될 수 있습니다.

개발

브리지에는 런타임 npm 종속성이 없습니다.

pnpm install
pnpm test
pnpm smoke

pnpm test는 가짜 Computer Use 서버를 사용하며 어디서나 안전하게 실행할 수 있습니다. pnpm smoke는 실제 로컬 서비스에 연결하고, list_apps를 호출하며, get_app_state가 텍스트와 JPEG 스크린샷을 모두 반환하는지 확인합니다.

문제 해결

Sender process is not authenticated

Computer Use 클라이언트가 서명된 Codex 실행기를 통하지 않고 직접 시작되었습니다. /Applications에 ChatGPT 또는 Codex가 설치되어 있는지 확인하거나, COMPUTER_USE_CODEX_LAUNCHER_PATH를 설정하세요.

Computer Use 클라이언트가 없음

OpenAI Computer Use를 먼저 활성화하거나 재설치한 다음, 해당 클라이언트가 $CODEX_HOME/computer-use 아래에 있는지 확인하세요.

클라이언트와 서버 버전 불일치

ChatGPT를 종료하고 다시 시작하여 Computer Use 클라이언트와 런타임이 함께 업데이트되도록 한 후, 스모크 테스트를 다시 시도하세요.

This application session has been explicitly stopped by the user

누군가 Computer Use 오버레이에서 Esc를 눌러 현재 턴의 앱 세션을 취소했습니다. 브리지가 클라이언트를 자동으로 재활용하므로, 준비가 되면 Claude에게 계속 진행하도록 요청하세요.

ChatGPT가 여전히 Computer Use 아래에 앱을 나열함

ChatGPT의 Computer Use 메뉴는 브리지가 클라이언트를 해제한 후에도 앱을 계속 표시할 수 있습니다("Stop Using …" 동작 포함). 서비스는 후속 턴이 새로운 승인 없이 재개될 수 있도록 앱 세션 기록을 유지하며, Codex 자체의 턴 추적만이 이를 닫습니다. 외부 클라이언트는 해당 신호를 보낼 지원되는 방법이 없습니다. 기록은 부기일 뿐입니다: 제어하는 클라이언트 프로세스는 사라졌으며 새 브리지 세션에는 영향을 미치지 않습니다. ChatGPT의 "Stop Using …" 동작으로 지우거나 ChatGPT를 종료하여 지우세요.

SkyComputerUseClient computer-history 프로세스가 남아 있음

이것들은 ChatGPT 자체의 기록/녹화 도우미로, Computer Use가 사용될 때마다 codex app-server 데몬에 의해 생성되고 이후에도 유지됩니다. 유휴 상태이며, 어떤 애플리케이션도 제어하지 않으며, 이 브리지에 의해 관리되지 않습니다. 브리지가 관리하는 클라이언트는 일반 mcp 인수로 실행되며 유휴 해제 시 종료됩니다. 도우미는 ChatGPT가 종료될 때 종료됩니다.

errAETimeout: the AppleEvent timed out

Computer Use 서비스가 대상 애플리케이션에 제때 도달할 수 없습니다. 호출이 몇 분 동안 차단될 수 있습니다. 한 번 재시도하십시오. 지속되면 대상 애플리케이션을 종료하고 다시 시작하고, 마지막 수단으로 ChatGPT를 종료하고 다시 시작하여 Computer Use 서비스가 다시 시작되도록 하십시오.

플러그인 변경 사항이 나타나지 않음

Claude Code를 다시 시작하거나 /plugin marketplace update songkeys를 실행하고 재설치하십시오. Claude Code는 설치된 플러그인의 캐시된 복사본을 실행하므로, 체크아웃을 편집해도 플러그인이 업데이트될 때까지 기존 설치에 영향을 미치지 않습니다.

라이선스 및 상표

브리지 코드는 MIT 라이선스에 따라 사용 가능합니다.

이 프로젝트는 독립적이며 OpenAI 또는 Anthropic과 제휴, 보증 또는 후원을 받지 않습니다. OpenAI, ChatGPT, Codex, Anthropic, Claude 및 관련 이름은 해당 소유자의 상표일 수 있습니다. 사용자는 자신의 OpenAI 및 Anthropic 소프트웨어와 계정을 공급받고 사용할 수 있는 라이선스를 보유해야 합니다.

선행 기술

이 프로젝트는 Kimi Code CLI용 동일한 브리지인 kimi-computer-use를 미러링합니다.