文档
代理工作空间

代理工作空间

适用范围

在以下情况使用此页面：

  • 您需要解释代理工作空间或其文件布局
  • 您想要备份或迁移代理工作空间

工作空间是代理的主目录。它是用于文件工具和工作空间上下文的唯一工作目录。保持其私有并将其视为记忆。

这与 ~/.moltbot/ 分开，后者存储配置、凭据和会话。

重要： 工作空间是 默认 cwd，而不是硬沙箱。工具根据工作空间解析相对路径，但绝对路径仍然可以到达主机上的其他地方，除非启用了沙箱。如果您需要隔离，请使用 agents.defaults.sandbox（和/或每代理沙箱配置）。 当启用沙箱且 workspaceAccess 不是 "rw" 时，工具在 ~/.moltbot/sandboxes 下的沙箱工作空间内运行，而不是您的主机工作空间。

默认位置

  • 默认：~/clawd
  • 如果设置了 MOLTBOT_PROFILE 且不是 "default"，默认变为 ~/clawd-<profile>。
  • 在 ~/.moltbot/moltbot.json 中覆盖：
{
  agent: {
    workspace: "~/clawd"
  }
}

moltbot onboard、moltbot configure 或 moltbot setup 将创建工作空间并在缺少引导文件时为其播种。

如果您自己管理工作空间文件，可以禁用引导文件创建：

{ agent: { skipBootstrap: true } }

额外的工作空间文件夹

较旧的安装可能已创建 ~/moltbot。保留多个工作空间目录可能会导致令人困惑的身份验证或状态漂移，因为一次只有一个工作空间是活动的。

建议： 保持单个活动工作空间。如果您不再使用额外的文件夹，请将其存档或移动到废纸篓（例如 trash ~/moltbot）。 如果您有意保留多个工作空间，请确保 agents.defaults.workspace 指向活动的那个。

moltbot doctor 在检测到额外的工作空间目录时会发出警告。

工作空间文件映射（每个文件的含义）

这些是 Moltbot 在工作空间中期望的标准文件：

  • AGENTS.md

    • 代理的操作说明以及它应如何使用记忆。
    • 在每次会话开始时加载。
    • 规则、优先级和"如何表现"详细信息的好地方。

  • SOUL.md

    • 角色、语气和边界。
    • 每次会话加载。

  • USER.md

    • 用户是谁以及如何称呼他们。
    • 每次会话加载。

  • IDENTITY.md

    • 代理的名称、氛围和表情符号。
    • 在引导仪式期间创建/更新。

  • TOOLS.md

    • 关于本地工具和约定的注释。
    • 不控制工具可用性；它只是指导。

  • HEARTBEAT.md

    • 心跳运行的可选小型检查清单。
    • 保持简短以避免令牌消耗。

  • BOOT.md

    • 可选的启动检查清单，在启用内部挂钩时在网关重启时执行。
    • 保持简短；使用消息工具进行出站发送。

  • BOOTSTRAP.md

    • 一次性首次运行仪式。
    • 仅为一个全新的工作空间创建。
    • 仪式完成后删除它。

  • memory/YYYY-MM-DD.md

    • 每日记忆日志（每天一个文件）。
    • 建议在会话开始时读取今天 + 昨天。

  • MEMORY.md（可选）

    • 精选的长期记忆。
    • 仅在主、私人会话中加载（不在共享/群组上下文中）。

请参阅记忆了解工作流程和自动记忆刷新。

  • skills/（可选）

    • 工作空间特定的技能。
    • 当名称冲突时，覆盖托管/捆绑的技能。

  • canvas/（可选）

    • 节点显示的 Canvas UI 文件（例如 canvas/index.html）。

如果缺少任何引导文件，Moltbot 会在会话中注入"缺少文件"标记并继续。大型引导文件在注入时会被截断；通过 agents.defaults.bootstrapMaxChars 调整限制（默认：20000）。 moltbot setup 可以在不覆盖现有文件的情况下重新创建缺少的默认值。

工作空间中没有的内容

这些内容位于 ~/.moltbot/ 下，不应提交到工作空间仓库：

  • ~/.moltbot/moltbot.json（配置）
  • ~/.moltbot/credentials/（OAuth 令牌、API 密钥）
  • ~/.moltbot/agents/<agentId>/sessions/（会话脚本 + 元数据）
  • ~/.moltbot/skills/（托管技能）

如果您需要迁移会话或配置，请单独复制它们并将其排除在版本控制之外。

Git 备份（推荐，私有）

将工作空间视为私有记忆。将其放在 私有 git 仓库中，以便备份和恢复。

在运行网关的机器上运行这些步骤（即工作空间所在的位置）。

1) 初始化仓库

如果安装了 git，全新的工作空间会自动初始化。如果此工作空间还不是仓库，请运行：

cd ~/clawd
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"

2) 添加私有远程（适合初学者的选项）

选项 A：GitHub Web UI

  1. 在 GitHub 上创建一个新的 私有 仓库。
  2. 不要使用 README 初始化（避免合并冲突）。
  3. 复制 HTTPS 远程 URL。
  4. 添加远程并推送：
git branch -M main
git remote add origin <https-url>
git push -u origin main

选项 B：GitHub CLI (gh)

gh auth login
gh repo create clawd-workspace --private --source . --remote origin --push

选项 C：GitLab Web UI

  1. 在 GitLab 上创建一个新的 私有 仓库。
  2. 不要使用 README 初始化（避免合并冲突）。
  3. 复制 HTTPS 远程 URL。
  4. 添加远程并推送：
git branch -M main
git remote add origin <https-url>
git push -u origin main

3) 持续更新 

git status
git add .
git commit -m "Update memory"
git push

不要提交机密

即使在私有仓库中，也要避免在工作空间中存储机密：

  • API 密钥、OAuth 令牌、密码或私有凭据。
  • ~/.moltbot/ 下的任何内容。
  • 聊天的原始转储或敏感附件。

如果您必须存储敏感引用，请使用占位符并将真正的机密保存在其他地方（密码管理器、环境变量或 ~/.moltbot/）。

建议的 .gitignore 入门：

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

将工作空间移动到新机器

  1. 将仓库克隆到所需的路径（默认 ~/clawd）。
  2. 在 ~/.moltbot/moltbot.json 中将 agents.defaults.workspace 设置为该路径。
  3. 运行 moltbot setup --workspace <path> 以播种任何缺少的文件。
  4. 如果您需要会话，请从旧机器单独复制 ~/.moltbot/agents/<agentId>/sessions/。

高级说明

  • 多代理路由可以为每个代理使用不同的工作空间。请参阅通道路由了解路由配置。
  • 如果启用了 agents.defaults.sandbox，非主会话可以在 agents.defaults.sandbox.workspaceRoot 下使用每会话沙箱工作空间。
插件（扩展）代理循环（Moltbot）