컴퓨터 사용은 모델이 스크린샷으로 화면을 보고 클릭, 타이핑, 스크롤을 지시하는 기능입니다. 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 경로의 시각적 좌표 선택은 활성 provider/source에 호환되는 grounding이 있을 때만 locate로 수행합니다.
동작 방식
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은 지원 목록과 함께 오류로 돌아갑니다.
좌표는 타깃 공간과 실제 화면 사이를 양방향 스케일링합니다. 모델은 display_width_px=1280, display_height_px=800 기준으로 좌표를 내고, 하네스가 실제 해상도로 변환합니다.
구조를 먼저 읽고, 스크린샷은 나중에
접근성 트리나 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하지 않습니다. OpenAI subscription source에 visual grounding을 별도로 구성하지 않았다면 capture는 가능하지만 locate는 dependency error로 중단되며, 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가 항상 비활성화됩니다.
실패 모드
| 증상 | 원인 | 해법 |
|---|---|---|
도구 목록에 computer가 없음 | 설정이 꺼졌거나 선택한 driver가 준비되지 않음 | computer_use_enabled와 pyautogui/helper 설치 상태를 확인합니다. |
computer_use locate가 dependency error | 활성 provider/source에 source-safe visual grounding이 없음 | 좌표를 추측하지 말고 ui_probe, browser DOM, playwriter 또는 검증된 keyboard navigation을 사용합니다. |
move가 Accessibility 오류 | OS가 입력 이벤트를 거부했거나 helper 권한이 없음 | 활성 driver/helper에 Accessibility 권한을 주고 geode doctor를 다시 실행합니다. |
| 동작이 오류로 반환 | 지원하지 않는 action 이름 | 오류 응답의 supported_actions 목록을 확인합니다. |
| 클릭 위치가 어긋남 | 타깃 공간과 화면 해상도 불일치 | 스케일링은 자동입니다. 멀티 디스플레이 구성에서는 활성 디스플레이 기준임을 감안합니다. |
이 경계는 2026-08-17 Slack Socket Mode 실환경 검증에서 재현됐다. Strict computer_use 캡처는 성공하고 locate는 안전하게 중단됐으며, 별도 browser DOM case는 Example Domain을 확인했다. 공개 영수증은 두 경로를 구분한다.
다음
- 도구와 툴셋. 도구 레지스트리와 승인 흐름.
- 정책과 라이프사이클. DANGEROUS 분류가 사는 곳.