OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Nodes and media

컴퓨터 사용

컴퓨터 사용 기능을 통해 Gateway 에이전트는 페어링된 macOS 데스크톱을 보고 제어할 수 있습니다. 기존 screen.snapshot Node 명령으로 스크린샷을 캡처하고, 위험한 단일 Node 명령인 computer.act를 통해 포인터와 키보드를 조작합니다. 동작 집합은 Anthropic의 핵심 컴퓨터 사용 동작을 따르며, 선택 사항인 computer_20251124 확대/축소 기능은 노출되지 않습니다. 비전 기능을 지원하는 모델이 내장 computer 에이전트 도구를 통해 이를 제어합니다.

에이전트는 단일 통합 명령인 computer.act를 내보내며, Node가 이를 어떤 방식으로 수행하는지는 알 수 없습니다. macOS Node는 내장된 Peekaboo 서비스와 제한적인 CoreGraphics 기본 기능을 사용하여 프로세스 내에서 computer.act를 수행합니다(올바른 TCC 권한이 필요하며 추가 프로세스는 사용하지 않음). 이후 다른 플랫폼에서도 에이전트 대상 계약을 변경하지 않고 동일한 명령을 수행할 수 있습니다.

요구 사항

  • 페어링된 macOS Node(Node 모드로 실행 중인 OpenClaw macOS 앱).
  • macOS 앱 설정에서 Allow Computer Control 활성화(기본값: 꺼짐).
  • OpenClaw에 macOS Accessibility 권한(포인터/키보드 입력용)과 Screen Recording 권한(screen.snapshot용) 부여.
  • Gateway에서 computer.act 명령 활성화(위험한 명령이므로 기본적으로 비활성화됨).
  • 비전 기능을 지원하는 에이전트 모델.
  • computer를 노출하는 도구 정책. 기본 coding 프로필은 이를 노출하지 않습니다. tools.alsoAllow에 computer를 추가하세요. 샌드박스 에이전트는 tools.sandbox.tools.alsoAllow에도 추가해야 합니다.

computer 에이전트 도구

내장 computer 도구는 호출당 하나의 동작을 받습니다. 좌표는 가장 최근 스크린샷의 음수가 아닌 정수 픽셀이며, Node는 이를 디스플레이 포인트로 변환합니다. 좌표를 사용하는 동작에는 스크린샷 결과의 frameId를 그대로 포함해야 하며, 명시적인 screenIndex는 해당 프레임과 일치해야 합니다. OpenClaw는 스크린샷에서 Node가 발급한 디스플레이 식별 정보도 동작에 전달하므로, 디스플레이가 다시 연결되거나 화면 구조가 변경되면 동일한 인덱스로 조용히 대상을 변경하는 대신 안전하게 실패합니다. 이러한 검사는 추측한 토큰과 다른 프레임 또는 디스플레이에서 전달된 토큰을 거부합니다. 토큰은 최신 상태를 보장하지 않습니다. 캡처 후에도 같은 디스플레이에서 앱이 픽셀을 변경할 수 있으므로 화면이 변경되었을 가능성이 있으면 새 스크린샷을 촬영하세요.

  • 읽기: screenshot.
  • 포인터: left_click, right_click, middle_click, double_click, triple_click, mouse_move, left_click_drag(startCoordinate 사용), left_mouse_down, left_mouse_up.
  • 스크롤: scrollDirection(up|down|left|right) 및 scrollAmount(휠 틱)를 사용하는 scroll.
  • 키보드: type(텍스트), key(cmd+shift+t 또는 Return과 같은 조합), hold_key(text 조합을 duration초 동안 누름).
  • 속도 조절: wait(duration초).

클릭 및 스크롤 동작에서 보조 키는 text 필드로 전달됩니다(shift, ctrl, alt, cmd). 입력 동작 후 도구는 모델이 결과를 확인할 수 있도록 새 스크린샷을 반환합니다. 컴퓨터 기능을 지원하는 Node가 둘 이상 연결되어 있으면 node를 명시적으로 전달하세요.

스크린샷은 모델 전용으로 유지되며 채팅 채널에 자동으로 전달되지 않습니다. 화면에 표시되는 모든 콘텐츠를 신뢰할 수 없는 입력으로 취급하세요. 도구는 사용자 요청과 충돌하는 화면상의 지시를 따르지 않도록 모델에 경고합니다.

computer.act Node 명령

