OpenClaw 도구(Tools) 설정하기

에이전트에게 어떤 권한을 줄지 결정하는 일은 항상 고민이죠. 너무 많은 도구를 허용하면 보안이 걱정되고, 그렇다고 하나씩 일일이 설정하자니 설정 파일이 너무 복잡해지기 마련입니다. 기존의 복잡한 스킬 시스템 대신, 이제 더 직관적이고 안전한 도구 관리 방식이 필요합니다.

OpenClaw는 복잡한 셸 호출 없이도 에이전트가 직접 브라우저나 런타임과 상호작용할 수 있는 구조를 제공해요. 어떻게 하면 도구들을 효율적으로 제어할 수 있는지 바로 알아볼까요?

필요한 것

openclaw.json 설정 파일
OpenClaw 환경

빠른 시작

OpenClaw는 browser, canvas, nodes, cron을 위한 first-class agent tools를 제공해요. 기존의 openclaw-* 스킬을 대체하는 이 도구들은 모두 타입이 지정되어 있고, 셸을 호출하는 방식이 아니므로 에이전트가 직접 의존하여 사용할 수 있습니다.

도구 비활성화하기

openclaw.json의 tools.allow 또는 tools.deny를 통해 도구를 전역적으로 관리할 수 있어요. 만약 두 설정이 충돌한다면 deny가 우선적으로 적용됩니다. 거부된 도구는 모델 프로바이더에게 전송되지 않아요.

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

도구 프로필(Profile) 활용하기

매번 도구를 하나씩 지정하기 번거롭다면 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: 제한 없음 (설정하지 않았을 때와 동일)

특정 에이전트에게만 별도의 프로필을 적용하는 것도 가능해요. 아래 예시는 전체적으로는 coding 프로필을 쓰지만, 고객 지원 에이전트에게만 messaging 프로필과 Slack 도구를 허용하는 설정입니다.

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

문제 해결

도구 이름 매칭: 대소문자를 구분하지 않으니 편하게 작성하세요.
와일드카드 사용: *를 사용하면 모든 도구를 의미합니다. ("*"는 모든 도구 선택)
경고 메시지: 만약 tools.allow에 알 수 없는 플러그인 도구 이름만 적혀 있다면, OpenClaw는 경고를 남기고 해당 allowlist를 무시합니다. 이 경우 핵심(core) 도구들은 계속 사용할 수 있는 상태로 유지됩니다.
우선순위: 동일한 도구가 allow와 deny에 모두 포함되어 있다면, 항상 deny가 이깁니다.

설정 중에 궁금한 점이 생기면 언제든 AI Setup Assistant의 도움을 받아보세요.

다음 단계

특정 Provider나 모델에서만 유독 도구가 오작동하는 경우를 겪어보셨나요? 모든 모델에 동일한 도구 세트를 제공하고 싶지만, 어떤 모델은 특정 API 호출에 취약하거나 보안상 제약이 있을 수 있습니다. 그렇다고 전체 설정을 바꾸자니 다른 모델들이 아쉬워지죠.

이럴 때 전체 설정을 건드리지 않고도 특정 환경에만 맞춤형 규칙을 적용하는 방법을 소개할게요.

필요한 것

tools.byProvider 설정
agents.list[].tools.byProvider 설정 (에이전트별 설정 시)

빠른 시작

tools.byProvider를 사용하면 글로벌 기본 설정을 유지하면서도 특정 Provider(또는 특정 provider/model)의 도구 사용을 더욱 세부적으로 제한할 수 있습니다.

이 설정은 기본 도구 Profile이 적용된 후에, 그리고 Allow/Deny 리스트가 적용되기 전에 실행됩니다. 즉, 기존 도구 세트를 더 좁게 제한하는 역할만 수행해요. Provider 키값으로는 google-antigravity 같은 Provider 이름이나 openai/gpt-5.2 같은 구체적인 모델 이름을 사용할 수 있습니다.

1. 글로벌 코딩 Profile 유지하며 특정 Provider만 제한하기

전체적으로는 coding Profile을 사용하지만, Google Antigravity 모델에만 최소한의 도구를 허용하고 싶을 때 사용하세요.

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

2. 불안정한 엔드포인트를 위한 모델별 Allowlist 설정

특정 모델에서 특정 API가 불안정하다면 해당 모델의 Allowlist만 별도로 관리할 수 있습니다.

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

3. 특정 에이전트 내에서 Provider 설정 덮어쓰기

에이전트 단위에서도 특정 Provider에 대한 도구 정책을 개별적으로 설정할 수 있습니다.

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

