智能体运行时
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,并在验证导入的行后删除每个源。
若要完全禁用引导文件创建(用于预置工作区),请设置:
内置工具¶
核心工具(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