computer.act는 도구가 입력을 전달하는 단일 Node 명령입니다(command: "computer.act"를 사용하는 node.invoke). 이 명령의 특성은 다음과 같습니다.

  • 기본적으로 위험함: 내장된 위험 Node 명령 목록에 포함되며 명시적으로 활성화할 때까지 런타임 허용 목록에서 제외됩니다. macOS Node는 페어링 시 이를 선언하여 해당 기능을 한 번만 승인받을 수 있습니다.
  • 현재 macOS 전용: Allow Computer Control이 활성화된 macOS Node에서만 알려집니다.

읽기에는 screen.snapshot을 재사용하며 별도의 두 번째 캡처 경로는 없습니다. 공유 캡처 명령에 관한 자세한 내용은 카메라 및 화면 Node를 참조하세요.

활성화 및 사용 허용

  1. macOS 앱에서 Settings → Allow Computer Control을 활성화합니다. 그런 다음 Settings → Permissions를 열고 macOS System Settings에서 Accessibility 및 Screen Recording 권한을 부여합니다.

  2. Gateway에서 페어링 업데이트를 승인합니다(새 명령을 추가하면 다시 페어링해야 함).

  3. 비전 기능을 지원하는 에이전트에 도구를 노출합니다. 기본 coding 프로필의 경우:

    json5
    {  tools: {    alsoAllow: ["computer"],    // 샌드박스 에이전트에는 이 두 번째 게이트도 필요합니다.    sandbox: { tools: { alsoAllow: ["computer"] } },  },}

  4. 제한된 시간 동안 computer.act의 사용을 허용합니다. phone-control Plugin은 computer 그룹을 제공합니다.

    text
    /phone arm computer 30m/phone status/phone disarm

    사용 허용에는 operator.admin 권한(또는 소유자)이 필요하며 자동으로 만료됩니다. 레거시 /phone arm all 그룹은 의도적으로 데스크톱 제어를 제외하므로 명시적인 computer 그룹을 사용하세요. 사용 허용은 Gateway가 호출할 수 있는 항목만 전환합니다. macOS 앱은 계속해서 Allow Computer Control 설정과 운영 체제 권한을 적용합니다.

영구적으로 권한을 부여하려면 gateway.nodes.allowCommands에 computer.act를 추가하고 gateway.nodes.denyCommands에서는 제거하세요. 거부 목록이 우선합니다. 영구 권한은 자동으로 만료되지 않습니다. /phone arm 전에 이미 존재하던 항목은 /phone disarm 후에도 유지됩니다. 임시 권한이 활성화된 동안 영구 권한으로 전환하지 마세요.

권한 부여는 의도적으로 활성화와 사용으로 나뉩니다. computer.act의 사용을 허용하거나 영구적으로 구성하려면 관리자 권한이 필요합니다. 사용이 허용되면 operator.write 권한이 있는 인증된 운영자는 권한이 만료되거나 해제될 때까지 node.invoke를 통해 computer.act를 호출할 수 있으며, 각 동작마다 관리자 권한을 확인하지 않습니다. computer.act를 선언하는 Node를 승인하는 것은 나중에 사용을 허용할 수 있도록 해당 기능을 기록할 뿐이며, 그 자체로 호출을 활성화하지는 않습니다.

안전

  • 권한을 부여하기 전에는 모든 계층(도구 정책, Gateway 명령 정책, macOS 설정, Accessibility 및 Screen Recording)이 모두 허용해야 합니다. 사용이 허용된 후에는 만료되거나 /phone disarm이 실행될 때까지 동작별 확인 없이 작업이 실행됩니다.
  • 텍스트 입력은 문자소 단위로 하나씩 전송됩니다. 취소, 연결 해제, 일시 중지, 비활성화 또는 엔드포인트 교체가 발생하면 오래된 나머지 입력이 계속되지 않고 다음 문자소 전에 중지됩니다.
  • 스크린샷은 모델 전용이며 채팅에 자동으로 전송되지 않습니다(이슈 #44759).
  • 화면 콘텐츠는 프롬프트 인젝션을 포함할 수 있으므로 신뢰할 수 없는 것으로 취급하세요.

다른 데스크톱 제어 경로와의 관계

이 경로는 에이전트가 주도하는 경로입니다. PeekabooBridge 호스트, Codex Computer Use 및 직접 사용하는 cua-driver MCP와의 관계는 Peekaboo 브리지를 참조하세요.

Was this useful?
On this page

On this page