Tools (OpenClaw)

OpenClaw cung cấp các công cụ agent hạng nhất cho browser, canvas, nodes và cron. Chúng thay thế các skill openclaw-* cũ: các công cụ này có kiểu dữ liệu rõ ràng, không cần shell, và agent có thể dựa vào chúng trực tiếp.

Vô hiệu hóa công cụ

Các bạn có thể cho phép/từ chối công cụ toàn cục thông qua tools.allow / tools.deny trong openclaw.json (deny sẽ được ưu tiên). Điều này ngăn các công cụ không được phép được gửi đến model provider.

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

Lưu ý:

Khớp tên không phân biệt chữ hoa chữ thường.
Hỗ trợ ký tự đại diện * ("*" nghĩa là tất cả công cụ).
Nếu tools.allow chỉ tham chiếu đến tên công cụ plugin không xác định hoặc chưa tải, OpenClaw sẽ ghi cảnh báo và bỏ qua allowlist để các công cụ cốt lõi vẫn khả dụng.

Tool profiles (danh sách cho phép cơ bản)

tools.profile thiết lập danh sách cho phép công cụ cơ bản trước khi áp dụng tools.allow/tools.deny. Ghi đè cho từng agent: agents.list[].tools.profile.

Các profile:

minimal: chỉ session_status
coding: group:fs, group:runtime, group:sessions, group:memory, image
messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
full: không hạn chế (giống như không đặt)

Ví dụ (mặc định chỉ messaging, cho phép thêm công cụ Slack + Discord):

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

Ví dụ (profile coding, nhưng từ chối exec/process ở mọi nơi):

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

Ví dụ (profile coding toàn cục, agent support chỉ dùng messaging):

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

Chính sách công cụ theo provider

Dùng tools.byProvider để hạn chế thêm công cụ cho các provider cụ thể (hoặc một provider/model đơn lẻ) mà không thay đổi cài đặt toàn cục. Ghi đè cho từng agent: agents.list[].tools.byProvider.

Điều này được áp dụng sau tool profile cơ bản và trước danh sách allow/deny, nên nó chỉ có thể thu hẹp bộ công cụ. Khóa provider chấp nhận provider (ví dụ google-antigravity) hoặc provider/model (ví dụ openai/gpt-5.2).

Ví dụ (giữ profile coding toàn cục, nhưng công cụ tối thiểu cho Google Antigravity):

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

Ví dụ (allowlist theo provider/model cho endpoint không ổn định):

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

Ví dụ (ghi đè theo agent cho một provider duy nhất):

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

Tool groups (viết tắt)

Các chính sách công cụ (toàn cục, agent, sandbox) hỗ trợ các mục group:* mở rộng thành nhiều công cụ. Dùng chúng trong tools.allow / tools.deny.

Các group có sẵn:

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: tất cả công cụ OpenClaw tích hợp sẵn (không bao gồm plugin provider)

Ví dụ (chỉ cho phép công cụ file + browser):

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

Plugin + công cụ

Plugin có thể đăng ký các công cụ bổ sung (và lệnh CLI) ngoài bộ công cụ cốt lõi. Xem Plugin để cài đặt + cấu hình, và Skills để biết cách hướng dẫn sử dụng công cụ được đưa vào prompt. Một số plugin đi kèm với skill riêng cùng với công cụ (ví dụ: plugin voice-call).

Các công cụ plugin tùy chọn:

Lobster: runtime workflow có kiểu với phê duyệt có thể tiếp tục (yêu cầu Lobster CLI trên gateway host).
LLM Task: bước LLM chỉ JSON cho đầu ra workflow có cấu trúc (xác thực schema tùy chọn).

Danh mục công cụ

`apply_patch`

Áp dụng các patch có cấu trúc trên một hoặc nhiều file. Dùng cho chỉnh sửa nhiều đoạn. Thử nghiệm: bật qua tools.exec.applyPatch.enabled (chỉ model OpenAI).

`exec`

Chạy lệnh shell trong workspace.

Tham số chính:

