Công cụ và Plugin

Mọi việc agent thực hiện ngoài việc tạo văn bản đều diễn ra thông qua công cụ. Công cụ là cách agent đọc tệp, chạy lệnh, duyệt web, gửi tin nhắn và tương tác với thiết bị.

# Công cụ, Skills và Plugin

OpenClaw có ba lớp phối hợp với nhau:

# Công cụ tích hợp sẵn

Các công cụ này được phát hành cùng OpenClaw và có sẵn mà không cần cài đặt Plugin nào:

Công cụ	Chức năng	Trang
exec / process	Chạy lệnh shell, quản lý tiến trình nền	Exec, Phê duyệt Exec
code_execution	Chạy phân tích Python từ xa trong sandbox	Thực thi mã
browser	Điều khiển trình duyệt Chromium (điều hướng, nhấp, chụp màn hình)	Trình duyệt
web_search / x_search / web_fetch	Tìm kiếm web, tìm kiếm bài đăng X, lấy nội dung trang	Web, Lấy dữ liệu Web
read / write / edit	I/O tệp trong workspace
apply_patch	Bản vá tệp nhiều hunk	Áp dụng bản vá
message	Gửi tin nhắn trên mọi kênh	Agent gửi
canvas	Điều khiển Canvas node (trình bày, đánh giá, chụp snapshot)
nodes	Phát hiện và nhắm mục tiêu các thiết bị đã ghép nối
cron / gateway	Quản lý công việc đã lên lịch; kiểm tra, vá, khởi động lại hoặc cập nhật gateway
image / image_generate	Phân tích hoặc tạo hình ảnh	Tạo hình ảnh
music_generate	Tạo bản nhạc	Tạo nhạc
video_generate	Tạo video	Tạo video
tts	Chuyển văn bản thành giọng nói một lần	TTS
sessions_* / subagents / agents_list	Quản lý phiên, trạng thái và điều phối sub-agent	Sub-agent
session_status	Đọc lại nhẹ kiểu /status và ghi đè mô hình phiên	Công cụ phiên

