​

도구 (OpenClaw)

​

도구 비활성화

{
  tools: { deny: ["browser"] },
}

• 매칭은 대소문자를 구분하지 않습니다.
• * 와일드카드를 지원합니다 ("*" 는 모든 도구를 의미합니다).
• tools.allow 가 알 수 없거나 로드되지 않은 플러그인 도구 이름만 참조하는 경우, OpenClaw 는 경고를 로그에 기록하고 allowlist 를 무시하여 핵심 도구가 계속 사용 가능하도록 합니다.

​

도구 프로필 (기본 allowlist)

• minimal: session_status 만
• coding: group:fs, group:runtime, group:sessions, group:memory, image
• messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
• full: 제한 없음 (미설정과 동일)

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],
  },
}

{
  tools: { profile: "coding" },
  agents: {
    list: [
      {
        id: "support",
        tools: { profile: "messaging", allow: ["slack"] },
      },
    ],
  },
}

​

프로바이더별 도구 정책

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

{
  agents: {
    list: [
      {
        id: "support",
        tools: {
          byProvider: {
            "google-antigravity": { allow: ["message", "sessions_list"] },
          },
        },
      },
    ],
  },
}

​

도구 그룹 (단축 표기)

• group:runtime: exec, bash, process
• group:fs: read, write, edit, apply_patch
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• group:memory: memory_search, memory_get
• group:web: web_search, web_fetch
• group:ui: browser, canvas
• group:automation: cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:openclaw: 모든 내장 OpenClaw 도구 (프로바이더 플러그인 제외)

{
  tools: {
    allow: ["group:fs", "browser"],
  },
}

​

플러그인 + 도구

• Lobster: 재개 가능한 승인 기능을 갖춘 타입드 워크플로 런타임 (게이트웨이 호스트에 Lobster CLI 필요).
• LLM Task: 구조화된 워크플로 출력을 위한 JSON 전용 LLM 단계 (선택적 스키마 검증).

​

도구 인벤토리

​

apply_patch

​

exec

• command (필수)
• yieldMs (타임아웃 후 자동 백그라운드, 기본값 10000)
• background (즉시 백그라운드)
• timeout (초; 초과 시 프로세스 종료, 기본값 1800)
• elevated (bool; 상승 모드가 활성화/허용된 경우 호스트에서 실행; 에이전트가 샌드박스화된 경우에만 동작 변경)
• host (sandbox | gateway | node)
• security (deny | allowlist | full)
• ask (off | on-miss | always)
• node (host=node 용 노드 id/name)
• 실제 TTY 가 필요한가요? pty: true 를 설정하십시오.

• 백그라운드로 전환되면 sessionId 가 포함된 status: "running" 를 반환합니다.
• 백그라운드 세션을 폴링/로그/쓰기/종료/정리하려면 process 를 사용하십시오.
• process 이 허용되지 않으면, exec 는 동기적으로 실행되며 yieldMs/background 를 무시합니다.
• elevated 는 tools.elevated 와 모든 agents.list[].tools.elevated 재정의에 의해 게이트되며 (둘 다 허용되어야 함), host=gateway + security=full 의 별칭입니다.
• elevated 는 에이전트가 샌드박스화된 경우에만 동작을 변경합니다 (그 외에는 no-op).
• host=node 는 macOS 컴패니언 앱 또는 헤드리스 노드 호스트 (openclaw node run) 를 대상으로 할 수 있습니다.
• 게이트웨이/노드 승인 및 allowlist: Exec approvals.

​

process

• list, poll, log, write, kill, clear, remove

• poll 는 완료 시 새 출력과 종료 상태를 반환합니다.
• log 는 라인 기반 offset/limit 를 지원합니다 (offset 를 생략하면 마지막 N 줄을 가져옵니다).
• process 는 에이전트별 범위로 제한되며, 다른 에이전트의 세션은 보이지 않습니다.

​

web_search

• query (필수)
• count (1–10; 기본값은 tools.web.search.maxResults)

• Brave API 키가 필요합니다 (권장: openclaw configure --section web, 또는 BRAVE_API_KEY 설정).
• tools.web.search.enabled 를 통해 활성화하십시오.
• 응답은 캐시됩니다 (기본 15 분).
• 설정은 Web tools 를 참고하십시오.

​

web_fetch

• url (필수)
• extractMode (markdown | text)
• maxChars (긴 페이지 자르기)

• tools.web.fetch.enabled 를 통해 활성화하십시오.
• maxChars 는 tools.web.fetch.maxCharsCap (기본값 50000) 로 제한됩니다.
• 응답은 캐시됩니다 (기본 15 분).
• JS 비중이 큰 사이트의 경우 browser 도구를 선호하십시오.
• 설정은 Web tools 를 참고하십시오.
• 선택적 안티봇 대체 수단은 Firecrawl 을 참고하십시오.

​

browser

