文档
代理运行时 🤖

代理运行时 🤖

适用范围

在以下情况使用此页面：

  • 更改代理运行时、工作空间引导或会话行为

Moltbot 运行源自 p-mono 的单个嵌入式代理运行时。

工作空间（必需）

Moltbot 使用单个代理工作空间目录（agents.defaults.workspace）作为代理 唯一 工作目录（cwd），用于工具和上下文。

推荐：使用 moltbot setup 创建 ~/.moltbot/moltbot.json（如果缺少）并初始化工作空间文件。

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

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

引导文件（注入）

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

  • AGENTS.md — 操作说明 + “记忆”
  • SOUL.md — 角色、边界、语气
  • TOOLS.md — 用户维护的工具注释（例如 imsg、sag、约定）
  • BOOTSTRAP.md — 一次性首次运行仪式（完成后删除）
  • IDENTITY.md — 代理名称/氛围/表情符号
  • USER.md — 用户配置文件 + 首选地址

在新会话的第一轮，Moltbot 将这些文件的内容直接注入到代理上下文中。

空白文件被跳过。大型文件被修剪并带有标记截断，以便提示保持精简（读取文件以获取完整内容）。

如果缺少文件，Moltbot 会注入单行"缺少文件"标记行（并且 moltbot setup 将创建安全的默认模板）。

BOOTSTRAP.md 仅为 全新的工作空间 创建（没有其他引导文件存在）。如果您在完成仪式后删除它，则不应在以后重新启动时重新创建。

要完全禁用引导文件创建（对于预播种的工作空间），请设置：

{ agent: { skipBootstrap: true } }

内置工具

核心工具（read/exec/edit/write 和相关系统工具）始终可用，受工具策略限制。apply_patch 是可选的，由 tools.exec.applyPatch 限制。TOOLS.md 不 控制哪些工具存在；它只是您希望它们如何使用的指导。

技能

Moltbot 从三个位置加载技能（工作空间在名称冲突时获胜）：

  • 捆绑（随安装一起提供）
  • 托管/本地：~/.moltbot/skills
  • 工作空间：<workspace>/skills

技能可以通过配置/环境进行限制（参见网关配置中的 skills）。

p-mono 集成

Moltbot 重用 p-mono 代码库的部分（模型/工具），但 会话管理、发现和工具连接是 Moltbot 拥有的。

  • 无 p-coding 代理运行时。
  • 不查询 ~/.pi/agent 或 <workspace>/.pi 设置。

会话

会话脚本以 JSONL 格式存储在：

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

会话 ID 是稳定的，由 Moltbot 选择。 不读取传统的 Pi/Tau 会话文件夹。

流式传输时的引导

当队列模式是 steer 时，入站消息被注入到当前运行中。 在 每次工具调用之后 检查队列；如果存在排队消息， 当前 assistant 消息的剩余工具调用将被跳过（错误工具 结果为"由于排队的用户消息而跳过。"），然后在下一个 assistant 响应之前注入排队的用户消息。

当队列模式是 followup 或 collect 时，入站消息被保持直到当前轮次结束，然后新的代理轮次以排队负载开始。请参阅队列了解模式 + debounce/cap 行为。

块流式传输在完成时立即发送完成的 assistant 块；它 默认关闭（agents.defaults.blockStreamingDefault: "off"）。 通过 agents.defaults.blockStreamingBreak 调整边界（text_end vs message_end；默认为 text_end）。 使用 agents.defaults.blockStreamingChunk 控制软块分块（默认为 800–1200 个字符；首选段落分隔，然后是换行；句子最后）。 使用 agents.defaults.blockStreamingCoalesce 合并流式块以减少单行垃圾邮件（基于空闲的发送前合并）。非 Telegram 通道需要显式 *.blockStreaming: true 来启用块回复。 详细工具摘要在工具开始时发出（无 debounce）；控制 UI 在可用时通过代理事件流式传输工具输出。 更多详细信息：流式传输 + 分块。

模型引用

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

  • 在配置模型时使用 provider/model。
  • 如果模型 ID 本身包含 /（OpenRouter 风格），请包括提供程序前缀（例如：openrouter/moonshotai/kimi-k2）。
  • 如果您省略提供程序，Moltbot 会将输入视为别名或 默认提供程序 的模型（仅当模型 ID 中没有 / 时才有效）。

配置（最小）

至少设置：

  • agents.defaults.workspace
  • channels.whatsapp.allowFrom（强烈推荐）

下一步：群组聊天 🦞

代理循环（Moltbot）调试