---
title: Agent Core
description: Agent 任务、上下文提供器、与大语言模型/工具的交互边界。
---

import LinkToSource from '@/components/LinkToSource.astro';
import { LinkCard, Aside } from '@astrojs/starlight/components';

头文件：<LinkToSource relativePath="components/claw_modules/claw_core/include/claw_core.h" />

## 职责

`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` 返回结果 |

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

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

<Aside type="tip" title="输出详细 Agent 工具调用过程">
    `claw_core` 支持输出详细 Agent 工具调用过程。
    如需启用，详见 [数据流与自动化](@lang/reference-project/dataflow-and-automation#agent_stage-事件与执行过程通知)。
</Aside>

## 上下文拼接

`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：

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

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

<Aside type="tip">
    `edge_agent` 默认只对大语言模型暴露 `cap_files`、`cap_skill`、`cap_system`、`cap_lua`（完整结构化记忆模式还包含 `claw_memory`）。其余能力通常需要先激活对应 Skill，模型才能同时获得「工具可见性 + 使用说明」——详见 [claw_cap](./claw-cap) 与 [cap_skill](@lang/reference-cap/cap-skill)
</Aside>

## 工具调用

`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_session` 设为 `claw_memory_persist_session_callback`，该函数由 `claw_memory` 提供。
`claw_core` 会在普通轮次、中间工具轮、最终助手记录和失败说明等时机触发回调，将会话记录交由 `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、profile、model 不全时跳过 `claw_core_init` / `claw_core_start`，并打印日志。

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

<LinkCard title="启动与运行时装配" href="@lang/reference-project/boot-and-runtime" description="查看完整的 core 初始化流程与条件判断逻辑" />

## 配置项

`claw_core_config_t` 中常见字段含义：

- `profile` / `provider` / `backend_type` / `model` / `base_url` / `auth_type` / `timeout_ms`：对接不同大语言模型供应商时的路由与鉴权（具体支持的后端在 `claw_core_llm` 与 `llm/backends` 下实现）。`profile` 与 `provider` 二选一即可。
- `system_prompt`：系统提示词，必填（`claw_core_init` 会校验此字段非空）。
- `image_max_bytes`：传入 LLM 层的图像/媒体大小上限。
- `task_stack_size`、`task_priority`、`task_core`：后台 Agent 任务在 FreeRTOS 上的资源。
- `request_queue_len`、`response_queue_len`：请求/响应队列深度。
- `max_context_providers`：最多可注册的 provider 数量。