Đối với tác vụ hình ảnh, dùng image để phân tích và image_generate để tạo hoặc chỉnh sửa. Nếu bạn nhắm tới openai/*, google/*, fal/*, hoặc một nhà cung cấp hình ảnh không mặc định khác, hãy cấu hình khóa xác thực/API của nhà cung cấp đó trước.

Đối với tác vụ âm nhạc, dùng music_generate. Nếu bạn nhắm tới google/*, minimax/*, hoặc một nhà cung cấp âm nhạc không mặc định khác, hãy cấu hình khóa xác thực/API của nhà cung cấp đó trước.

Đối với tác vụ video, dùng video_generate. Nếu bạn nhắm tới qwen/* hoặc một nhà cung cấp video không mặc định khác, hãy cấu hình khóa xác thực/API của nhà cung cấp đó trước.

Đối với tạo âm thanh theo workflow, dùng music_generate khi một Plugin như ComfyUI đăng ký công cụ này. Công cụ này tách biệt với tts, vốn là chuyển văn bản thành giọng nói.

session_status là công cụ trạng thái/đọc lại nhẹ trong nhóm phiên. Nó trả lời các câu hỏi kiểu /status về phiên hiện tại và có thể tùy chọn đặt ghi đè mô hình cho từng phiên; model=default xóa ghi đè đó. Giống như /status, nó có thể điền ngược các bộ đếm token/cache thưa và nhãn mô hình runtime đang hoạt động từ mục usage transcript mới nhất.

gateway là công cụ runtime chỉ dành cho chủ sở hữu cho các thao tác gateway:

• config.schema.lookup cho một cây con cấu hình theo phạm vi đường dẫn trước khi chỉnh sửa
• config.get cho snapshot cấu hình hiện tại + hash
• config.patch cho cập nhật cấu hình một phần kèm khởi động lại
• config.apply chỉ dành cho thay thế toàn bộ cấu hình
• update.run cho tự cập nhật + khởi động lại rõ ràng

Đối với thay đổi một phần, ưu tiên config.schema.lookup rồi config.patch. Chỉ dùng config.apply khi bạn cố ý thay thế toàn bộ cấu hình. Để xem tài liệu cấu hình rộng hơn, đọc Cấu hình và Tham chiếu cấu hình. Công cụ này cũng từ chối thay đổi tools.exec.ask hoặc tools.exec.security; các alias cũ tools.bash.* được chuẩn hóa về cùng các đường dẫn exec được bảo vệ.

# Công cụ do Plugin cung cấp

Plugin có thể đăng ký thêm công cụ. Một số ví dụ:

• Diff — trình xem và trình render diff
• Tác vụ LLM — bước LLM chỉ xuất JSON cho đầu ra có cấu trúc
• Lobster — runtime workflow có kiểu với phê duyệt có thể tiếp tục
• Tạo nhạc — công cụ music_generate dùng chung với các nhà cung cấp dựa trên workflow
• OpenProse — điều phối workflow ưu tiên markdown
• Tokenjuice — thu gọn kết quả công cụ exec và bash nhiễu

Công cụ Plugin vẫn được tạo bằng api.registerTool(...) và khai báo trong danh sách contracts.tools của manifest Plugin. OpenClaw ghi lại mô tả công cụ đã xác thực trong quá trình phát hiện và lưu cache theo nguồn Plugin và contract, để việc lập kế hoạch công cụ sau này có thể bỏ qua việc tải runtime Plugin. Thực thi công cụ vẫn tải Plugin sở hữu và gọi implementation đã đăng ký trực tiếp.

# Cấu hình công cụ

# Danh sách cho phép và từ chối

Kiểm soát công cụ nào agent có thể gọi thông qua tools.allow / tools.deny trong config. Từ chối luôn thắng cho phép.

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

OpenClaw mặc định đóng khi một allowlist rõ ràng không phân giải được công cụ nào có thể gọi. Ví dụ, tools.allow: ["query_db"] chỉ hoạt động nếu một Plugin đã tải thực sự đăng ký query_db. Nếu không có công cụ tích hợp sẵn, Plugin hoặc công cụ MCP đóng gói nào khớp với allowlist, lần chạy dừng trước lệnh gọi mô hình thay vì tiếp tục như một lần chạy chỉ văn bản có thể bịa ra kết quả công cụ.

# Hồ sơ công cụ

tools.profile đặt allowlist cơ sở trước khi áp dụng allow/deny. Ghi đè theo từng agent: agents.list[].tools.profile.

Hồ sơ	Nội dung bao gồm
full	Tất cả công cụ lõi và công cụ Plugin tùy chọn; đường cơ sở không hạn chế cho quyền truy cập lệnh/điều khiển rộng hơn
coding	group:fs, group:runtime, group:web, group:sessions, group:memory, cron, image, image_generate, music_generate, video_generate
messaging	group:messaging, sessions_list, sessions_history, sessions_send, session_status
minimal	Chỉ session_status

coding bao gồm các công cụ web nhẹ (web_search, web_fetch, x_search) nhưng không bao gồm công cụ điều khiển trình duyệt đầy đủ. Tự động hóa trình duyệt có thể điều khiển các phiên thật và hồ sơ đã đăng nhập, vì vậy hãy thêm rõ ràng bằng tools.alsoAllow: ["browser"] hoặc theo từng agent agents.list[].tools.alsoAllow: ["browser"].

Các hồ sơ coding và messaging cũng cho phép các công cụ bundle MCP đã cấu hình dưới khóa Plugin bundle-mcp. Thêm tools.deny: ["bundle-mcp"] khi bạn muốn một hồ sơ giữ các công cụ tích hợp sẵn thông thường nhưng ẩn tất cả công cụ MCP đã cấu hình. Hồ sơ minimal không bao gồm công cụ bundle MCP.

Ví dụ (bề mặt công cụ rộng nhất theo mặc định):

{
  tools: {
    profile: "full",
  },
}

# Nhóm công cụ

Dùng cách viết tắt group:* trong danh sách cho phép/từ chối:

Nhóm	Công cụ
group:runtime	exec, process, code_execution (bash được chấp nhận làm bí danh cho exec)
group:fs	read, write, edit, apply_patch
group:sessions	sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
group:memory	memory_search, memory_get
group:web	web_search, x_search, web_fetch
group:ui	browser, canvas
group:automation	heartbeat_respond, cron, gateway
group:messaging	message
group:nodes	nodes
group:agents	agents_list, update_plan
group:media	image, image_generate, music_generate, video_generate, tts
group:openclaw	Tất cả công cụ OpenClaw tích hợp sẵn (không bao gồm công cụ Plugin)

sessions_history trả về một chế độ xem truy hồi có giới hạn và được lọc an toàn. Nó loại bỏ các thẻ suy nghĩ, khung dựng <relevant-memories>, payload XML lời gọi công cụ dạng văn bản thuần (bao gồm <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> và các khối lời gọi công cụ bị cắt ngắn), khung dựng lời gọi công cụ đã hạ cấp, các token điều khiển mô hình ASCII/toàn độ rộng bị rò rỉ, và XML lời gọi công cụ MiniMax sai định dạng khỏi văn bản của trợ lý, sau đó áp dụng biên tập che giấu/cắt ngắn và các placeholder có thể có cho hàng quá khổ thay vì hoạt động như một bản đổ transcript thô.

# Hạn chế theo nhà cung cấp

Dùng tools.byProvider để giới hạn công cụ cho các nhà cung cấp cụ thể mà không thay đổi mặc định toàn cục:

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