跳转至

智能体运行时

OpenClaw 内置一个嵌入式代理运行时:一个内置代理循环、工具接线和提示词组装,区别于将轮次委托给外部 harness 进程。每个已配置的代理(运行多个代理请参见 多代理路由)都有自己的工作区、引导文件和会话存储。本页介绍该运行时契约:工作区必须包含什么、哪些文件会被注入,以及会话如何基于它进行引导。

工作区(必需)

每个代理使用单一工作区目录(agents.defaults.workspace,或每个代理的 agents.entries.*.workspace)作为其唯一工作目录(cwd),用于工具和上下文。

建议:如果缺失,请使用 openclaw setup 创建 ~/.openclaw/openclaw.json 并初始化工作区文件。

完整工作区布局 + 备份指南:代理工作区

如果启用了 agents.defaults.sandbox,非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的每会话工作区来覆盖此设置(参见 网关配置)。

引导文件(注入)

在工作区内,OpenClaw 期望存在以下用户可编辑文件:

文件 用途
AGENTS.md 操作说明 + “记忆”
SOUL.md 人格、边界、语气
IDENTITY.md 代理名称/气质/表情
USER.md 用户资料 + 首选称呼
BOOTSTRAP.md 一次性首次运行仪式(完成后删除)
MEMORY.md 根目录长期记忆文件(如果存在)

在新会话的第一轮中,OpenClaw 会将这些文件的内容注入系统提示词的 Project Context。MEMORY.md 仅当它存在于工作区根目录时才会被注入。

空文件会被跳过。大文件会被裁剪并截断,并带有标记,以保持提示词精简(读取文件以获取完整内容)。缺失文件(除 MEMORY.md 外)会改为注入单行“缺失文件”标记。openclaw setup 会为其创建安全的默认模板。

BOOTSTRAP.md 仅为全新工作区创建(不存在其他引导文件)。在其待处理期间,OpenClaw 会将其保留在 Project Context 中。OpenClaw 会为初始仪式添加系统提示词引导,而不是将该文件复制到用户消息中。如果你在完成仪式后删除它,后续重启时不会重新创建。

在工作区被观察后,OpenClaw 会将其设置状态和认证信息存储在共享 SQLite 数据库 ~/.openclaw/state/openclaw.sqlite 中。如果最近已认证的工作区消失或被清空,启动过程会拒绝静默重新生成 BOOTSTRAP.md。请恢复工作区,或使用完整初始化重置,以便工作区及其数据库状态一起被清除。

旧版本使用工作区 JSON 和 .attested 伴生文件。运行时不会读取这些文件。运行 openclaw doctor --fix 以验证它们,将其状态导入 SQLite,并在验证导入的行后删除每个源。

若要完全禁用引导文件创建(用于预置工作区),请设置:

{ agents: { defaults: { skipBootstrap: true } } }

内置工具

核心工具(read/exec/edit/write 及相关系统工具)始终可用,但受工具策略约束。apply_patch 对 OpenAI 模型默认开启,并受 tools.exec.applyPatch(enabled、workspaceOnly、allowModels)控制。AGENTS.md 中的 ## Tools 部分不控制哪些工具存在。它是关于你希望如何使用它们的指导。

技能

OpenClaw 从以下位置加载技能(优先级从高到低):

  • 工作区:<workspace>/skills
  • 项目代理技能:<workspace>/.agents/skills
  • 个人代理技能:~/.agents/skills
  • 托管/本地:~/.openclaw/skills
  • 内置(随安装提供)
  • 额外技能文件夹:skills.load.extraDirs

技能根目录可以包含分组文件夹,例如 <workspace>/skills/personal/foo/SKILL.md。技能仍以其扁平 frontmatter 名称暴露,例如 foo。

技能可通过配置/环境变量控制(参见 网关配置 中的 skills)。

运行时边界

嵌入式代理运行时由 OpenClaw 管理:模型发现、工具接线、提示词组装、会话管理和通道投递共享一个统一的运行时界面。

会话

会话行存储在每个代理的 SQLite 数据库中:

  • ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite

转录 JSONL 文件仍可以位于 ~/.openclaw/agents/<agentId>/sessions/ 下,作为旧版迁移输入、已删除或重置的归档、导入、导出和支持工件。活动代理历史与会话行一起存储在 SQLite 中。会话 ID 是稳定的,并由 OpenClaw 选择。OpenClaw 不会读取其他工具的会话文件夹。

流式传输中的转向

默认情况下,运行中途到达的传入提示会被转向到当前运行。OpenClaw 运行时会在转向能够跳过其未开始的顺序尾部之前,启动助手消息中第一个可执行工具调用。流式批次共享该消息的已启动状态。并行批次始终运行且不会被转向跳过,正在运行的工具会继续。每个批次稳定后,会在停止钩子和下一次模型调用之前检查转向。被跳过的调用会收到合成配对结果,排空的转向消息会跟随工具结果。

/queue steer 是默认的活动运行行为。/queue followup 和 /queue collect 会让消息等待后续轮次,而不是转向。/queue interrupt 则会中止活动运行。有关队列和边界行为,请参见 队列 和 转向队列。

块流式传输会在助手块完成后立即发送它们。它默认关闭(agents.defaults.blockStreamingDefault: "off")。通过 agents.defaults.blockStreamingBreak(text_end 或 message_end,默认 text_end)调整边界。使用 agents.defaults.blockStreamingChunk 控制软块分块(默认 800-1200 个字符,并优先段落换行,其次换行符,再次句子)。使用 agents.defaults.blockStreamingCoalesce 合并流式块,以减少单行刷屏(基于空闲的发送前合并)。非 Telegram 通道需要显式 *.streaming.block.enabled: true 才能启用块回复(QQ Bot 则流式传输块回复,除非 channels.qqbot.streaming.mode 为 "off")。详细工具摘要在工具开始时输出,无防抖。控制 UI 在可用时通过代理事件流式传输工具输出。更多细节:流式传输 + 分块。

模型引用

配置中的模型引用(例如 agents.defaults.model 和 agents.defaults.models)会按第一个 / 拆分解析。

  • 配置模型时使用 provider/model。
  • 如果模型 ID 本身包含 /(OpenRouter 风格),请包含提供商前缀(示例:openrouter/moonshotai/kimi-k2)。
  • 如果省略提供商,OpenClaw 会先尝试别名,然后尝试针对该确切模型 ID 的唯一已配置提供商匹配,最后才回退到已配置的默认提供商。如果该提供商不再暴露已配置的默认模型,OpenClaw 会回退到第一个已配置的提供商/模型,而不是显示过期的已移除提供商默认值。

最小配置

至少设置:

  • agents.defaults.workspace
  • 为你启用的每个通道配置发送者允许列表(强烈建议) — 参见 访问组

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw