Tools (OpenClaw)

OpenClaw는 browser, canvas, nodes, cron을 위한 first-class agent tools를 제공합니다. 이 도구들은 오래된 openclaw-* skills를 대체합니다. 모든 tool은 typed되어 있으며 셸을 우회 호출할 필요가 없고, agent는 가능한 한 이들을 직접 사용해야 합니다.

Disabling tools

openclaw.json의 tools.allow / tools.deny를 통해 tool을 전역적으로 허용/차단할 수 있습니다 (deny가 우선함). 이렇게 하면 허용되지 않은 tool이 model provider로 전송되지 않습니다.

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

참고:

매칭은 대소문자를 구분하지 않습니다.
* wildcard를 지원합니다 ("*"는 모든 tool을 의미).
tools.allow가 알 수 없거나 로드되지 않은 plugin tool 이름만 참조하면, OpenClaw는 경고를 기록하고 allowlist를 무시하여 core tool이 계속 사용 가능하도록 합니다.

Tool profiles (base allowlist)

tools.profile은 tools.allow/tools.deny 전에 적용되는 기본 tool allowlist를 설정합니다. agent별 override: agents.list[].tools.profile. 프로필:

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: 제한 없음 (미설정과 동일)

예시 (기본은 messaging-only, Slack + Discord tool도 허용):

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

예시 (coding 프로필이지만 어디서나 exec/process는 차단):

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

예시 (전역 coding 프로필, support agent는 messaging-only):

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

Provider-specific tool policy

tools.byProvider를 사용하면 전역 기본값을 바꾸지 않고도 특정 provider (또는 단일 provider/model)에 대해 tool을 추가로 제한할 수 있습니다. agent별 override: agents.list[].tools.byProvider. 이는 기본 tool profile 이후, allow/deny list 이전에 적용되므로 tool 집합을 더 좁히는 것만 가능합니다. provider key는 provider(예: google-antigravity) 또는 provider/model(예: openai/gpt-5.2) 둘 다 사용할 수 있습니다. 예시 (전역 coding 프로필 유지, 하지만 Google Antigravity에는 minimal tool만 사용):

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

예시 (불안정한 endpoint에 대해 provider/model별 allowlist 적용):

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

예시 (단일 provider에 대한 agent-specific override):

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

Tool groups (shorthands)

tool policy(전역, agent, sandbox)는 여러 tool로 확장되는 group:* 항목을 지원합니다. tools.allow / tools.deny에서 사용하세요. 사용 가능한 그룹:

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: 모든 built-in OpenClaw tool (provider plugin 제외)

예시 (파일 tool + browser만 허용):

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

Plugins + tools

plugin은 core set 외에 추가 tool(및 CLI 명령)을 등록할 수 있습니다. 설치 및 구성은 Plugins을 참고하고, tool 사용 가이드가 prompt에 어떻게 주입되는지는 Skills를 참고하세요. 일부 plugin은 tool과 함께 자체 skill도 제공합니다(예: voice-call plugin). 선택적 plugin tool:

Lobster: 재개 가능한 승인 기능이 있는 typed workflow runtime (gateway host에 Lobster CLI 필요).
LLM Task: 구조화된 workflow 출력을 위한 JSON-only LLM step (선택적 schema validation).
Diffs: before/after text 또는 unified patch를 위한 read-only diff viewer 및 PNG/PDF 파일 renderer.

Tool inventory

`apply_patch`

하나 이상의 파일에 구조화된 patch를 적용합니다. multi-hunk 편집에 사용합니다. 실험적 기능이며 tools.exec.applyPatch.enabled로 활성화합니다 (OpenAI model 전용). tools.exec.applyPatch.workspaceOnly의 기본값은 true(workspace 내부 한정)입니다. apply_patch가 workspace 디렉터리 밖에 쓰기/삭제하도록 의도한 경우에만 false로 설정하세요.

`exec`

workspace에서 shell 명령을 실행합니다. 핵심 매개변수:

command (필수)
yieldMs (timeout 후 자동 background, 기본값 10000)
background (즉시 background)
timeout (초 단위, 초과 시 process 종료, 기본값 1800)
elevated (bool; elevated mode가 활성/허용된 경우 host에서 실행. agent가 sandboxed일 때만 동작 변화가 있음)
host (sandbox | gateway | node)
security (deny | allowlist | full)
ask (off | on-miss | always)
node (host=node용 node id/name)
실제 TTY가 필요하다면 pty: true를 설정하세요.

참고:

background로 전환되면 status: "running"과 sessionId를 반환합니다.
background session을 poll/log/write/kill/clear하려면 process를 사용하세요.
process가 허용되지 않으면 exec는 동기식으로 실행되며 yieldMs/background를 무시합니다.
elevated는 tools.elevated와 agents.list[].tools.elevated override의 제약을 받습니다(둘 다 허용해야 함). 이는 host=gateway + security=full의 별칭입니다.
elevated는 agent가 sandboxed일 때만 동작을 바꿉니다(그 외에는 no-op).
host=node는 macOS companion app 또는 headless node host(openclaw node run)를 대상으로 할 수 있습니다.
gateway/node approval 및 allowlist는 Exec approvals를 참고하세요.

`process`

background exec session을 관리합니다. 핵심 action:

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

참고:

poll은 완료 시 새 출력과 exit status를 반환합니다.
log는 줄 단위 offset/limit를 지원합니다 (offset을 생략하면 마지막 N줄을 가져옴).
process는 agent별 범위로 제한되며, 다른 agent의 session은 보이지 않습니다.

`loop-detection` (tool-call loop guardrails)

OpenClaw는 최근 tool-call 기록을 추적하고, 진전 없는 반복 루프를 감지하면 차단하거나 경고합니다. tools.loopDetection.enabled: true로 활성화하세요 (기본값은 false).

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

genericRepeat: 같은 tool + 같은 params 호출 패턴 반복.
knownPollNoProgress: 동일한 출력을 가진 poll 계열 tool의 반복.
pingPong: A/B/A/B 식의 진전 없는 교대 패턴.
agent별 override: agents.list[].tools.loopDetection.

`web_search`

Perplexity, Brave, Gemini, Grok, Kimi를 사용해 웹을 검색합니다. 핵심 매개변수:

query (필수)
count (1–10, 기본값은 tools.web.search.maxResults에서 가져옴)

참고:

선택한 provider에 대한 API key가 필요합니다 (권장: openclaw configure --section web).
tools.web.search.enabled로 활성화합니다.
응답은 캐시됩니다 (기본 15분).
설정은 Web tools를 참고하세요.

`web_fetch`

URL에서 읽기 좋은 콘텐츠를 가져와 추출합니다 (HTML → markdown/text). 핵심 매개변수:

url (필수)
extractMode (markdown | text)
maxChars (긴 페이지 잘라내기)

참고:

tools.web.fetch.enabled로 활성화합니다.
maxChars는 tools.web.fetch.maxCharsCap으로 상한이 적용됩니다 (기본 50000).
응답은 캐시됩니다 (기본 15분).
JS 비중이 큰 사이트는 browser tool을 우선 사용하세요.
설정은 Web tools를 참고하세요.
선택적 anti-bot fallback은 Firecrawl을 참고하세요.

`browser`

OpenClaw가 관리하는 전용 browser를 제어합니다. 핵심 action:

status, start, stop, tabs, open, focus, close
snapshot (aria/ai)
screenshot (image block + MEDIA:<path> 반환)
act (UI actions: click/type/press/hover/drag/select/fill/resize/wait/evaluate)
navigate, console, pdf, upload, dialog

프로필 관리:

profiles — 상태와 함께 모든 browser profile 나열
create-profile — 자동 할당된 port(또는 cdpUrl)로 새 profile 생성
delete-profile — browser 중지, user data 삭제, config에서 제거 (local 전용)
reset-profile — profile port의 orphan process 종료 (local 전용)

일반 매개변수:

profile (선택 사항, 기본값은 browser.defaultProfile)
target (sandbox | host | node)
node (선택 사항, 특정 node id/name 지정) 참고:
browser.enabled=true가 필요합니다 (기본값은 true; 비활성화하려면 false 설정).
모든 action은 multi-instance 지원을 위해 선택적 profile 매개변수를 받습니다.
profile을 생략하면 browser.defaultProfile을 사용합니다 (기본값 "chrome").
profile 이름은 소문자 영숫자 + 하이픈만 허용합니다 (최대 64자).
port 범위: 18800-18899 (최대 약 100개 profile).
remote profile은 attach-only입니다 (start/stop/reset 불가).
browser-capable node가 연결되어 있으면 tool이 자동으로 그쪽으로 라우팅할 수 있습니다 (target을 고정하지 않은 경우).
Playwright가 설치되어 있으면 snapshot 기본값은 ai입니다. accessibility tree가 필요하면 aria를 사용하세요.
snapshot은 role-snapshot 옵션(interactive, compact, depth, selector)도 지원하며 e12 같은 ref를 반환합니다.
act는 snapshot에서 받은 ref가 필요합니다 (AI snapshot은 숫자 12, role snapshot은 e12). 드문 CSS selector 필요 시에는 evaluate를 사용하세요.
기본적으로 act → wait를 남용하지 마세요. 신뢰할 수 있는 UI 상태를 기다릴 수 없는 예외적인 경우에만 사용하세요.
upload는 준비 후 자동 click하도록 선택적 ref를 전달할 수 있습니다.
upload는 <input type="file">에 직접 설정하기 위한 inputRef(aria ref) 또는 element(CSS selector)도 지원합니다.

`canvas`

node Canvas를 구동합니다 (present, eval, snapshot, A2UI). 핵심 action:

present, hide, navigate, eval
snapshot (image block + MEDIA:<path> 반환)
a2ui_push, a2ui_reset

참고:

내부적으로 gateway node.invoke를 사용합니다.
node를 지정하지 않으면 tool이 기본값을 선택합니다 (연결된 단일 node 또는 로컬 mac node).
A2UI는 v0.8 전용입니다 (createSurface 없음). CLI는 v0.9 JSONL을 줄 단위 오류와 함께 거부합니다.
빠른 smoke test: openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI".

`nodes`

pairing된 node를 탐색하고 대상으로 지정하며, notification을 보내고, camera/screen을 캡처합니다. 핵심 action:

status, describe
pending, approve, reject (pairing)
notify (macOS system.notify)
run (macOS system.run)
camera_list, camera_snap, camera_clip, screen_record
location_get, notifications_list, notifications_action
device_status, device_info, device_permissions, device_health

참고:

camera/screen 명령은 node app이 foreground에 있어야 합니다.
이미지는 image block + MEDIA:<path>를 반환합니다.
비디오는 FILE:<path>(mp4)를 반환합니다.
location은 JSON payload(lat/lon/accuracy/timestamp)를 반환합니다.
run params: command argv 배열, 선택적 cwd, env (KEY=VAL), commandTimeoutMs, invokeTimeoutMs, needsScreenRecording.

예시 (run):

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

`image`

구성된 image model로 이미지를 분석합니다. 핵심 매개변수:

image (필수 path 또는 URL)
prompt (선택 사항, 기본값은 "Describe the image.")
model (선택적 override)
maxBytesMb (선택적 크기 상한)

참고:

agents.defaults.imageModel이 구성된 경우(기본값 또는 fallback), 또는 기본 model + 구성된 auth로부터 암시적 image model을 추론할 수 있는 경우에만 사용 가능합니다 (best-effort pairing).
main chat model과 독립적으로 image model을 직접 사용합니다.

`pdf`

하나 이상의 PDF 문서를 분석합니다. 전체 동작, 제한, config, 예시는 PDF tool를 참고하세요.

`message`

Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams 전반에서 메시지와 채널 action을 전송합니다. 핵심 action:

send (텍스트 + 선택적 media, MS Teams는 Adaptive Cards용 card도 지원)
poll (WhatsApp/Discord/MS Teams poll)
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 poll은 직접 전송합니다.
message tool 호출이 활성 chat session에 바인딩된 경우, 교차 컨텍스트 유출을 막기 위해 전송은 그 session의 target으로 제한됩니다.

`cron`

Gateway cron job과 wakeup을 관리합니다. 핵심 action:

status, list
add, update, remove, run, runs
wake (system event enqueue + 선택적 즉시 heartbeat)

참고:

add는 전체 cron job 객체를 기대합니다 (cron.add RPC와 동일한 schema).
update는 { jobId, patch }를 사용합니다 (id도 호환성을 위해 허용됨).

`gateway`

실행 중인 Gateway process를 재시작하거나 update를 적용합니다(in-place). 핵심 action:

restart (권한 확인 후 in-process restart를 위해 SIGUSR1 전송, openclaw gateway 재시작 in-place)
config.schema.lookup (전체 schema를 prompt context에 로드하지 않고 config path 하나만 검사)
config.get
config.apply (validate + config 쓰기 + restart + wake)
config.patch (부분 update merge + restart + wake)
update.run (update 실행 + restart + wake)

참고:

config.schema.lookup에는 gateway.auth 또는 agents.list.*.heartbeat 같은 대상 config path를 전달해야 합니다.
plugins.entries.<id>를 다룰 때는 slash로 구분된 plugin id를 path에 포함할 수 있습니다. 예: plugins.entries.pack/one.config.
진행 중인 reply를 끊지 않으려면 delayMs(기본값 2000)를 사용하세요.
config.schema는 내부 Control UI 흐름에는 계속 사용 가능하지만 agent gateway tool로는 노출되지 않습니다.
restart는 기본적으로 활성화되어 있습니다. 비활성화하려면 commands.restart: false를 설정하세요.

`sessions_list` / `sessions_history` / `sessions_send` / `sessions_spawn` / `session_status`

session을 나열하고, transcript history를 확인하거나, 다른 session으로 전송합니다. 핵심 매개변수:

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?, runtime?, agentId?, model?, thinking?, cwd?, runTimeoutSeconds?, thread?, mode?, cleanup?, sandbox?, streamTo?, attachments?, attachAs?
session_status: sessionKey? (기본값은 현재 session, sessionId 허용), model? (default는 override 해제)

참고:

main은 canonical direct-chat key이며, global/unknown은 숨겨집니다.
messageLimit > 0이면 session별 마지막 N개 메시지를 가져옵니다 (tool 메시지는 필터링됨).
session targeting은 tools.sessions.visibility로 제어됩니다 (기본값 tree: 현재 session + spawn된 subagent session). 여러 사용자를 위해 공유 agent를 실행한다면, 교차 session 탐색을 방지하려고 tools.sessions.visibility: "self" 설정을 고려하세요.
sessions_send는 timeoutSeconds > 0일 때 최종 완료까지 대기합니다.
delivery/announce는 완료 후 best-effort로 이뤄집니다. status: "ok"는 announce가 전달되었다는 뜻이 아니라 agent 실행이 끝났다는 뜻입니다.
sessions_spawn은 runtime: "subagent" | "acp"를 지원합니다 (기본값은 subagent). ACP runtime 동작은 ACP Agents를 참고하세요.
ACP runtime에서 streamTo: "parent"는 초기 실행 진행 요약을 직접 child 전달 대신 requester session으로 system event 형태로 라우팅합니다.
sessions_spawn은 sub-agent 실행을 시작하고 requester chat으로 announce reply를 게시합니다.
- one-shot mode(mode: "run")와 persistent thread-bound mode(mode: "session" + thread: true)를 지원합니다.
- thread: true이고 mode가 생략되면 mode 기본값은 session입니다.
- mode: "session"에는 thread: true가 필요합니다.
- runTimeoutSeconds를 생략하면, 설정된 경우 OpenClaw는 agents.defaults.subagents.runTimeoutSeconds를 사용하고, 그렇지 않으면 기본 timeout은 0(timeout 없음)입니다.
- Discord thread-bound flow는 session.threadBindings.*와 channels.discord.threadBindings.*에 의존합니다.
- reply 형식에는 Status, Result, compact stats가 포함됩니다.
- Result는 assistant completion text이며, 없으면 최신 toolResult를 fallback으로 사용합니다.
수동 completion-mode spawn은 먼저 direct로 전송한 뒤, 일시적 실패 시 queue fallback과 retry를 수행합니다 (status: "ok"는 announce 전달이 아니라 실행 종료를 의미).
sessions_spawn은 subagent runtime에 한해 inline file attachment를 지원합니다 (ACP는 이를 거부함). 각 attachment는 name, content, 선택적 encoding(utf8 또는 base64), mimeType을 가집니다. 파일은 child workspace의 .openclaw/attachments/<uuid>/에 .manifest.json metadata 파일과 함께 materialize됩니다. tool은 count, totalBytes, 파일별 sha256, relDir를 담은 receipt를 반환합니다. attachment content는 transcript persistence에서 자동으로 redaction됩니다.
- 제한은 tools.sessions_spawn.attachments(enabled, maxTotalBytes, maxFiles, maxFileBytes, retainOnSessionKeep)로 구성합니다.
- attachAs.mountPath는 향후 mount 구현을 위한 예약 힌트입니다.
sessions_spawn은 non-blocking이며 즉시 status: "accepted"를 반환합니다.
ACP streamTo: "parent" 응답에는 진행 history를 tailing하기 위한 streamLogPath(session-scoped *.acp-stream.jsonl)가 포함될 수 있습니다.
sessions_send는 reply-back ping-pong을 수행합니다 (REPLY_SKIP로 중단, 최대 turn 수는 session.agentToAgent.maxPingPongTurns, 0–5).
ping-pong 이후 target agent는 announce step을 실행합니다. announcement를 막으려면 ANNOUNCE_SKIP로 reply하세요.
sandbox clamp: 현재 session이 sandboxed이고 agents.defaults.sandbox.sessionToolsVisibility: "spawned"이면, OpenClaw는 tools.sessions.visibility를 tree로 clamp합니다.