문제 해결

특정 모델에서 도구가 제대로 작동하지 않아요

불안정한 엔드포인트(Flaky endpoint)를 가진 모델이 있다면, 해당 모델의 byProvider 설정에서 문제가 되는 도구를 제외한 Allowlist를 직접 정의해 보세요. 위에서 소개한 openai/gpt-5.2 예시처럼 설정하면 해결할 수 있습니다.

설정 과정에서 도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

다음 단계

매번 Agent를 설정할 때마다 수많은 도구 이름을 일일이 나열하는 건 정말 번거로운 일이에요. 권한 설정을 하다가 실수로 중요한 도구를 빠뜨리기도 하고, 설정 파일이 너무 길어져서 한눈에 들어오지 않는 경우도 자주 발생하죠.

필요한 것

tools.allow 또는 tools.deny 설정이 포함된 Tool policies (global, agent, sandbox)
OpenClaw 환경

빠른 시작

Tool policies에서는 group:* 형식을 사용해서 여러 도구를 묶음으로 관리할 수 있어요. 이 shorthand를 사용하면 복잡한 도구 목록을 간단하게 줄일 수 있습니다.

사용 가능한 그룹 목록은 다음과 같아요:

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 도구 포함 (단, provider plugins는 제외)

파일 관련 도구와 브라우저만 허용하고 싶을 때의 예시예요:

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

Plugins + tools

Plugins를 사용하면 기본 세트 외에 추가 도구와 CLI 커맨드를 등록할 수 있어요. 설치와 설정 방법은 Plugins 문서에서 확인할 수 있고, 도구 사용 가이드가 프롬프트에 어떻게 주입되는지는 Skills 문서를 참고해 보세요. voice-call plugin처럼 일부 Plugin은 도구와 함께 전용 Skill을 제공하기도 합니다.

추가로 선택할 수 있는 Plugin 도구들은 다음과 같아요:

Lobster: 승인 후 재개가 가능한 타입화된 워크플로우 런타임이에요 (Gateway 호스트에 Lobster CLI가 설치되어 있어야 해요).
LLM Task: 구조화된 워크플로우 출력을 위한 JSON 전용 LLM 단계 도구예요 (선택적으로 스키마 검증이 가능해요).

문제 해결

문제: group:openclaw를 사용했는데 특정 Plugin 도구가 작동하지 않아요.
해결: group:openclaw는 내장 도구만 포함하며, provider plugins는 제외됩니다. Plugin으로 추가한 도구는 별도로 명시해 주세요.

설정 중에 궁금한 점이 생기면 AI Setup Assistant에게 언제든 물어보세요!

What’s Next

---
title: "OpenClaw Tool Inventory 가이드"
description: "OpenClaw 에이전트가 세상과 상호작용하기 위해 사용하는 강력한 도구 모음(Tool Inventory)을 살펴봅니다."
---

단순히 텍스트만 주고받는 AI는 답답할 때가 많죠? 코드를 수정하고 싶거나, 브라우저를 직접 조작해야 하거나, 복잡한 터미널 명령어를 실행해야 하는 상황 말이에요. 개발자로서 우리는 모델이 단순히 "말"만 하는 게 아니라 "행동"하기를 원합니다.

OpenClaw의 Tool Inventory는 에이전트에게 손과 발이 되어주는 기능들의 집합이에요. 파일 편집부터 브라우징, 메시지 전송까지 에이전트가 수행할 수 있는 모든 작업이 이 도구들을 통해 이루어집니다.

## 필요한 것

시작하기 전에 소스 문서에서 언급된 몇 가지 준비 사항을 체크해 주세요.

- **OpenAI 모델**: `apply_patch` 기능을 사용하려면 필요해요.
- **Brave API Key**: `web_search` 기능을 사용하기 위해 필요하며, `openclaw configure --section web`에서 설정할 수 있어요.
- **Playwright**: `browser` 도구에서 `ai` 스냅샷 기능을 사용하려면 설치되어 있어야 해요.
- **Gateway 설정**: `cron`이나 `gateway` 관리 도구를 쓰려면 Gateway가 실행 중이어야 합니다.

## 빠른 시작

가장 많이 쓰이는 `exec` 도구로 5분 만에 시작해 볼까요? 에이전트에게 쉘 명령어를 내리는 방법은 아주 간단해요.