command (bắt buộc)
yieldMs (tự động chạy nền sau timeout, mặc định 10000)
background (chạy nền ngay lập tức)
timeout (giây; kill process nếu vượt quá, mặc định 1800)
elevated (bool; chạy trên host nếu chế độ elevated được bật/cho phép; chỉ thay đổi hành vi khi agent được sandbox)
host (sandbox | gateway | node)
security (deny | allowlist | full)
ask (off | on-miss | always)
node (node id/name cho host=node)
Cần TTY thật? Đặt pty: true.

Lưu ý:

Trả về status: "running" với sessionId khi chạy nền.
Dùng process để poll/log/write/kill/clear các session nền.
Nếu process không được phép, exec chạy đồng bộ và bỏ qua yieldMs/background.
elevated được kiểm soát bởi tools.elevated cộng với bất kỳ ghi đè agents.list[].tools.elevated nào (cả hai phải cho phép) và là alias cho host=gateway + security=full.
elevated chỉ thay đổi hành vi khi agent được sandbox (nếu không thì nó không làm gì).
host=node có thể nhắm đến ứng dụng companion macOS hoặc node host không giao diện (openclaw node run).
Phê duyệt và allowlist gateway/node: Exec approvals.

`process`

Quản lý các session exec nền.

Các hành động chính:

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

Lưu ý:

poll trả về output mới và trạng thái thoát khi hoàn thành.
log hỗ trợ offset/limit theo dòng (bỏ qua offset để lấy N dòng cuối).
process được phạm vi hóa theo agent; các session từ agent khác không hiển thị.

`web_search`

Tìm kiếm web bằng Brave Search API.

Tham số chính:

query (bắt buộc)
count (1–10; mặc định từ tools.web.search.maxResults)

Lưu ý:

Yêu cầu Brave API key (khuyên dùng: openclaw configure --section web, hoặc đặt BRAVE_API_KEY).
Bật qua tools.web.search.enabled.
Response được cache (mặc định 15 phút).
Xem Web tools để thiết lập.

`web_fetch`

Lấy và trích xuất nội dung có thể đọc từ URL (HTML → markdown/text).

Tham số chính:

url (bắt buộc)
extractMode (markdown | text)
maxChars (cắt ngắn trang dài)

Lưu ý:

Bật qua tools.web.fetch.enabled.
Response được cache (mặc định 15 phút).
Với các trang nhiều JS, nên dùng công cụ browser.
Xem Web tools để thiết lập.
Xem Firecrawl cho fallback chống bot tùy chọn.

`browser`

Điều khiển browser chuyên dụng do OpenClaw quản lý.

Các hành động chính:

status, start, stop, tabs, open, focus, close
snapshot (aria/ai)
screenshot (trả về image block + MEDIA:<path>)
act (hành động UI: click/type/press/hover/drag/select/fill/resize/wait/evaluate)
navigate, console, pdf, upload, dialog

Quản lý profile:

profiles — liệt kê tất cả browser profile với trạng thái
create-profile — tạo profile mới với port tự động phân bổ (hoặc cdpUrl)
delete-profile — dừng browser, xóa dữ liệu người dùng, xóa khỏi config (chỉ local)
reset-profile — kill process mồ côi trên port của profile (chỉ local)

Tham số chung:

profile (tùy chọn; mặc định là browser.defaultProfile)
target (sandbox | host | node)
node (tùy chọn; chọn node id/name cụ thể)

Lưu ý:

Yêu cầu browser.enabled=true (mặc định là true; đặt false để vô hiệu hóa).
Tất cả hành động chấp nhận tham số profile tùy chọn để hỗ trợ nhiều instance.
Khi bỏ qua profile, dùng browser.defaultProfile (mặc định là “chrome”).
Tên profile: chỉ chữ thường, số và dấu gạch ngang (tối đa 64 ký tự).
Phạm vi port: 18800-18899 (~100 profile tối đa).
Profile từ xa chỉ attach (không start/stop/reset).
Nếu node có khả năng browser được kết nối, công cụ có thể tự động định tuyến đến nó (trừ khi bạn ghim target).
snapshot mặc định là ai khi Playwright được cài đặt; dùng aria cho cây accessibility.
snapshot cũng hỗ trợ tùy chọn role-snapshot (interactive, compact, depth, selector) trả về ref như e12.
act yêu cầu ref từ snapshot (số 12 từ AI snapshot, hoặc e12 từ role snapshot); dùng evaluate cho nhu cầu CSS selector hiếm.
Tránh act → wait theo mặc định; chỉ dùng trong trường hợp đặc biệt (không có trạng thái UI đáng tin cậy để đợi).
upload có thể tùy chọn truyền ref để tự động click sau khi chuẩn bị.
upload cũng hỗ trợ inputRef (aria ref) hoặc element (CSS selector) để đặt <input type="file"> trực tiếp.