`agents_list`

현재 session이 sessions_spawn으로 대상으로 지정할 수 있는 agent id를 나열합니다. 참고:

결과는 agent별 allowlist(agents.list[].subagents.allowAgents)로 제한됩니다.
["*"]가 설정된 경우 tool은 구성된 모든 agent를 포함하고 allowAny: true를 표시합니다.

Parameters (common)

Gateway-backed tools(canvas, nodes, cron):

gatewayUrl (기본값 ws://127.0.0.1:18789)
gatewayToken (auth가 활성화된 경우)
timeoutMs

참고: gatewayUrl을 설정했다면 gatewayToken도 명시적으로 포함해야 합니다. override 시 tool은 config나 environment 자격 증명을 상속하지 않으며, 필요한 자격 증명이 명시되지 않으면 오류가 발생합니다. Browser tool:

profile (선택 사항, 기본값은 browser.defaultProfile)
target (sandbox | host | node)
node (선택 사항, 특정 node id/name 고정)
문제 해결 가이드:
- Linux startup/CDP 문제: Browser troubleshooting (Linux)
- WSL2 Gateway + Windows remote Chrome CDP: WSL2 + Windows + remote Chrome CDP troubleshooting

Recommended agent flows

Browser automation:

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

Canvas render:

canvas → present
a2ui_push (선택 사항)
snapshot

Node targeting:

nodes → status
선택한 node에 describe
notify / run / camera_snap / screen_record

Safety

직접 system.run을 사용하지 말고, nodes → run은 명시적 사용자 동의가 있을 때만 사용하세요.
camera/screen 캡처에 대해서는 사용자 동의를 존중하세요.
media 명령을 호출하기 전에 status/describe로 권한을 확인하세요.

How tools are presented to the agent

tool은 두 개의 병렬 채널로 agent에 노출됩니다:

System prompt text: 사람이 읽을 수 있는 목록 + 가이드.
Tool schema: model API로 전송되는 구조화된 function 정의.

즉, agent는 “어떤 tool이 존재하는가”와 “어떻게 호출하는가”를 모두 봅니다. tool이 system prompt나 schema에 나타나지 않으면, model은 해당 tool을 호출할 수 없습니다.

개요

내장 도구

브라우저

에이전트 연동

스킬

확장 기능

자동화

미디어 및 장치

Tools

Tools (OpenClaw)

Disabling tools

Tool profiles (base allowlist)

Provider-specific tool policy

Tool groups (shorthands)

Plugins + tools

Tool inventory

`apply_patch`

`exec`

`process`

`loop-detection` (tool-call loop guardrails)

`web_search`

`web_fetch`

`browser`

`canvas`

`nodes`

`image`

`pdf`

`message`

`cron`

`gateway`

`sessions_list` / `sessions_history` / `sessions_send` / `sessions_spawn` / `session_status`

`agents_list`

Parameters (common)

Recommended agent flows

Safety

How tools are presented to the agent

개요

내장 도구

브라우저

에이전트 연동

스킬

확장 기능

자동화

미디어 및 장치

​Tools (OpenClaw)

​Disabling tools

​Tool profiles (base allowlist)

​Provider-specific tool policy

​Tool groups (shorthands)

​Plugins + tools

​Tool inventory

​apply_patch

​exec

​process

​loop-detection (tool-call loop guardrails)

​web_search

​web_fetch

​browser

​canvas

​nodes

​image

​pdf

​message

​cron

​gateway

​sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

​agents_list

​Parameters (common)

​Recommended agent flows

​Safety

​How tools are presented to the agent

Tools (OpenClaw)

Disabling tools

Tool profiles (base allowlist)

Provider-specific tool policy

Tool groups (shorthands)

Plugins + tools

Tool inventory

`apply_patch`

`exec`

`process`

`loop-detection` (tool-call loop guardrails)

`web_search`

`web_fetch`

`browser`

`canvas`

`nodes`

`image`

`pdf`

`message`

`cron`

`gateway`

`sessions_list` / `sessions_history` / `sessions_send` / `sessions_spawn` / `session_status`

`agents_list`

Parameters (common)

Recommended agent flows

Safety

How tools are presented to the agent