1. `exec` 도구를 호출하여 원하는 명령어를 전달합니다.
2. `command` 파라미터에 실행할 명령을 넣으세요 (예: `ls -la`).
3. 결과를 바로 확인하거나, 시간이 오래 걸리는 작업은 `background: true`로 설정해 보세요.
4. 백그라운드 작업은 `process` 도구의 `poll` 액션으로 상태를 추적할 수 있어요.

---

## Tool Inventory 상세 상세 내역

### `apply_patch`
하나 이상의 파일에 구조화된 패치를 적용해요. 여러 부분을 한꺼번에 수정(multi-hunk edits)할 때 유용합니다.
- **참고**: 실험적 기능이며 `tools.exec.applyPatch.enabled`를 통해 활성화해야 해요 (OpenAI 모델 전용).

### `exec`
워크스페이스에서 쉘 명령어를 실행합니다.

**핵심 파라미터:**
- `command` (필수)
- `yieldMs`: 타임아웃 후 자동 백그라운드 전환 (기본값 10000ms)
- `background`: 즉시 백그라운드 실행
- `timeout`: 초 단위; 초과 시 프로세스 종료 (기본값 1800초)
- `elevated`: `true` 설정 시 호스트에서 실행 (샌드박스 상태일 때만 동작)
- `host`: `sandbox | gateway | node`
- `security`: `deny | allowlist | full`
- `ask`: `off | on-miss | always`
- `node`: `host=node`일 때 사용할 노드 ID/이름
- **TTY 필요 시**: `pty: true`로 설정하세요.

**주의사항:**
- 백그라운드 실행 시 `sessionId`와 함께 `status: "running"`을 반환해요.
- `process` 도구를 사용해 로그 확인, 입력, 종료 등을 관리할 수 있습니다.
- `elevated` 모드는 `tools.elevated`와 `agents.list[].tools.elevated` 설정이 모두 허용되어야 작동하며, `host=gateway` + `security=full`과 같은 의미입니다.
- 승인 및 allowlist 관련 상세 내용은 [Exec approvals](/docs/tools/exec-approvals)를 참고하세요.

### `process`
백그라운드 `exec` 세션을 관리합니다.
- **주요 액션**: `list`, `poll`, `log`, `write`, `kill`, `clear`, `remove`
- **참고**: `poll`은 작업 완료 시 새로운 출력과 종료 상태를 반환해요. `log`는 `offset`과 `limit`으로 줄 단위 조회가 가능합니다. 세션은 에이전트별로 격리되어 있어 다른 에이전트의 세션은 볼 수 없어요.

### `web_search`
Brave Search API를 사용해 웹을 검색해요.
- **핵심 파라미터**: `query` (필수), `count` (1–10; 기본값은 `tools.web.search.maxResults`)
- **설정**: `BRAVE_API_KEY`가 필요하며 `tools.web.search.enabled`를 통해 활성화합니다. 결과는 15분간 캐싱돼요. 자세한 내용은 [Web tools](/docs/tools/web)를 보세요.

### `web_fetch`
URL에서 읽기 가능한 콘텐츠를 추출해요 (HTML을 markdown이나 text로 변환).
- **핵심 파라미터**: `url` (필수), `extractMode` (`markdown` | `text`), `maxChars`
- **참고**: JS가 많이 들어간 사이트는 `browser` 도구를 권장해요. `maxChars`는 `tools.web.fetch.maxCharsCap`에 의해 제한됩니다. 설정법은 [Web tools](/docs/tools/web) 및 [Firecrawl](/docs/tools/firecrawl) 문서를 확인하세요.

### `browser`
OpenClaw가 관리하는 전용 브라우저를 제어합니다.

**주요 액션:**
- `status`, `start`, `stop`, `tabs`, `open`, `focus`, `close`
- `snapshot`: `aria` (접근성 트리) 또는 `ai` (Playwright 기반) 방식 지원
- `screenshot`: 이미지 블록과 `MEDIA:<path>` 반환
- `act`: 클릭, 타이핑, 드래그 등 UI 액션 (CSS 셀렉터 대신 `snapshot`에서 얻은 `ref` 사용 권장)
- `navigate`, `console`, `pdf`, `upload`, `dialog`
- **프로필 관리**: `profiles`, `create-profile`, `delete-profile`, `reset-profile`

**참고:**
- 포트 범위는 18800-18899를 사용하며 최대 100개 프로필을 지원해요.
- `act` 실행 시 `wait`을 남발하기보다 UI 상태가 안정될 때까지 기다리는 방식을 권장합니다.
- 원격 프로필은 연결(attach)만 가능하며 시작/중지는 할 수 없어요.

