Agent 运行时

Agent（智能体）是 OpenClaw 的核心 AI 实体，负责接收消息、处理上下文并执行工具调用。每个 Agent 拥有独立的工作区、会话状态与工具策略。

核心概念

Agent 是一个有状态的消息处理器。它从消息队列中读取用户输入，结合系统提示词（System Prompt）与工具定义，调用大语言模型（LLM）生成回复或执行动作。

快速理解

Agent = 系统提示词 + 工具集 + 模型 + 会话状态。改变其中任一项都会改变 Agent 的行为。

工作区文件

Agent 通过工作区中的 Markdown 文件获取指令与上下文：

文件	用途
AGENTS.md	智能体行为指令（Instructions）
SOUL.md	人格定义（Personality）
TOOLS.md	工具定义（Tool Definitions）
IDENTITY.md	身份信息
USER.md	用户画像
HEARTBEAT.md	心跳任务
BOOTSTRAP.md	引导上下文
MEMORY.md	长期记忆

文件加载顺序

工作区文件在每次 Agent 运行时注入系统提示词。子 Agent（Sub-agent）仅接收 AGENTS.md 和 TOOLS.md。

转向模式（Steering Modes）

Agent 支持三种消息队列处理模式：

# 转向模式配置
steering: steer      # 默认：逐条处理，每条消息触发一次 LLM 调用
steering: followup   # 追加模式：将后续消息追加到当前对话
steering: collect    # 收集模式：等待一段时间后批量处理

• steer — 标准模式，每条消息独立处理
• followup — 后续消息作为追加上下文发送
• collect — 在指定时间窗口内收集消息后一次性处理

模型引用格式

Agent 使用 provider/model-name 格式引用模型，按第一个斜杠分割：

单模型配置

model: openai/gpt-4o

带 Failover 配置

model: openai/gpt-4o
failover:
  - anthropic/claude-3-5-sonnet
  - google/gemini-2.0-flash

格式注意

模型名称中可能包含多个斜杠（如 azure/deployments/gpt-4o），解析时仅按第一个 / 分割 provider 和 model name。

技能加载（Skills Loading）

Skills（技能）按以下优先级加载：

1. Bundled Skills     → 内置技能（随 OpenClaw 发布）
2. Managed Skills     → ~/.openclaw/skills/（用户管理的技能）
3. Workspace Skills   → /skills/（工作区本地技能）

每个 Skill 是一个目录，包含 SKILL.md 定义文件和可选的工具脚本。

Bootstrap 文件

Bootstrap（引导）文件在 Agent 启动时注入上下文。可通过配置跳过：

# 跳过 Bootstrap 注入
skipBootstrap: true

默认情况下，所有工作区文件都会作为 "Project Context" 注入系统提示词。

流式输出控制

# 默认阻止流式输出（适合某些渠道）
blockStreamingDefault: true

# 分块配置（Chunking）
chunking:
  enabled: true
  maxChunkSize: 1000

渠道差异

WhatsApp 等平台不支持流式输出，需设置 blockStreamingDefault: true。Web UI 和 Telegram 可使用流式输出提升体验。

工具策略（Tool Policies）

Tool Policies 控制工具的执行权限：

toolPolicies:
  file_write:
    permission: ask       # 每次执行前询问用户
  web_search:
    permission: allow     # 始终允许
  shell_exec:
    permission: deny      # 禁止执行

转录存储（Transcripts）

Agent 的对话历史以 JSONL（JSON Lines）格式存储，每行一条消息记录：

~/.openclaw/sessions/<session-key>/transcript.jsonl

会话元数据保存在 sessions.json 中，包含会话 ID、创建时间与最后活跃时间。

🇨🇳 中国用户须知

• 推荐搭配国产模型使用，如 deepseek/deepseek-chat 或 zhipu/glm-4
• 工作区文件支持中文内容，SOUL.md 中可用中文定义人格
• 流式输出在国内网络环境下建议启用分块（Chunking）以提升稳定性

下一步

• 了解 Agent 循环 的消息处理流程
• 配置 Agent 工作区
• 探索 系统提示词 的构建方式