Agent Core

职责

claw_core 实现设备侧的 Agent 核心：收到包含「用户说了什么、来自哪个会话与通道」的消息后，在独立任务里完成上下文拼装、调用大语言模型、解析 Tool Call、再通过统一入口执行能力，并按配置迭代多轮，直到模型给出最终文本或出错。

请求结构

claw_core_request_t 包含单次交互所需的全部元数据，例如：

session_id：会话标识（Console 里 session 命令会切换当前会话；IM 路由也会按策略生成会话 id）。
user_text：用户输入正文。
source_* / target_*：来源通道、聊天 id、消息 id、来源 cap 等。这些字段会原样传入 claw_cap_call_from_core，以便在 Capability 层定向回复或关联上下文。

应用通过 claw_core_submit 投递请求，用 claw_core_receive / claw_core_receive_for 取回 claw_core_response_t。 claw_core_response_t 包含助手回复正文（text 字段）与错误信息（error_message）。

请求标志

claw_core_request_t.flags 支持以下标志位的组合：

标志	说明
`CLAW_CORE_REQUEST_FLAG_PUBLISH_OUT_MESSAGE`	Agent 完成推理后，将响应以 `out_message` 事件发布到 Event Router
`CLAW_CORE_REQUEST_FLAG_SKIP_RESPONSE_QUEUE`	跳过响应队列，不通过 `claw_core_receive` 返回结果
`CLAW_CORE_REQUEST_FLAG_USER_INTERRUPT`	标记本次请求为用户打断（中止前一个请求后发起的新请求）

Event Router 的 run_agent 动作会同时设置前两个标志，实现异步提交 + 事件发布的响应路径。

在拼装发往大语言模型的当前轮用户提示时，claw_core 会附带一段 Behavior Notes，说明最终助手结果通常会由框架自动投递给用户，因此一般不必再主动调用 cap_im_platform 中的 IM 发送接口返回正文（减少重复回复）。

上下文拼接

claw_core 支持挂接多个 context provider（claw_core_context_provider_t）。每个 provider 在收集阶段往 claw_core_context_t 里填一块内容，类型由 claw_core_context_kind_t 区分，包括：

CLAW_CORE_CONTEXT_KIND_SYSTEM_PROMPT
CLAW_CORE_CONTEXT_KIND_MESSAGES
CLAW_CORE_CONTEXT_KIND_TOOLS

edge_agent 在 app_claw_start 里按固定顺序挂了多个 provider：

可编辑人设与画像：claw_memory_profile_provider
长期记忆：claw_memory_long_term_provider（完整模式）或 claw_memory_long_term_lightweight_provider（轻量模式）
会话历史：claw_memory_session_history_provider
Skills 目录清单：claw_skill_skills_list_provider
当前可见工具列表：claw_cap_tools_provider

因此：大语言模型最终接收的工具列表，不仅取决于注册了哪些 Capability，还取决于 claw_cap_set_llm_visible_groups。

缓存命中率优化设计

claw_core 的上下文拼接顺序经过设计，以最大化 LLM API 的缓存命中率。

设计原则

LLM API（如 Anthropic、OpenAI）的缓存基于前缀匹配。因此，ESP-Claw 在最近的版本中尝试减少提示词前部内容变更频率。

Skill 文档注入的变更

早期设计中，已激活的 Skill 文档通过独立的 context provider (claw_skill_active_skill_docs_provider) 注入 system prompt。每次 Skill 激活/停用都会改变 system prompt 内容，导致缓存失效。

当前设计移除了该 provider，改为通过 activate_skill 工具的返回值将 Skill 文档注入会话历史。这确保 system prompt 较为稳定，缓存前缀不受 Skill 激活状态影响。

工具调用

claw_core 通过回调处理大语言模型发出的工具调用请求。

edge_agent 的 call_cap 回调指向 claw_cap_call_from_core，该函数由 claw_cap 提供。 claw_core 只基于「能力名 + JSON 参数 + 当前请求上下文」接受调用工具的指令，但不负责查找对应的 Capability 实现与执行。 Capability 的解析与执行工作由 claw_cap 负责。

一轮里允许的工具轮数由 max_tool_iterations 限制。

上下文持久化

claw_core 通过 typed record batch 回调持久化可回放的上下文记录。

edge_agent 中，persist_context 设为 claw_memory_persist_context_callback，该函数由 claw_memory 提供。 claw_core 会在普通轮次、中间工具轮、最终助手记录和失败说明等时机触发回调，将按 session_id 分区的上下文记录交由 claw_memory 处理。

请求取消

claw_core_cancel_request(request_id) 用于取消当前正在执行的请求：

request_id == 0：取消任意当前 in-flight 请求。
request_id != 0：仅当当前 in-flight 请求 ID 匹配时才生效。
若没有可取消的请求，返回 ESP_ERR_NOT_FOUND。

该取消是协作式中断，主要用于中止进行中的 LLM HTTP 请求；请求结束后，错误信息会被统一标记为 request cancelled，便于上层识别。

完成观察器

claw_core_add_completion_observer 允许注册完成观察器，在每次请求结束后接收 claw_core_completion_summary_t：

request_id / session_id：请求与会话标识。
final_text：本轮最终回复文本（可能为空）。
context_providers_csv：本轮注入了非空上下文的 provider 列表（CSV）。
tool_calls_csv：本轮触发过的工具调用列表（CSV）。

该机制适合做审计、统计或“结果一致性”检查（例如检测某些声明是否伴随了对应工具调用）。

初始化错误处理

app_claw_start 会在 API Key、backend_type、model 不全时跳过 claw_core_init / claw_core_start，并打印日志。

此时依赖大语言模型的 ask、Event Router 发往 Agent 的路由（含 fallback 路由）、图片 inspect 等能力不可用。但 Event Router、自动化、本地 Capability、Console REPL 仍可工作。

启动与运行时装配查看完整的 core 初始化流程与条件判断逻辑

配置项

claw_core_config_t 中常见字段含义：

backend_type / model / base_url / auth_type / max_tokens_field / timeout_ms / max_tokens：对接不同大语言模型供应商时的路由与鉴权（具体支持的后端在 claw_core_llm 与 llm/backends 下实现）。
system_prompt：系统提示词，必填（claw_core_init 会校验此字段非空）。
supports_tools / supports_vision / image_remote_url_only：是否支持工具调用、视觉输入和仅远程 URL 图像。
image_max_bytes：传入 LLM 层的图像/媒体大小上限。
request_gate：可选的请求门控回调，在请求处理前拦截或拒绝请求。
task_stack_size、task_priority、task_core：后台 Agent 任务在 FreeRTOS 上的资源。
request_queue_len、response_queue_len：请求/响应队列深度。
max_context_providers：最多可注册的 provider 数量。