### `canvas`
노드 Canvas를 구동합니다 (present, eval, snapshot, A2UI).
- **핵심 액션**: `present`, `hide`, `navigate`, `eval`, `snapshot`, `a2ui_push`, `a2ui_reset`
- **참고**: A2UI는 v0.8 버전만 지원해요. v0.9 JSONL을 넣으면 오류가 발생하니 주의하세요.

### `nodes`
연결된 노드를 탐색하고 알림 전송, 카메라/화면 캡처 등을 수행해요.
- **주요 액션**: `status`, `describe`, `notify`, `camera_snap`, `screen_record`, `location_get`, `run`
- **예시 (`run` 액션)**:
```json
{
  "action": "run",
  "node": "office-mac",
  "command": ["echo", "Hello"],
  "env": ["FOO=bar"],
  "commandTimeoutMs": 12000,
  "invokeTimeoutMs": 45000,
  "needsScreenRecording": false
}

`image`

설정된 이미지 모델을 사용해 이미지를 분석해요.

파라미터: image (경로 또는 URL), prompt, model, maxBytesMb
참고: agents.defaults.imageModel이 설정되어 있어야 사용 가능해요.

`message`

Discord, Slack, Telegram 등 다양한 채널에 메시지를 보냅니다.

주요 액션: send, poll, react, thread-create, channel-list, member-info 등
참고: WhatsApp은 Gateway를 통해 라우팅되고, 다른 채널은 직접 전송됩니다. 활성화된 세션에 바인딩된 경우 해당 세션의 타겟으로 전송이 제한됩니다.

`cron`

Gateway 크론 작업과 웨이크업(wakeups)을 관리해요.

액션: status, list, add, update, remove, run, wake

`gateway`

실행 중인 Gateway 프로세스를 재시작하거나 설정을 업데이트합니다.

액션: restart, config.get, config.apply, config.patch, update.run
참고: 응답 도중 끊기는 것을 방지하려면 delayMs를 적절히 사용하세요.

`sessions` 관련 도구

세션 목록 확인, 히스토리 조사, 다른 세션으로 메시지 전송 등을 수행해요.

종류: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
참고: sessions_spawn은 서브 에이전트를 실행하고 즉시 status: "accepted"를 반환하는 비차단(non-blocking) 방식이에요.

`agents_list`

현재 세션이 sessions_spawn으로 호출할 수 있는 에이전트 ID 목록을 가져와요.

문제 해결

문제가 발생했나요? 아래 해결책을 확인해 보세요.

process 도구가 작동하지 않아요: 설정에서 process 사용이 허용되지 않았다면 exec는 동기적으로 실행되며 yieldMs나 background 옵션을 무시하게 됩니다.
elevated 모드가 동작하지 않아요: tools.elevated와 해당 에이전트의 agents.list[].tools.elevated 값이 모두 허용으로 되어 있는지 확인해 주세요.
브라우저 액션(act) 실패: CSS 셀렉터 대신 snapshot에서 반환된 ref 번호를 사용하고 있는지 확인하세요.
A2UI 오류: v0.9 JSONL 형식을 사용 중인지 확인하세요. 현재는 v0.8만 지원합니다.

궁금한 점이 더 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

여러 도구를 연결해 사용하다 보면 설정값이 꼬여서 에이전트가 제대로 작동하지 않는 경험을 하곤 하죠. 특히 인증 토큰이나 URL 설정 하나 때문에 전체 워크플로우가 멈추면 정말 답답해요. 이런 문제를 방지하기 위해 도구들이 공통으로 사용하는 파라미터를 정확히 이해하는 것이 중요합니다.

## 필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

- Gateway URL (기본값: `ws://127.0.0.1:18789`)
- Gateway Token (인증이 활성화된 경우)
- Browser 도구 사용 시 필요한 `profile` 정보

## 빠른 시작

가장 많이 사용하는 Gateway 기반 도구들을 설정하는 방법입니다.

1.  **Gateway 연결 설정**: `gatewayUrl`을 지정합니다.
2.  **인증 정보 추가**: `gatewayUrl`을 직접 설정했다면 `gatewayToken`도 반드시 명시해야 합니다.
3.  **타임아웃 설정**: 필요에 따라 `timeoutMs`를 조절합니다.

