Capability System

What Is a Capability

A Capability is a C-layer callable tool registered in the claw_cap system. Each Capability has a unique string id, a JSON input schema, and an execute function. The LLM calls Capabilities directly through the tool-use interface; developers can also invoke them via:

• AT command: AT+CLAW=cap,<id>[,<json_args>]

• Lua script: cap.call("id", json_string) using the cap Lua module

• Internal code: claw_cap_call() C API

Capability Groups and Gating

Capabilities are organized into groups (cap_groups). Most groups are always visible to the LLM. Some groups are gated — hidden by default and unlocked only after the corresponding Skill is activated. This forces the LLM to acquire the right context before calling hardware-specific or resource-intensive tools.

Group	Gate Skill	Capabilities in the Group
files	(always visible)	file_read, file_write, file_delete, file_list, file_move, file_copy, file_stat
skill_mgr	(always visible)	skill_list, skill_activate, skill_save, skill_delete, skill_deactivate
lua	(always visible)	lua_run, lua_run_async, lua_job_get, lua_job_list, lua_job_stop
scheduler	(always visible)	scheduler_add_job, scheduler_list_jobs, scheduler_remove_job, scheduler_enable_job, scheduler_disable_job
system	(always visible)	get_heap_info, get_task_list, get_info, get_wifi, get_ip, restart
time	(always visible)	get_current_time, sync_time
http_request	(always visible)	http_request
net_discover	(always visible)	net_discover_start, net_discover_stop, net_discover_peer
vision	(always visible)	vision_describe
web_search	(always visible)	web_search
im_local / im_telegram / etc.	(always visible)	local_send_text, telegram_send_text, feishu_send_message, wechat_send_text, qq_send_message, im_send_media
board	board_hardware_info (activate first)	board_list_devices, board_get_device, board_query_peripheral, board_schema, board_reload
audio_stream	camera_capture (activate first)	audio_stream_start, audio_stream_tx_start, audio_stream_rx_start, audio_stream_stop, audio_stream_pause, audio_stream_status

Capability Quick Reference

File Management

Capability	Description
file_read	Read file contents from vfs:/ or rolfs:/
file_write	Write or append file contents
file_delete	Delete a file (stops running Lua jobs using that path first)
file_list	List files and subdirectories at a path
file_move	Move or rename a file
file_copy	Copy a file to a new path
file_stat	Get file metadata (size, type, modification time)

Skill Management

Capability	Description
skill_list	List all available Skills (built-in + user)
skill_activate	Activate a Skill for the current session; injects its SKILL.md context and unlocks its cap_groups
skill_save	Save a new user Skill (SKILL.md + optional scripts/main.lua)
skill_delete	Delete a user-created Skill directory
skill_deactivate	Deactivate a Skill from the session activation list

Lua Execution

Capability	Description
lua_run	Execute a Lua script synchronously; returns the run() return value + captured print() output
lua_run_async	Start a Lua script as a background job; returns job_id immediately
lua_job_get	Get a background job’s status and incremental log output (since_seq)
lua_job_list	List all background Lua jobs with their status
lua_job_stop	Cooperatively stop a running background job

Scheduler

Capability	Description
scheduler_add_job	Add or update a scheduled job (supports event_type, delay_sec, interval_sec, cron)
scheduler_list_jobs	List all scheduled jobs
scheduler_remove_job	Remove a scheduled job by ID
scheduler_enable_job	Enable a previously disabled job
scheduler_disable_job	Disable a job without removing it

Board Hardware (requires activating ``board_hardware_info`` first)

Capability	Description
board_list_devices	List all devices wired on the board (sensors, displays, etc.)
board_get_device	Get full details for a device: chip, interface pin assignments, driver params
board_query_peripheral	Check whether a peripheral type is available and which pins/instances are free
board_schema	Get the board authoring schema (chip definitions, constraints)
board_reload	Reload the board.json configuration from VFS

System Information

Capability	Description
get_heap_info	Get free heap and historical minimum
get_task_list	List all FreeRTOS tasks with state, priority, and stack watermark
get_info	Get chip model, firmware version, uptime
get_wifi	Get Wi-Fi SSID, channel, RSSI, IP address
restart	Soft-reset the device after a short delay

Time

Capability	Description
get_current_time	Get current wall-clock datetime (UTC+8) and Unix timestamp
sync_time	Trigger SNTP sync and write the result to the system clock and RTC

Network

Capability	Description
http_request	Send HTTP/HTTPS request (GET/POST/PUT/PATCH/DELETE/HEAD); returns status code and body
net_discover_start	Start persistent UDP broadcast/listen peer-discovery; fires callbacks on peers found/lost
net_discover_stop	Stop the peer-discovery background service
net_discover_peer	One-shot peer discovery (blocks until found or timeout)

Audio Streaming (requires activating ``camera_capture`` first)

Capability	Description
audio_stream_start	Start both RX (UDP→speaker) and TX (DMIC→UDP) streams in one call
audio_stream_tx_start	Start DMIC-to-UDP streaming (push-to-talk gated in C layer)
audio_stream_rx_start	Start UDP-to-speaker reception; call before TX
audio_stream_stop	Stop both TX and RX stream tasks
audio_stream_status	Get TX/RX running state and UDP packet counters

AT Command Interface

List all registered Capabilities:

AT+CLAW=cap

List all installed Skills (calls the skill_list Capability):

AT+CLAW=cap,skill_list

Call a Capability with JSON arguments:

AT+CLAW=cap,<capability_id>,<json_args>

Examples:

AT+CLAW=cap,get_info
AT+CLAW=cap,file_list,{"path":"vfs:/skills/"}
AT+CLAW=cap,lua_run,{"path":"vfs:/tmp/test.lua","args":{}}
AT+CLAW=cap,skill_activate,{"name":"board_hardware_info"}

To target a specific session (for per-session cap_groups visibility):

AT+CLAW=cap,<capability_id>,<json_args>,sid,<session_id>

Calling Capabilities from Lua Scripts

Use the cap Lua module inside Skill scripts. cap.call always returns two values:

local cap   = require("cap")
local cjson = require("cjson")

-- Correct: capture both ok (boolean) and result_json (string)
local ok, result_json = cap.call("get_current_time", "{}")
if not ok then
    return '{"error":' .. (result_json or '"cap call failed"') .. '}'
end
local t = cjson.decode(result_json)
-- t.timestamp, t.datetime, etc.

-- Incorrect: captures only ok (the boolean true/false), discards the JSON payload
-- local result = cap.call("get_current_time", "{}")  -- never do this