컴퓨터 사용

컴퓨터 사용은 모델이 스크린샷으로 화면을 보고 클릭, 타이핑, 스크롤을 지시하는 기능입니다. GEODE의 구현은 core/tools/computer_use.py의 ComputerUseHarness 하나이며 host backend는 pyautogui 또는 macOS helper입니다. 매 동작 후 base64 JPEG 스크린샷을 돌려주어 모델이 결과를 관찰합니다.

동작 방식

LLM ── tool_use("computer", action, 좌표/텍스트) ──→ handle_computer
                                                     (core/cli/tool_handlers/single_tool.py)
                                                          │ asyncio.to_thread
                                                          ▼
                                              ComputerUseHarness._execute_sync
                                                          │ pyautogui / macOS helper
                                                          ▼
LLM ←──────── { result, action, screenshot(base64 JPEG) } ◄┘

디스패치 테이블은 프로바이더 중립입니다. 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 기준으로 좌표를 내고, 하네스가 실제 해상도로 변환합니다.

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

화면에 무엇이 있는지 알아내는 데 스크린샷이 유일한 방법은 아닙니다. 스텝마다 1280x800 JPEG(약 1.5k 토큰)를 보내고 모델이 좌표를 눈대중하는 대신, 접근성 트리나 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)가 켜져 있고 선택한 실행 경로가 준비되어 있어야 true입니다. sandbox 경로는 host pyautogui가 필요 없고, helper 경로는 설치된 helper를, python 경로는 pyautogui를 요구합니다.

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

프로바이더가 native computer surface를 지원하면 그 경로를 쓰고, ChatGPT subscription처럼 native surface를 받지 않는 backend에는 같은 하네스를 normal function tool computer_use로 노출합니다.

안전

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 전에 거부합니다.

실패 모드

다음

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