• status, start, stop, tabs, open, focus, close
• snapshot (aria/ai)
• screenshot (이미지 블록 + MEDIA:<path> 반환)
• act (UI 액션: click/type/press/hover/drag/select/fill/resize/wait/evaluate)
• navigate, console, pdf, upload, dialog

• profiles — 상태와 함께 모든 browser 프로필 나열
• create-profile — 자동 할당 포트로 새 프로필 생성 (또는 cdpUrl)
• delete-profile — browser 중지, 사용자 데이터 삭제, 구성에서 제거 (로컬 전용)
• reset-profile — 프로필 포트의 고아 프로세스 종료 (로컬 전용)

• profile (선택; 기본값 browser.defaultProfile)
• target (sandbox | host | node)
• node (선택; 특정 노드 id/name 지정) 참고:
• browser.enabled=true 가 필요합니다 (기본값은 true; 비활성화하려면 false 설정).
• 모든 액션은 다중 인스턴스 지원을 위해 선택적 profile 파라미터를 허용합니다.
• profile 가 생략되면 browser.defaultProfile (기본값 “chrome”) 을 사용합니다.
• 프로필 이름: 소문자 영숫자 + 하이픈만 허용 (최대 64 자).
• 포트 범위: 18800-18899 (최대 약 100 개 프로필).
• 원격 프로필은 attach 전용입니다 (start/stop/reset 불가).
• browser 가능 노드가 연결되어 있으면, 도구가 자동으로 라우팅할 수 있습니다 (target 를 고정하지 않는 한).
• Playwright 가 설치된 경우 snapshot 는 기본적으로 ai 를 사용합니다; 접근성 트리는 aria 를 사용하십시오.
• snapshot 는 역할 스냅샷 옵션 (interactive, compact, depth, selector) 도 지원하며, e12 와 같은 참조를 반환합니다.
• act 는 snapshot 의 ref 가 필요합니다 (AI 스냅샷의 숫자 12 또는 역할 스냅샷의 e12); 드문 CSS 셀렉터 요구에는 evaluate 를 사용하십시오.
• 기본적으로 act → wait 는 피하십시오; 신뢰할 수 있는 UI 상태를 기다릴 수 없는 예외적 경우에만 사용하십시오.
• upload 는 준비 후 자동 클릭을 위해 선택적으로 ref 를 전달할 수 있습니다.
• upload 는 <input type="file"> 를 직접 설정하기 위해 inputRef (aria ref) 또는 element (CSS 셀렉터) 도 지원합니다.

​

canvas

• present, hide, navigate, eval
• snapshot (이미지 블록 + MEDIA:<path> 반환)
• a2ui_push, a2ui_reset

• 내부적으로 게이트웨이 node.invoke 를 사용합니다.
• node 가 제공되지 않으면, 도구가 기본값 (단일 연결 노드 또는 로컬 mac 노드) 을 선택합니다.
• A2UI 는 v0.8 전용입니다 (createSurface 없음); CLI 는 v0.9 JSONL 을 라인 오류로 거부합니다.
• 빠른 스모크 테스트: openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI".

​

nodes

• status, describe
• pending, approve, reject (페어링)
• notify (macOS system.notify)
• run (macOS system.run)
• camera_snap, camera_clip, screen_record
• location_get

• 카메라/화면 명령은 노드 앱이 포그라운드에 있어야 합니다.
• 이미지는 이미지 블록 + MEDIA:<path> 를 반환합니다.
• 비디오는 FILE:<path> (mp4) 를 반환합니다.
• 위치는 JSON 페이로드 (lat/lon/accuracy/timestamp) 를 반환합니다.
• run 파라미터: command argv 배열; 선택적 cwd, env (KEY=VAL), commandTimeoutMs, invokeTimeoutMs, needsScreenRecording.

{
  "action": "run",
  "node": "office-mac",
  "command": ["echo", "Hello"],
  "env": ["FOO=bar"],
  "commandTimeoutMs": 12000,
  "invokeTimeoutMs": 45000,
  "needsScreenRecording": false
}

​

image

• image (필수 경로 또는 URL)
• prompt (선택; 기본값 “Describe the image.”)
• model (선택적 재정의)
• maxBytesMb (선택적 크기 제한)

• agents.defaults.imageModel 가 구성된 경우 (기본 또는 폴백), 또는 기본 모델 + 구성된 인증에서 암시적 이미지 모델을 추론할 수 있는 경우에만 사용 가능합니다 (best-effort 페어링).
• 메인 채팅 모델과 독립적으로 이미지 모델을 직접 사용합니다.

​

message

• send (텍스트 + 선택적 미디어; MS Teams 는 Adaptive Cards 용 card 도 지원)
• poll (WhatsApp/Discord/MS Teams 설문)
• react / reactions / read / edit / delete
• pin / unpin / list-pins
• permissions
• thread-create / thread-list / thread-reply
• search
• sticker
• member-info / role-info
• emoji-list / emoji-upload / sticker-upload
• role-add / role-remove
• channel-info / channel-list
• voice-status
• event-list / event-create
• timeout / kick / ban