`canvas`

Điều khiển node Canvas (present, eval, snapshot, A2UI).

Các hành động chính:

present, hide, navigate, eval
snapshot (trả về image block + MEDIA:<path>)
a2ui_push, a2ui_reset

Lưu ý:

Dùng gateway node.invoke bên dưới.
Nếu không cung cấp node, công cụ sẽ chọn mặc định (node được kết nối duy nhất hoặc local mac node).
A2UI chỉ v0.8 (không có createSurface); CLI từ chối JSONL v0.9 với lỗi dòng.
Kiểm tra nhanh: openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI".

`nodes`

Khám phá và nhắm mục tiêu các node đã ghép nối; gửi thông báo; chụp camera/màn hình.

Các hành động chính:

status, describe
pending, approve, reject (pairing)
notify (macOS system.notify)
run (macOS system.run)
camera_snap, camera_clip, screen_record
location_get

Lưu ý:

Lệnh camera/màn hình yêu cầu ứng dụng node ở foreground.
Hình ảnh trả về image block + MEDIA:<path>.
Video trả về FILE:<path> (mp4).
Vị trí trả về payload JSON (lat/lon/accuracy/timestamp).
Tham số run: mảng argv command; tùy chọn cwd, env (KEY=VAL), commandTimeoutMs, invokeTimeoutMs, needsScreenRecording.

Ví dụ (run):

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

`image`

Phân tích hình ảnh với image model đã cấu hình.

Tham số chính:

image (đường dẫn hoặc URL bắt buộc)
prompt (tùy chọn; mặc định là “Describe the image.”)
model (ghi đè tùy chọn)
maxBytesMb (giới hạn kích thước tùy chọn)

Lưu ý:

Chỉ khả dụng khi agents.defaults.imageModel được cấu hình (chính hoặc fallback), hoặc khi image model ngầm định có thể được suy ra từ model mặc định + auth đã cấu hình (ghép nối tốt nhất).
Dùng image model trực tiếp (độc lập với model chat chính).

`message`

Gửi tin nhắn và hành động channel qua Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams.

Các hành động chính:

send (text + media tùy chọn; MS Teams cũng hỗ trợ card cho Adaptive Cards)
poll (WhatsApp/Discord/MS Teams polls)
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

Lưu ý:

send định tuyến WhatsApp qua Gateway; các channel khác đi trực tiếp.
poll dùng Gateway cho WhatsApp và MS Teams; Discord poll đi trực tiếp.
Khi lệnh gọi công cụ message được ràng buộc với chat session đang hoạt động, việc gửi bị giới hạn vào target của session đó để tránh rò rỉ cross-context.

`cron`

Quản lý các cron job và wakeup của Gateway.

Các hành động chính:

status, list
add, update, remove, run, runs
wake (đưa system event vào hàng đợi + heartbeat ngay lập tức tùy chọn)

Lưu ý:

add mong đợi đối tượng cron job đầy đủ (cùng schema với cron.add RPC).
update dùng { id, patch }.

`gateway`

Khởi động lại hoặc áp dụng cập nhật cho process Gateway đang chạy (tại chỗ).

Các hành động chính:

restart (ủy quyền + gửi SIGUSR1 để khởi động lại trong process; openclaw gateway restart tại chỗ)
config.get / config.schema
config.apply (xác thực + ghi config + restart + wake)
config.patch (merge cập nhật một phần + restart + wake)
update.run (chạy update + restart + wake)

Lưu ý:

Dùng delayMs (mặc định 2000) để tránh làm gián đoạn reply đang thực hiện.
restart bị vô hiệu hóa theo mặc định; bật với commands.restart: true.

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

