Docs | Src |   A-  |  A+   | -/-

Metadata
sourcehttps://docs.openclaw.ai/tools
created2026-03-01
bynvidia:z-ai/glm5

오픈클로 도구

오픈클로(OpenClaw)는 브라우저, 캔버스, 노드, 크론(Cron)을 위한 일급 에이전트 도구를 제공한다. 이 도구들은 기존 openclaw-* 스킬을 대체한다. 도구에는 타입이 지정되어 있고 셸을 실행하지 않으며, 에이전트는 이 도구들에 직접 의존해야 한다. openclaw.json에서 tools.allow / tools.deny를 통해 전역적으로 도구를 허용하거나 거부할 수 있다(거부가 우선한다). 이렇게 하면 허용되지 않은 도구가 모델 제공자에게 전송되는 것을 방지할 수 있다.

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

참고:

tools.profile은 tools.allow / tools.deny 이전에 기본 도구 허용 목록을 설정한다. 에이전트별 재정의는 agents.list[].tools.profile에서 가능하다.

프로필:

예시(기본적으로 메시징 전용, 슬랙(Slack) + 디스코드(Discord) 도구도 허용):

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

예시(코딩 프로필이지만 exec/process는 어디서든 거부):

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

예시(전역 코딩 프로필, 메시징 전용 지원 에이전트):

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

전역 기본값을 변경하지 않고 특정 제공자(또는 단일 provider/model)에 대해 도구를 추가로 제한하려면 tools.byProvider를 사용한다. 에이전트별 재정의는 agents.list[].tools.byProvider에서 가능하다. 이 설정은 기본 도구 프로필 이후, 허용/거부 목록 이전에 적용된다. 따라서 도구 집합을 좁히는 역할만 한다. 제공자 키는 provider(예: google-antigravity) 또는 provider/model(예: openai/gpt-5.2)을 받는다.

예시(전역 코딩 프로필 유지, 구글 안티그래비티(Google Antigravity)는 최소 도구만):

{
  "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:* 항목을 지원한다. tools.allow / tools.deny에서 사용한다. 사용 가능한 그룹:

예시(파일 도구 + 브라우저만 허용):

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

플러그인은 핵심 세트 외에 추가 도구(및 CLI 명령)를 등록할 수 있다. 설치 및 설정은 플러그인을, 도구 사용 가이드가 프롬프트에 주입되는 방식은 스킬을 참조하라. 일부 플러그인은 도구와 함께 자체 스킬을 제공한다(예: 음성 통화 플러그인).

선택적 플러그인 도구:

apply_patch

하나 이상의 파일에 구조화된 패치를 적용한다. 여러 청(multi-hunk) 편집에 사용한다.

실험적 기능: tools.exec.applyPatch.enabled로 활성화한다(오픈AI 모델만 해당).

tools.exec.applyPatch.workspaceOnly의 기본값은 true(워크스페이스 내 포함)이다. 의도적으로 apply_patch가 워크스페이스 디렉터리 외부에 쓰거나 삭제하게 하려면 false로 설정하라.

exec

워크스페이스에서 셸 명령을 실행한다.

핵심 매개변수:

참고:

process

백그라운드 exec 세션을 관리한다.

핵심 작업:

참고:

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

오픈클로는 최근 도구 호출 기록을 추적하여 반복되고 진전이 없는 루프를 감지하면 차단하거나 경고한다. tools.loopDetection.enabled: true로 활성화한다(기본값은 false).

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

web_search

Brave Search API를 사용하여 웹을 검색한다.

핵심 매개변수:

참고:

web_fetch

URL에서 콘텐츠를 가져와 읽을 수 있는 형식으로 추출한다(HTML → 마크다운/텍스트).

핵심 매개변수:

참고:

browser

전용 오픈클로 관리 브라우저를 제어한다.

핵심 작업:

프로필 관리:

공통 매개변수:

참고:

canvas

노드 캔버스를 구동한다(제시, 평가, 스냅샷, A2UI).

핵심 작업:

참고:

nodes

페어링된 노드를 검색하고 대상으로 지정하며, 알림을 보내고 카메라/화면을 캡처한다.

핵심 작업:

참고:

예시(run):

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

image

구성된 이미지 모델로 이미지를 분석한다.

핵심 매개변수:

참고:

message

디스코드/구글 챗/슬랙/텔레그램/왓츠앱/시그널/iMessage/MS 팀즈 간에 메시지와 채널 작업을 보낸다.

핵심 작업:

참고:

cron

게이트웨이 크론 작업 및 웨이크업을 관리한다.

핵심 작업:

참고:

gateway

실행 중인 게이트웨이 프로세스를 재시작하거나 업데이트를 적용한다(인플레이스).

핵심 작업:

참고:

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

세션을 나열하고, 기록을 검사하거나, 다른 세션으로 보낸다.

핵심 매개변수:

참고:

agents_list

현재 세션이 sessions_spawn으로 대상으로 지정할 수 있는 에이전트 ID를 나열한다.

참고:

매개변수 (공통)

게이트웨이 지원 도구(canvas, nodes, cron):

참고: gatewayUrl을 설정할 때는 gatewayToken을 명시적으로 포함하라. 도구는 재정의를 위해 구성이나 환경 자격 증명을 상속하지 않는다. 명시적 자격 증명이 누락되면 오류이다.

브라우저 도구:

권장 에이전트 흐름

브라우저 자동화:

  1. browser → status / start
  2. snapshot (ai 또는 aria)
  3. act (클릭/입력/누르기)
  4. 시각적 확인이 필요하면 screenshot

캔버스 렌더링:

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

노드 대상 지정:

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

안전

도구는 두 개의 병렬 채널을 통해 노출된다:

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

즉, 에이전트는 "어떤 도구가 있는지"와 "어떻게 호출하는지"를 모두 볼 수 있다. 도구가 시스템 프롬프트나 스키마에 나타나지 않으면 모델은 그 도구를 호출할 수 없다.

https://docs.openclaw.ai/tools