Capabilities overview

What is a capability?

A capability is the uniform abstraction for anything callable in ESP-Claw. Each cap_* component registers one or more metadata-rich descriptors (claw_cap_descriptor_t) with claw_cap, and all execution funnels through the shared dispatcher.

Capabilities can play three roles:

Role	kind	Meaning
Callable tool	CLAW_CAP_KIND_CALLABLE	JSON in, text out; invokable from the LLM, Console, or automation
Event source	CLAW_CAP_KIND_EVENT_SOURCE	Long-lived producer feeding claw_event_router
Hybrid	CLAW_CAP_KIND_HYBRID	Both callable and event emitting

Descriptors are grouped into capability groups (claw_cap_group_t)—the smallest unit for registration, start/stop, and LLM visibility toggles.

Built-in taxonomy

Family	Components	Notes
IM ingress	cap_im_*	Chat platforms as both event sources and send helpers
Filesystem	cap_files	Managed FATFS CRUD + listing
Lua	cap_lua	Author, sync/async run, and track Lua jobs
Skill admin	cap_skill	Register/unregister/activate/deactivate Skills (core as tools)
LLM inspect	cap_llm_inspect	Nested multimodal calls over local images
Web search	cap_web_search	External search APIs
Time	cap_time	Device clock queries
System info	cap_system	Query system/memory/CPU/Wi-Fi/IP status and support operational actions like restart
Scheduler	cap_scheduler	Cron-like scheduling
Router admin	cap_router_mgr	Dynamic Event Router rule maintenance
MCP	cap_mcp_*	Model Context Protocol client/server
CLI	cap_cli	Surface caps through terminal helpers
Sessions	cap_session_mgr	Session state persistence

Group registration

Every cap_* exposes cap_xxx_register_group() for the app to call during init:

// cap_files example
esp_err_t cap_files_register_group(void)
{
    if (claw_cap_group_exists(s_files_group.group_id)) {
        return ESP_OK;
    }
    return claw_cap_register_group(&s_files_group);
}

claw_cap_register_group enforces unique group ids, runs descriptor init hooks, then finishes registration. claw_cap_start_group later invokes start (e.g. launching the Telegram poll task).

LLM visibility

Not every registered group is visible to the model. claw_cap_set_llm_visible_groups applies an allow-list controlling which tool schemas enter context:

// Typical boot policy: only baseline tools
static const char *VISIBLE_GROUPS[] = { "cap_files", "cap_skill", "cap_system" };
claw_cap_set_llm_visible_groups(VISIBLE_GROUPS, 3);

Other groups remain callable from the Console or automation; activating Skills expands the LLM-facing set.

Tip

Why not expose everything?

Dumping every tool description balloons tokens, hurting quality, latency, and cost. Skills implement progressive disclosure: humans (or the LLM) activate only the guides—and tool metadata—they need for the current task.

Call paths

Three primary entry points:

1. LLM tool calls: claw_core → claw_cap_call_from_core (session/channel aware)
2. Console: cap call <name> <json> for direct execution
3. Event Router rules: call_cap actions (see Dataflow and automation)

claw_cap_call_context_t.caller records whether the invoker was SYSTEM, AGENT, or CONSOLE.

Deep dives

How to implement a capability Authoring a `cap_*` component end-to-end

cap_im_tg IM reference: event source + callable sends

cap_skill Core-surface reference: `claw_skill` as tools

cap_llm_inspect LLM-interaction reference: nested inference

cap_files Filesystem reference: managed-tree CRUD

cap_system System-state reference: inspect runtime status and support safe restart

cap_scheduler Scheduling reference: time-based event triggering and periodic tasks

cap_lua and Lua overview Lua tooling plus where scripts fit in the stack

Lua extension modules Registering `lua_module_*`, custom modules, `display` deep dive