컴퓨터 사용

컴퓨터 사용은 모델이 스크린샷으로 화면을 보고 클릭, 타이핑, 스크롤을 지시하는 기능입니다. GEODE의 구현은 core/tools/computer_use.py의 ComputerUseHarness 하나이며 host backend는 pyautogui 또는 macOS helper입니다. Provider-native computer surface는 스크린샷을 해당 provider wire로 돌려주지만, normal function tool인 computer_use는 base64를 생략하고 compact observation만 반환합니다. 현재 function-tool 경로의 자동 좌표 선택인 locate는 모든 provider/source에서 사용할 수 없습니다.

동작 방식

LLM ── tool_use("computer", action, 좌표/텍스트) ──→ handle_computer
                                                     (core/tools/handlers/single_tool.py)
                                                          │ asyncio.to_thread
                                                          ▼
                                              ComputerUseHarness._execute_sync
                                                          │ pyautogui / macOS helper
                                                          ▼
native computer ←── screenshot(provider wire) ──────────┤
computer_use ←────── compact observation(base64 omitted) ◄┘

디스패치 테이블은 프로바이더 중립입니다. Anthropic 어휘 (left_click, triple_click, cursor_position)와 OpenAI 어휘 (keypress)를 같은 핸들러로 받습니다. 지원 동작은 screenshot, click, double_click, type, key, scroll, move, drag, wait와 클릭 변형들입니다. 지원하지 않는 action은 실행 전에 오류로 돌아갑니다.

좌표는 1280×800 스크린샷 공간과 실제 화면 사이를 양방향 스케일링합니다. 기존 Anthropic 도구는 display 필드로 크기를 선언하고, Opus 5.5의 computer_toolset_20260801은 스크린샷에서 크기를 읽습니다. 도구 결과에도 toolset 식별자를 보존합니다.

새 toolset은 순차 호출을 요청합니다. 구현되지 않은 zoom, hold_key, left_mouse_down, left_mouse_up은 노출하지 않습니다. 좌표·키·대기 시간은 실행 전에 검증하고, 생략된 클릭 좌표는 관측한 커서 위치를 사용합니다. 예상하지 못한 복수 동작 응답은 실행을 차단하되 사용량과 실패 원인을 기록합니다. 프로토콜 회귀 검사는 실제 데스크톱 조작 성공을 뜻하지 않습니다.

구조를 먼저 읽고, 스크린샷은 나중에

접근성 트리나 DOM처럼 구조가 있는 표면은 텍스트로 더 싸고 정확하게 읽힙니다. GEODE는 이 두 표면을 각각 도구로 노출합니다.

• ui_probe(core/tools/ui_probe.py). macOS 접근성(AX) 트리를 role, title, value, 사각형 텍스트로 반환합니다. 여기서 AX는 Apple의 접근성(Accessibility) 프레임워크(AXUIElement 등 AX 접두어 API)를 가리킵니다. 네이티브 macOS 앱에서 스크린샷보다 저렴하고 신뢰도 높은 첫 단계입니다. 소프트 의존 pyobjc([desktop] extra), OS 접근성 권한이 필요합니다. AX 판독은 라이브 검증됨 (2026-07-04). AX 좌표에서 클릭 좌표로의 매핑 캘리브레이션은 아직 미검증이며 사각형은 coord_space=ax_points로 표기됩니다.
• browser_scan / browser_execute_js(core/tools/browser_tools.py). CDP로 운영자의 실제 Chrome에 붙어 로그인 세션, 쿠키, 핑거프린트를 그대로 두고 웹을 지각하고 조작합니다. 로그인 벽, SPA, CAPTCHA가 사람이 쓸 때처럼 동작합니다. web_fetch(헤드리스 GET, JS 없음)나 픽셀 클릭과 달리 브라우저 작업은 실제 DOM 판독과 JS 실행으로 처리합니다. Chrome을 --remote-debugging-port=9222로 실행하면 됩니다. CDP 라운드트립은 라이브 검증됨(2026-07-04).

먼저 접근성 트리나 DOM으로 구조를 읽고, 그것이 없거나 부족한 화면(게임, 직접 그린 캔버스)에서만 픽셀 하네스로 내려갑니다.

활성화

게이트는 is_computer_use_enabled()(core/llm/providers/anthropic.py) 하나입니다. 설정 computer_use_enabled(core/config/_settings.py)가 켜져 있고 선택한 host driver가 준비되어 있어야 true입니다. helper 경로는 설치된 helper를, python 경로는 pyautogui를 요구합니다.

[computer_use]
enabled = true
driver = "helper"
# helper_path = "/absolute/path/to/geode-computer-helper"

macOS에서는 geode setup이 helper를~/.geode/helpers/computer-use/ 아래에 빌드합니다. wheel 안의 Swift/build source는 읽기 전용이며 생성물은 설치 디렉터리에 기록하지 않습니다.

프로바이더가 native computer surface를 지원하면 그 경로를 쓰고, ChatGPT subscription처럼 native surface를 받지 않는 backend에는 같은 하네스를 normal function tool computer_use로 노출합니다. 이 경로는 다른 provider로 몰래 fallback하지 않습니다.capture는 가능하지만 locate는 활성 provider/source를 표시하는 dependency error로 중단됩니다. 미검증 GLM 자동 grounding 경로는 제거했으며, browser DOM·playwriter· ui_probe 같은 source-safe 구조 경로를 선택해야 합니다.

안전

computer는 core/agent/safety.py의 DANGEROUS_TOOLS에 속합니다. run_bash와 같은 등급으로, 대화형 세션에서는 human-in-the-loop 승인을 요구하고 서브에이전트 자동 승인 대상에서 제외됩니다. 승인 UI가 없는 DAEMON 세션은 기본 차단되며 제한된 gateway에서 [gateway] allow_computer_use = true를 명시했을 때만 executor가 두 computer-use surface의 실행을 허용합니다. 옵션이 꺼져 있으면 provider-visible schema가 있더라도 dispatch 전에 거부합니다. unrestricted Petri audit에는 검증된 격리 경로가 없으므로 두 surface가 항상 비활성화됩니다.

실패 모드

이 경계는 2026-08-17 Slack Socket Mode 실환경 검증에서 재현됐다. Strict computer_use 캡처는 성공하고 locate는 안전하게 중단됐으며, 별도 browser DOM case는 Example Domain을 확인했다. 공개 영수증은 두 경로를 구분한다.

다음

• 도구와 툴셋. 도구 레지스트리와 승인 흐름.
• 정책과 라이프사이클. DANGEROUS 분류가 사는 곳.