智能体运行时

OpenClaw 自带一个嵌入式代理运行时：内置的代理循环、工具编排和提示词组装，不同于将轮次委托给外部 harness 进程。每个已配置的代理（有关运行多个代理，请参阅多代理路由）都有自己的工作空间、引导文件和会话存储。本页介绍该运行时契约：工作空间必须包含什么、哪些文件会被注入，以及会话如何基于它进行引导。

工作空间（必需）¶

每个代理使用单一工作空间目录（agents.defaults.workspace，或按代理配置的 agents.entries.*.workspace）作为工具和上下文的唯一工作目录（cwd）。

建议使用 openclaw setup 创建缺失的 ~/.openclaw/openclaw.json 并初始化工作空间文件。

完整工作空间布局 + 备份指南：代理工作空间

如果启用了 agents.defaults.sandbox，非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的按会话工作空间来覆盖此设置（参见网关配置）。

引导文件（注入）¶

在工作空间内，OpenClaw 期望以下用户可编辑文件：

在新会话的第一轮，OpenClaw 会将这些文件的内容注入系统提示的项目上下文（Project Context）。MEMORY.md 仅当其存在于工作空间根目录时才会被注入。

空文件会被跳过。大文件会被裁剪并以标记截断，以保持提示精简（如需完整内容请读取文件）。缺失的文件（MEMORY.md 除外）会注入一行“缺失文件”标记。openclaw setup 会为其创建安全的默认模板。

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

在观察到工作空间后，OpenClaw 会将其设置状态和认证信息存储在共享 SQLite 数据库 ~/.openclaw/state/openclaw.sqlite 中。如果最近已认证的工作空间消失或被清除，启动时会拒绝静默重新播种 BOOTSTRAP.md。请恢复工作空间，或执行完整的 onboard 重置，以便工作空间及其数据库状态一起被清除。

旧版本使用工作空间 JSON 和 .attested sidecar 文件。运行时不会读取这些文件。运行 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 不会读取来自其他工具的会话文件夹。

流式传输过程中的转向（Steering）¶

默认情况下，在运行中途到达的入站提示会被转向（steer）到当前运行中。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"）。详细工具摘要会在工具启动时输出，没有去抖。控制界面通过代理事件流式输出工具输出（如果可用）。更多详情：流式传输 + 分块。

模型引用¶

配置中的模型引用（例如 agents.defaults.model 和 agents.defaults.models）通过按第一个 / 拆分来解析。

• 配置模型时使用 provider/model。
• 如果模型 ID 本身包含 /（OpenRouter 风格），请包含提供商前缀（示例：openrouter/moonshotai/kimi-k2）。
• 如果省略提供商，OpenClaw 会先尝试别名，然后尝试为该确切模型 ID 查找唯一的已配置提供商匹配项，最后才回退到已配置的默认提供商。如果该提供商不再提供已配置的默认模型，OpenClaw 将回退到第一个已配置的提供商/模型，而不是呈现已移除提供商的过时默认值。

配置（最小化）¶

至少需要设置：

• agents.defaults.workspace
• 为你启用的每个渠道设置发送者允许列表（强烈推荐）——参见访问组

相关¶

• 代理工作区
• 多代理路由
• 会话管理
• 群聊
• 系统提示词