• send 는 WhatsApp 을 Gateway(게이트웨이) 를 통해 라우팅하며, 다른 채널은 직접 전송합니다.
• poll 는 WhatsApp 과 MS Teams 에 Gateway(게이트웨이) 를 사용하며, Discord 설문은 직접 전송됩니다.
• 메시지 도구 호출이 활성 채팅 세션에 바인딩된 경우, 컨텍스트 간 누출을 방지하기 위해 해당 세션의 대상에만 전송이 제한됩니다.

​

cron

• status, list
• add, update, remove, run, runs
• wake (시스템 이벤트 큐잉 + 선택적 즉시 하트비트)

• add 는 전체 cron 작업 객체를 기대합니다 (cron.add RPC 와 동일한 스키마).
• update 는 { jobId, patch } 를 사용합니다 (호환성을 위해 id 허용).

​

gateway

• restart (권한 부여 + 인프로세스 재시작을 위한 SIGUSR1 전송; openclaw gateway 는 인플레이스 재시작)
• config.get / config.schema
• config.apply (구성 검증 + 기록 + 재시작 + 웨이크)
• config.patch (부분 업데이트 병합 + 재시작 + 웨이크)
• update.run (업데이트 실행 + 재시작 + 웨이크)

• 진행 중인 응답을 중단하지 않으려면 delayMs (기본값 2000) 을 사용하십시오.
• restart 는 기본적으로 비활성화되어 있으며, commands.restart: true 로 활성화합니다.

​

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

• sessions_list: kinds?, limit?, activeMinutes?, messageLimit? (0 = 없음)
• sessions_history: sessionKey (또는 sessionId), limit?, includeTools?
• sessions_send: sessionKey (또는 sessionId), message, timeoutSeconds? (0 = fire-and-forget)
• sessions_spawn: task, label?, agentId?, model?, runTimeoutSeconds?, cleanup?
• session_status: sessionKey? (기본값 current; sessionId 허용), model? (default 는 재정의 해제)

• main 는 표준 direct-chat 키이며, global/unknown 은 숨겨집니다.
• messageLimit > 0 는 세션별 마지막 N 개 메시지를 가져옵니다 (도구 메시지는 필터링됨).
• sessions_send 는 timeoutSeconds > 0 인 경우 최종 완료를 대기합니다.
• 전달/공지(announce) 는 완료 후 best-effort 로 수행됩니다; status: "ok" 는 공지가 전달되었음을 보장하지 않고 에이전트 실행이 완료되었음을 확인합니다.
• sessions_spawn 는 서브 에이전트 실행을 시작하고 요청자 채팅으로 공지 응답을 게시합니다.
• sessions_spawn 는 논블로킹이며 즉시 status: "accepted" 를 반환합니다.
• sessions_send 는 응답 핑퐁을 실행합니다 (중단하려면 REPLY_SKIP 로 응답; 최대 턴은 session.agentToAgent.maxPingPongTurns, 0–5).
• 핑퐁 이후 대상 에이전트는 공지 단계 를 실행합니다; 공지를 억제하려면 ANNOUNCE_SKIP 로 응답하십시오.

​

agents_list

• 결과는 에이전트별 allowlist (agents.list[].subagents.allowAgents) 로 제한됩니다.
• ["*"] 가 구성된 경우, 도구는 모든 구성된 에이전트를 포함하고 allowAny: true 를 표시합니다.

​

파라미터 (공통)

• gatewayUrl (기본값 ws://127.0.0.1:18789)
• gatewayToken (인증이 활성화된 경우)
• timeoutMs

• profile (선택; 기본값 browser.defaultProfile)
• target (sandbox | host | node)
• node (선택; 특정 노드 id/name 고정)

​

권장 에이전트 플로우

1. browser → status / start
2. snapshot (ai 또는 aria)
3. act (click/type/press)
4. 시각적 확인이 필요하면 screenshot

1. canvas → present
2. a2ui_push (선택)
3. snapshot

1. nodes → status
2. 선택한 노드에서 describe
3. notify / run / camera_snap / screen_record

​

안전

• 직접적인 system.run 는 피하고, 명시적인 사용자 동의가 있을 때만 nodes → run 를 사용하십시오.
• 카메라/화면 캡처에 대한 사용자 동의를 준수하십시오.
• 미디어 명령을 호출하기 전에 권한을 확인하려면 status/describe 를 사용하십시오.

​

도구가 에이전트에 제시되는 방식

1. 시스템 프롬프트 텍스트: 사람이 읽을 수 있는 목록 + 가이던스.
2. 도구 스키마: 모델 API 로 전송되는 구조화된 함수 정의.