​

Tools (OpenClaw)

​

도구 비활성화

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

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

​

도구 프로필 (기본 허용 목록)

• 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/이름)
• 실제 TTY가 필요한가요? pty: true를 설정하세요.

• 백그라운드 상태에서는 sessionId와 함께 status: "running"을 반환합니다.
• process를 사용하여 백그라운드 세션을 폴링/로그/기록/종료/삭제할 수 있습니다.
• process가 허용되지 않는 경우, exec는 동기식으로 실행하며 yieldMs/background를 무시합니다.
• elevated는 tools.elevated와 agents.list[].tools.elevated 오버라이드를 모두 허용해야 하며, host=gateway + security=full의 별칭 역할을 합니다.
• elevated는 에이전트가 샌드박스 격리된 경우에만 동작을 변경하며, 그렇지 않으면 동작하지 않습니다.
• host=node는 macOS 동반 앱이나 헤드리스 노드 호스트 (openclaw node run)를 대상으로 할 수 있습니다.
• 게이트웨이/노드 승인 및 허용 목록: Exec 승인.

​

process

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

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

​

loop-detection (도구 호출 루프 가드레일)

{
  tools: {
    loopDetection: {
      enabled: true,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      historySize: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

• genericRepeat: 도구와 매개변수가 동일한 반복적인 호출 패턴.
• knownPollNoProgress: 동일한 출력의 반복적인 폴링 도구.
• pingPong: 진행되지 않는 A/B/A/B 반복 패턴.
• 에이전트별 오버라이드: agents.list[].tools.loopDetection.

​

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_fetch

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

• tools.web.fetch.enabled로 활성화.
• maxChars는 tools.web.fetch.maxCharsCap으로 제한됩니다 (기본 50000).
• 응답은 캐시됩니다 (기본 15분).
• JS가 많은 사이트의 경우 브라우저 도구를 선호하십시오.
• 설정은 웹 도구를 참조하십시오.
• 선택적 안티봇 대체는 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 — 모든 브라우저 프로필을 상태와 함께 나열
• create-profile — 자동 할당된 포트(또는 cdpUrl)로 새 프로필 생성
• delete-profile — 브라우저 중지, 사용자 데이터 삭제, 설정에서 삭제 (로컬 전용)
• reset-profile — 고아 프로세스를 프로필의 포트에서 종료 (로컬 전용)

• profile (옵션; 기본값은 browser.defaultProfile)
• target (sandbox | host | node)
• node (옵션; 특정 노드 id/이름 선택)

• browser.enabled=true가 필요 (기본값은 true; 비활성화하려면 false로 설정).
• 모든 작업은 다중 인스턴스 지원을 위한 선택적 profile 매개변수를 수용합니다.
• profile이 생략되면 “chrome”으로 기본 설정되는 browser.defaultProfile을 사용합니다.
• 프로필 이름은 소문자, 영문자 및 하이픈만 허용 (최대 64자).
• 포트 범위: 18800-18899 (~100개 프로필 최대).
• 원격 프로필은 부착 전용 (시작/중지/재설정 없음).
• 브라우저 사용 가능한 노드가 연결된 경우, 도구가 자동으로 해당 노드로 경로를 지정할 수 있습니다 (직접 target을 지정하지 않은 경우).
• snapshot은 Playwright가 설치된 경우 기본적으로 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 참조) 또는 element (CSS 선택기)를 지원합니다.

​

canvas

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

• 게이트웨이 node.invoke를 내부적으로 사용합니다.
• node가 제공되지 않으면, 도구는 기본값을 선택합니다 (단일 연결 노드 또는 로컬 맥 노드).
• 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 페이로드 (위도/경도/정확도/타임스탬프)로 반환됩니다.
• 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이 구성되었을 때만 사용 가능 (주요 또는 보조), 또는 기본 모델과 구성된 인증에서 암시적 이미지 모델을 유추할 수 있을 때 (최선의 짝짓기).
• 주 채팅 모델과 독립적으로 이미지 모델을 직접 사용합니다.

​

message

• send (텍스트 + 옵션 미디어; MS Teams는 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이 게이트웨이를 통해 라우팅되고, 다른 채널은 직접 연결됩니다.
• poll은 WhatsApp과 MS Teams는 게이트웨이를 사용하고, Discord 설문조사는 직접 연결됩니다.
• 메시지 도구 호출이 활성 채팅 세션에 바인딩된 경우, 전송은 그 세션의 대상으로 제한되어 교차 컨텍스트 유출을 방지합니다.

​

cron

• status, list
• add, update, remove, run, runs
• wake (시스템 이벤트 큐에 추가 + 선택사항 즉시 하트비트)

• add는 전체 크론 작업 객체가 필요 (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: false로 비활성화 가능합니다.

​

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?, thinking?, runTimeoutSeconds?, thread?, mode?, cleanup?
• session_status: sessionKey? (기본값 현재; sessionId 수용), model? (default는 오버라이드를 해제)

• main은 정규 직접 채팅 키이며, 글로벌/알 수 없는 것은 숨겨집니다.
• messageLimit > 0은 각 세션에서 마지막 N개의 메시지를 가져옵니다 (도구 메시지는 필터링됨).
• 세션 타겟팅은 tools.sessions.visibility에 의해 제어됩니다 (기본값 tree: 현재 세션 + 생성된 하위 에이전트 세션). 여러 사용자를 위한 공유 에이전트를 실행하는 경우, tools.sessions.visibility: "self"로 설정하여 교차 세션 탐색을 방지하는 것을 고려하세요.
• sessions_send는 timeoutSeconds > 0일 때 최종 완료를 대기합니다.
• 전달/공지 사항은 완료 후 발생하고 최선의 결과로만 이루어지며, status: "ok"는 에이전트 실행이 완료되었음을 확인하며 공지 사항이 전달되었음을 나타내지 않습니다.
• sessions_spawn는 하위 에이전트 실행을 시작하며 요청자 채팅에 공지 답장을 게시합니다.
  • 일회성 모드 (mode: "run")와 지속적인 스레드 바인딩 모드 (mode: "session", thread: true 포함)를 지원합니다.
  • thread: true이고 mode가 생략된 경우 기본값은 session입니다.
  • mode: "session"은 thread: true가 필요합니다.
  • Discord 스레드 바인딩 흐름은 session.threadBindings.* 및 channels.discord.threadBindings.*에 의존합니다.
  • 답장 형식에는 Status, Result, 그리고 간단한 통계가 포함됩니다.
  • Result는 어시스턴트 완료 텍스트이며, 누락된 경우 최근 toolResult가 대체로 사용됩니다.
• 수동 완료 모드 생성은 먼저 직접 전송하며, 일시적 실패에 대한 대기열 대체 및 재시도가 있습니다 (status: "ok"는 실행이 완료되었음을 의미하며, 공지가 전달되었음을 의미하지 않음).
• sessions_spawn는 비차단이며 status: "accepted"를 즉시 반환합니다.
• sessions_send는 답장 백 핑퐁을 실행합니다 (답장 REPLY_SKIP으로 중단; session.agentToAgent.maxPingPongTurns를 통해 최대 턴 설정, 0–5).
• 핑퐁 후 대상 에이전트는 announce step을 실행하며, 공지 사항을 억제하려면 ANNOUNCE_SKIP으로 답장하세요.
• 샌드박스 제한: 현재 세션이 샌드박스 격리되고 agents.defaults.sandbox.sessionToolsVisibility: "spawned"인 경우, OpenClaw는 tools.sessions.visibility를 tree로 제한합니다.

​

agents_list

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

​

agents_list

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

​

매개변수 (공통)

• gatewayUrl (기본값 ws://127.0.0.1:18789)
• gatewayToken (인증 활성화 시)
• timeoutMs

• profile (옵션; 기본값은 browser.defaultProfile)
• target (sandbox | host | node)
• node (옵션; 특정 노드 id/이름 고정)

​

추천 에이전트 흐름

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에 전송되는 구조화된 함수 정의.