```typescript
// Gateway 기반 도구 예시 (canvas, nodes, cron)
{
  "gatewayUrl": "ws://127.0.0.1:18789",
  "gatewayToken": "your-token-here",
  "timeoutMs": 30000
}

주요 파라미터 살펴보기

Gateway 기반 도구 (`canvas`, `nodes`, `cron`)

이 도구들은 Gateway를 통해 통신하며 다음 파라미터를 공유합니다.

gatewayUrl: Gateway 주소입니다. (기본값 ws://127.0.0.1:18789)
gatewayToken: 인증이 필요한 경우 사용합니다.
timeoutMs: 작업 제한 시간입니다.

주의할 점: gatewayUrl을 별도로 설정하면 gatewayToken도 명시적으로 포함해야 해요. 도구가 환경 변수나 기존 설정을 자동으로 상속받지 않기 때문에, 인증 정보가 누락되면 에러가 발생합니다.

Browser 도구

브라우저 제어를 위한 파라미터입니다.

profile: (선택 사항) 사용할 브라우저 프로필입니다. 기본값은 browser.defaultProfile이에요.
target: sandbox, host, node 중 하나를 선택합니다.
node: (선택 사항) 특정 Node ID나 이름을 고정하여 사용합니다.

권장되는 에이전트 흐름 (Agent Flows)

에이전트가 작업을 더 효율적으로 수행할 수 있도록 돕는 권장 단계들입니다.

Browser 자동화

browser → status 또는 start로 상태 확인
snapshot (ai 또는 aria 방식)으로 페이지 분석
act (click, type, press 등)로 동작 수행
시각적 확인이 필요하면 screenshot 실행

Canvas 렌더링

canvas → present 호출
필요하다면 a2ui_push 추가
snapshot으로 결과 확인

Node 타겟팅

nodes → status로 노드 확인
선택한 노드에 대해 describe 실행
notify, run, camera_snap, screen_record 등 필요한 명령 실행

Safety (안전 가이드)

에이전트를 안전하게 운영하기 위해 다음 규칙을 지켜주세요.

system.run을 직접 호출하지 마세요. 대신 nodes → run을 사용하고, 반드시 사용자의 명시적인 동의를 받아야 합니다.
카메라나 화면 캡처를 사용할 때는 사용자의 동의를 존중해야 해요.
미디어 관련 명령을 내리기 전에 status나 describe를 먼저 호출해서 권한이 있는지 확인하는 것이 좋습니다.

에이전트에게 도구가 보여지는 방식

에이전트는 두 가지 경로로 도구를 인식합니다.

System prompt text: 사람이 읽을 수 있는 형태의 도구 목록과 안내 가이드입니다.
Tool schema: 모델 API로 전송되는 구조화된 함수 정의입니다.

에이전트는 “어떤 도구가 있는지”와 “어떻게 호출하는지”를 모두 알고 있어야 해요. 시스템 프롬프트나 스키마 중 하나라도 빠지면 모델은 해당 도구를 호출할 수 없으니 주의하세요.

문제 해결

문제: Gateway 연결 시 인증 에러가 발생합니다.

해결 방법: gatewayUrl을 직접 설정했는지 확인해 보세요. URL을 직접 지정했다면 gatewayToken도 명시적으로 추가해야 합니다. 설정을 자동으로 상속받지 않기 때문입니다.

문제: 브라우저 자동화 중 요소를 찾지 못합니다.

해결 방법: act 명령을 내리기 전에 snapshot을 먼저 호출했는지 확인해 보세요. 에이전트가 현재 페이지 상태를 최신화해야 정확한 위치에 동작을 수행할 수 있습니다.

설정 과정에서 도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.

OpenClaw 도구(Tools) 설정하기

필요한 것

빠른 시작

도구 비활성화하기

도구 프로필(Profile) 활용하기

문제 해결

다음 단계

필요한 것

빠른 시작

1. 글로벌 코딩 Profile 유지하며 특정 Provider만 제한하기

2. 불안정한 엔드포인트를 위한 모델별 Allowlist 설정

3. 특정 에이전트 내에서 Provider 설정 덮어쓰기

문제 해결

특정 모델에서 도구가 제대로 작동하지 않아요

다음 단계

필요한 것

빠른 시작

Plugins + tools

문제 해결

image

message

cron

gateway

sessions 관련 도구

agents_list

문제 해결

다음 단계

주요 파라미터 살펴보기

Gateway 기반 도구 (canvas, nodes, cron)

Browser 도구

권장되는 에이전트 흐름 (Agent Flows)

Browser 자동화

Canvas 렌더링

Node 타겟팅

Safety (안전 가이드)

에이전트에게 도구가 보여지는 방식

문제 해결

다음 단계

아직 막혀 있나요?

`image`

`message`

`cron`

`gateway`

`sessions` 관련 도구

`agents_list`

Gateway 기반 도구 (`canvas`, `nodes`, `cron`)