Agent 与 Agent Loop

Agent 是什么

OpenClaw 运行一个内嵌的 AI Agent 运行时（派生自 pi-mono）。Agent 负责：

• 接收用户消息
• 决定调用哪些工具
• 执行工具并观察结果
• 生成最终回复

工作区（必须配置）

Agent 使用一个目录作为工作区（agents.defaults.workspace），这是所有工具操作的唯一工作目录（cwd）。

推荐初始化：

openclaw setup

这会创建 ~/.openclaw/openclaw.json（如果不存在）并初始化工作区文件。

启动文件（Bootstrap Files）

首次启动新会话时，OpenClaw 会将工作区中的以下文件内容注入 Agent 上下文：

文件	作用
AGENTS.md	操作指令 + 持久"记忆"
SOUL.md	角色人格、边界、语气
TOOLS.md	工具使用规范（用户维护）
IDENTITY.md	Agent 名字/风格/emoji
USER.md	用户档案 + 称呼偏好
BOOTSTRAP.md	首次运行仪式（完成后删除）

• 空文件会被跳过
• 超长文件会被截断（附带截断标记），读完整内容用 read 工具
• 文件缺失时注入一行"缺失文件"提示标记
• BOOTSTRAP.md 只在全新工作区创建（其他 bootstrap 文件都不存在时）

禁用 Bootstrap 文件创建（预置工作区用）：

{ agent: { skipBootstrap: true } }

Agent Loop（运行循环）

Agent 按如下循环运行，直到模型不再调用工具为止：

1. 构建消息（系统提示 + 用户消息 + 历史）
2. 调用 AI 模型
3. 如果模型输出工具调用 → 执行工具 → 回到第 2 步
4. 如果模型输出纯文本 → 发送回复，结束

队列模式

当 Agent 正在处理消息时，新消息根据 queue.mode 处理：

• steer：新消息注入当前运行（每次工具调用后检查），可打断当前工具链
• followup：新消息等到当前轮结束，然后开始新轮
• collect（推荐）：收集多条消息合并后再处理，防止刷屏触发多次运行

{
  routing: {
    queue: {
      mode: "collect",
      debounceMs: 1000,  // 等 1 秒，收集快速连续的消息
      cap: 20,
    },
  },
}

流式回复

blockStreaming（块流式）让 Agent 在生成每个文本块时就发送，而非等待全文完成：

{
  agents: {
    defaults: {
      blockStreamingDefault: "off",  // off | on
      blockStreamingBreak: "text_end",  // text_end | message_end
      blockStreamingChunk: {
        minChars: 800,
        maxChars: 1200,
        breakPreference: "paragraph",  // paragraph | newline | sentence
      },
    },
  },
}

内置工具

Agent 始终可用以下核心工具（受 tool policy 约束）：

工具	功能
read	读取文件
write	写入文件
edit	编辑文件（精确替换）
exec	执行 Shell 命令
process	后台进程管理
apply_patch	应用 diff 补丁（可选）
browser	控制浏览器（可选）
memory_search	语义检索记忆
memory_get	读取特定记忆文件

Skills（技能）

Skills 是教 Agent 如何使用外部工具的 Markdown 文件夹。加载位置优先级（高→低）：

1. <workspace>/skills（工作区专属）
2. ~/.openclaw/skills（本机共享）
3. 内置 Skills（随安装包附带）

# 从 ClawHub 安装 Skill
clawhub install <skill-slug>

多 Agent 配置

可以运行多个 Agent，每个有独立工作区和会话：

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "slack" } },
  ],
}

模型引用格式

模型以 provider/model 格式引用：

• anthropic/claude-opus-4-6
• openai/gpt-5.4
• openrouter/anthropic/claude-sonnet-4-5（含 / 的模型 ID）

引用按第一个 / 分割：前缀是 provider，后面是 model ID（可包含 /）。