Agent Runtime 🤖

Moltbot 运行一个从 p-mono 派生的单一嵌入式 agent runtime。

Workspace（必需）

Moltbot 使用一个 agent workspace 目录（agents.defaults.workspace）作为工具与上下文的唯一工作目录（cwd）。

推荐：如果 ~/.openclaw/moltbot.json 不存在，用 moltbot setup 创建它并初始化 workspace files。

完整 workspace 结构 + 备份指南参见：Agent workspace

如果启用了 agents.defaults.sandbox，non-main sessions 可以在 agents.defaults.sandbox.workspaceRoot 下使用 per-session workspaces 覆盖该目录（参见 Gateway configuration）。

Bootstrap files（注入）

在 agents.defaults.workspace 内，Moltbot 期望存在这些用户可编辑文件：

• AGENTS.md — 操作说明 + “memory”
• SOUL.md — persona、边界、语气
• TOOLS.md — 用户维护的工具笔记（例如 imsg、sag、约定）
• BOOTSTRAP.md — 一次性的首次运行仪式（完成后删除）
• IDENTITY.md — agent name/vibe/emoji
• USER.md — 用户资料 + 偏好的称呼

在新 session 的第一回合，Moltbot 会把这些文件内容直接注入到 agent context。

空文件会被跳过。大文件会被裁剪/截断并附带标记，以保持 prompt 精简（需要完整内容时请读取文件）。

如果文件缺失，Moltbot 会注入一行 “missing file” 标记（并且 moltbot setup 会创建安全的默认模板）。

BOOTSTRAP.md 只会在全新 workspace（不存在其他 bootstrap files）时创建。如果你在完成仪式后删除它，它不应该在后续重启时被重新创建。

要完全禁用 bootstrap 文件创建（用于预置 workspaces），设置：

{ agent: { skipBootstrap: true } }

内置工具（Built-in tools）

核心工具（read/exec/edit/write 以及相关 system tools）始终可用，但会受 tool policy 约束。apply_patch 是可选的，并由 tools.exec.applyPatch 控制。

TOOLS.md 不会控制工具是否存在；它只是你希望工具如何被使用的“指导”。

Skills

Moltbot 从三个位置加载 skills（同名冲突时 workspace 优先）：

• Bundled（随安装包提供）
• Managed/local：~/.openclaw/skills
• Workspace：<workspace>/skills

skills 也可以通过 config/env gating（参见 Gateway configuration 中的 skills）。

p-mono 集成

Moltbot 复用 p-mono 代码库的一些部分（models/tools），但 session 管理、发现与 tool wiring 由 Moltbot 自己维护。

• 不使用 p-coding agent runtime。
• 不会读取 ~/.pi/agent 或 <workspace>/.pi 的设置。

Sessions

session transcripts 以 JSONL 形式存储在：

• ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

session ID 由 Moltbot 选择并保持稳定。 旧版 Pi/Tau session 目录不会被读取。

Streaming 中的 steer

当 queue mode 为 steer 时，入站消息会被注入到当前 run。 队列会在每次 tool call 之后检查；如果存在排队消息，则当前 assistant 消息中剩余的 tool calls 会被跳过（对应的 error tool results 为 "Skipped due to queued user message."），然后在下一条 assistant 回复前注入排队的用户消息。

当 queue mode 为 followup 或 collect 时，入站消息会被保留到当前回合结束，然后开启一个新的 agent 回合来处理排队 payloads。mode + debounce/cap 行为参见 Queue。

block streaming 会在 assistant 的 blocks 完成后立即发送；默认关闭（agents.defaults.blockStreamingDefault: "off"）。 可用 agents.defaults.blockStreamingBreak 调整边界（text_end vs message_end；默认 text_end）。 用 agents.defaults.blockStreamingChunk 控制软分块（默认 800–1200 chars；优先段落断点，其次换行；句子最后）。 用 agents.defaults.blockStreamingCoalesce 合并流式 chunks，以减少“一行一条”的刷屏（基于 idle 的发送前合并）。非 Telegram 渠道需要显式设置 *.blockStreaming: true 才会启用 block replies。 verbose 的 tool summaries 会在 tool start 立刻发出（无 debounce）；Control UI 在可用时通过 agent events 流式展示 tool 输出。 更多细节参见：Streaming + chunking。

Model refs

配置中的 model refs（例如 agents.defaults.model 与 agents.defaults.models）通过“第一个 /”分割解析。

• 配置 models 时使用 provider/model。
• 如果 model id 自身包含 /（OpenRouter 风格），请包含 provider 前缀（例如：openrouter/moonshotai/kimi-k2）。
• 如果省略 provider，Moltbot 会把输入当作 alias 或默认 provider 的 model（仅在 model id 不包含 / 时成立）。

最小配置（Configuration）

至少需要设置：

• agents.defaults.workspace
• channels.whatsapp.allowFrom（强烈建议）

---

Next: Group Chats 🦞