Liệt kê session, kiểm tra lịch sử transcript, hoặc gửi đến session khác.

Tham số chính:

sessions_list: kinds?, limit?, activeMinutes?, messageLimit? (0 = không có)
sessions_history: sessionKey (hoặc sessionId), limit?, includeTools?
sessions_send: sessionKey (hoặc sessionId), message, timeoutSeconds? (0 = fire-and-forget)
sessions_spawn: task, label?, agentId?, model?, runTimeoutSeconds?, cleanup?
session_status: sessionKey? (mặc định hiện tại; chấp nhận sessionId), model? (default xóa ghi đè)

Lưu ý:

main là khóa direct-chat chính thức; global/unknown bị ẩn.
messageLimit > 0 lấy N tin nhắn cuối mỗi session (tin nhắn công cụ được lọc).
sessions_send đợi hoàn thành cuối cùng khi timeoutSeconds > 0.
Giao hàng/thông báo xảy ra sau khi hoàn thành và là best-effort; status: "ok" xác nhận agent run đã hoàn thành, không phải thông báo đã được giao.
sessions_spawn bắt đầu sub-agent run và đăng announce reply trở lại requester chat.
sessions_spawn không chặn và trả về status: "accepted" ngay lập tức.
sessions_send chạy ping-pong reply-back (reply REPLY_SKIP để dừng; số lượt tối đa qua session.agentToAgent.maxPingPongTurns, 0–5).
Sau ping-pong, target agent chạy bước announce; reply ANNOUNCE_SKIP để bỏ qua thông báo.

`agents_list`

Liệt kê các agent id mà session hiện tại có thể nhắm mục tiêu với sessions_spawn.

Lưu ý:

Kết quả bị hạn chế bởi allowlist theo agent (agents.list[].subagents.allowAgents).
Khi ["*"] được cấu hình, công cụ bao gồm tất cả agent đã cấu hình và đánh dấu allowAny: true.

Tham số (chung)

Các công cụ được Gateway hỗ trợ (canvas, nodes, cron):

gatewayUrl (mặc định ws://127.0.0.1:18789)
gatewayToken (nếu auth được bật)
timeoutMs

Công cụ browser:

profile (tùy chọn; mặc định là browser.defaultProfile)
target (sandbox | host | node)
node (tùy chọn; ghim node id/name cụ thể)

Luồng agent được khuyến nghị

Tự động hóa browser:

browser → status / start
snapshot (ai hoặc aria)
act (click/type/press)
screenshot nếu cần xác nhận trực quan

Render canvas:

canvas → present
a2ui_push (tùy chọn)
snapshot

Nhắm mục tiêu node:

nodes → status
describe trên node đã chọn
notify / run / camera_snap / screen_record

An toàn

Tránh system.run trực tiếp; chỉ dùng nodes → run với sự đồng ý rõ ràng của người dùng.
Tôn trọng sự đồng ý của người dùng cho việc chụp camera/màn hình.
Dùng status/describe để đảm bảo quyền trước khi gọi lệnh media.

Cách công cụ được trình bày cho agent

Công cụ được hiển thị qua hai kênh song song:

System prompt text: danh sách có thể đọc được + hướng dẫn.
Tool schema: các định nghĩa hàm có cấu trúc được gửi đến model API.

Điều đó có nghĩa là agent thấy cả “công cụ nào tồn tại” và “cách gọi chúng”. Nếu một công cụ không xuất hiện trong system prompt hoặc schema, model không thể gọi nó.

Tools (OpenClaw)

Vô hiệu hóa công cụ

Tool profiles (danh sách cho phép cơ bản)

Chính sách công cụ theo provider

Tool groups (viết tắt)

Plugin + công cụ

Danh mục công cụ

apply_patch

exec

process

web_search

web_fetch

browser

canvas

nodes

image

message

cron

gateway

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

agents_list

Tham số (chung)

Luồng agent được khuyến nghị

An toàn

Cách công cụ được trình bày cho agent

`apply_patch`

`exec`

`process`

`web_search`

`web_fetch`

`browser`

`canvas`

`nodes`

`image`

`message`

`cron`

`gateway`

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

`agents_list`