Claude Codex Computer Use

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

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

요구 사항

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

• 플러그인을 지원하는 Claude Code. 버전 2.1.223에서 검증되었습니다.

• OpenAI Computer Use가 설치되어 작동 중인 ChatGPT 또는 Codex.

• OpenAI Computer Use 런타임에 손쉬운 사용 및 화면 기록 권한이 부여되어 있어야 합니다.

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

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

CODEX_HOME이 설정되어 있지 않으면 기본값은 ~/.codex입니다.

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 서비스는 클라이언트 프로세스의 출처를 인증합니다. Claude Code에서 해당 MCP 클라이언트를 직접 실행하면 인증되지 않은 발신자로 거부됩니다. 따라서 브리지는 ChatGPT 또는 Codex에 번들된 서명된 Codex 실행 파일을 프로세스 실행기로 사용합니다:

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

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

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

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

구성

환경 변수:

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

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 실행기를 통하지 않고 직접 시작되었습니다. ChatGPT 또는 Codex가 /Applications에 설치되어 있는지 확인하거나 COMPUTER_USE_CODEX_LAUNCHER_PATH를 설정하세요.

Computer Use 클라이언트가 없음

먼저 OpenAI Computer Use를 활성화하거나 다시 설치한 다음 $CODEX_HOME/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를 반영합니다.