System Prompt

OpenClaw 为每次 Agent 运行构建自定义系统提示词，由 OpenClaw 完全拥有，不使用 pi-coding-agent 默认提示词。

组装三层架构

层	职责
`buildAgentSystemPrompt`	纯渲染器，从显式输入渲染提示词，不直接读全局配置
`resolveAgentSystemPromptConfig`	解析配置驱动的提示词旋钮（owner 显示、TTS 提示、模型别名、记忆引用模式、子 Agent 委托模式）
Runtime adapters	收集工具、沙箱状态、channel 能力、上下文文件、provider 贡献，调用提示词 facade

Provider 插件可以贡献缓存感知的提示词引导，而不替换整个提示词。可以：

替换少量命名核心 section（interaction_style/tool_call_style/execution_bias）
在提示词缓存边界上方注入稳定前缀
在提示词缓存边界下方注入动态后缀

提示词结构（固定 Section）

Section	内容	缓存位置
Tooling	工具使用规范，长时间运行工作指导（用 cron 而非 sleep 循环）	稳定区
Execution Bias	执行跟进指导：在轮次内行动、持续到完成或阻塞、从弱工具结果恢复	稳定区
Safety	避免权力寻求行为或绕过监督的简短护栏提醒	稳定区
Skills	如何按需加载 skill 指令（有 skill 时才注入）	稳定区
OpenClaw Control	优先用 `gateway` 工具做配置/重启，避免发明 CLI 命令	稳定区
OpenClaw Self-Update	如何安全检查配置（`config.schema.lookup`/`config.patch`/`config.apply`）	稳定区
Workspace	工作目录（`agents.defaults.workspace`）	稳定区
Documentation	本地文档路径或 docs.openclaw.ai	稳定区
Project Context	工作区引导文件（AGENTS.md/SOUL.md 等）	稳定区
Sandbox	沙箱路径、elevated exec 可用性（启用时）	稳定区
Current Date & Time	仅时区（不含动态时钟，保持缓存稳定）	稳定区
Assistant Output Directives	附件、语音备注、回复标签语法	动态区
Messaging	Channel 消息发送规范	动态区
Voice	语音相关	动态区
Group Chat Context	群聊上下文	动态区
Heartbeats	心跳提示词和 ack 行为（启用时）	动态区
Runtime	host/OS/node/model/repo root/thinking level	动态区
Reasoning	当前可见级别 + /reasoning 切换提示	动态区

缓存策略：大型稳定内容（Project Context）放在内部提示词缓存边界上方；volatile 的 channel/session section 放在下方，让本地后端的前缀缓存可以跨 channel 轮次复用稳定工作区前缀。

Tooling Section 的长时间运行指导

提示词明确告诉模型：

用 cron 做未来跟进（提醒、周期工作），不要用 exec sleep 循环或 yieldMs 延迟
用 exec/process 只处理立即启动并在后台持续运行的命令
启用自动完成唤醒时，启动一次命令，依赖推送式唤醒路径
任务较大时优先用 sessions_spawn，子 Agent 完成是推送式的
不要轮询 subagents list/sessions_list 等待完成

提示词模式（promptMode）

模式	适用场景	省略内容
`full`（默认）	正常 Agent 运行	无
`minimal`	子 Agent	Memory Recall、Self-Update、Model Aliases、User Identity、Output Directives、Messaging、Silent Replies、Heartbeats
`none`	仅基础身份行	几乎全部

minimal 模式下，额外注入的提示词标记为 Subagent Context 而非 Group Chat Context。

工作区引导文件注入（Bootstrap Injection）

以下文件在每次轮次注入到 Project Context：

文件	注入条件
`AGENTS.md`	始终
`SOUL.md`	始终
`TOOLS.md`	始终
`IDENTITY.md`	始终
`USER.md`	始终
`HEARTBEAT.md`	心跳启用时（或 `includeSystemPromptSection: true`）
`BOOTSTRAP.md`	仅全新工作区
`MEMORY.md`	存在时

子 Agent 只注入 AGENTS.md 和 TOOLS.md（保持子 Agent 上下文精简）。

memory/*.md 日常文件不注入，通过 memory_search/memory_get 工具按需访问。例外：/new//reset 后的第一轮可以预置最近日常记忆作为一次性启动上下文。

截断限制

配置项	默认值	说明
`agents.defaults.bootstrapMaxChars`	12000	单文件最大字符数
`agents.defaults.bootstrapTotalMaxChars`	60000	所有引导文件总上限
`agents.defaults.bootstrapPromptTruncationWarning`	`once`	截断警告：`off`/`once`/`always`

截断不是数据丢失——文件在磁盘上完整，模型只看到缩短的注入副本。MEMORY.md 反复被截断时，应将其提炼为更短的持久摘要，详细历史移入 memory/*.md。

内部钩子可通过 agent:bootstrap 事件拦截此步骤（例如替换 SOUL.md 为备用人格）。

Skills 注入

有符合条件的 skill 时，注入紧凑的 XML 列表：

<available_skills>
  <skill>
    <name>...</name>
    <description>...</description>
    <location>...</location>
  </skill>
</available_skills>

提示词指示模型用 read 工具按需加载对应 SKILL.md，不在提示词里嵌入完整 skill 内容。

符合条件的判断：skill 元数据门控 + 运行时环境/配置检查 + agent skill 白名单（agents.defaults.skills/agents.list[].skills）。插件捆绑的 skill 仅在其所属插件启用时才符合条件。

Skills 提示词预算

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,  // 全局默认
    },
  },
  agents: {
    list: [{
      id: "tiny-local",
      skillsLimits: {
        maxSkillsPromptChars: 6000,  // 按 agent 覆盖
      },
    }],
  },
}

Skills 预算与运行时读取/注入预算（contextLimits.*）分开管理。

⚠️ “Skills catalog using compact format (descriptions omitted)”

原因：skills 列表超出了 maxSkillsPromptChars 限制，OpenClaw 降级为只注入 <name> 和 <location>，省略 <description>。

模型仍能看到 skill 名称和路径，但看不到描述，可能影响它判断何时使用哪个 skill。

解决方法：

{
  skills: {
    limits: {
      maxSkillsPromptChars: 30000,  // 提高上限
    },
  },
}

或减少安装的 skill 数量，或运行 openclaw skills check 审计哪些 skill 占用了过多空间。

时间处理

Current Date & Time section 只包含时区（不含动态时钟），保持提示词缓存稳定。

Agent 需要当前时间时，用 session_status 工具——状态卡包含时间戳行。

{
  agents: {
    defaults: {
      userTimezone: "Asia/Shanghai",
      timeFormat: "24",  // auto | 12 | 24
    },
  },
}

Documentation Section

指向本地文档目录（Git checkout 的 docs/ 或 npm 包捆绑文档），不可用时回退到 https://docs.openclaw.ai。

同时包含：

OpenClaw 源码位置（Git checkout 暴露本地源码根目录）
公共文档镜像、社区 Discord、ClawHub
配置查询指引：优先用 config.schema.lookup 获取精确字段文档

诊断

/context list    # 查看每个注入文件的原始/注入字符数、截断情况、工具 schema 开销
/context detail  # 详细版本

Wiki AI

目录