OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

基础

Agent 工作区

工作区是智能体的主目录：文件工具和工作区上下文所使用的工作目录。请将其保持私密，并将其视为记忆。

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

默认位置

  • 默认值：~/.openclaw/workspace
  • 如果设置了 OPENCLAW_PROFILE 且其值不是 "default"，默认位置将变为 ~/.openclaw/workspace-<profile>。
  • 设置 OPENCLAW_WORKSPACE_DIR 后，它会覆盖上述两项。
  • 未显式指定工作区的非默认智能体（agents.list[]）会解析到 <state-dir>/workspace-<agentId>，而不是共享的默认工作区。

在 ~/.openclaw/openclaw.json 中覆盖：

json5
{  agents: {    defaults: {      workspace: "~/.openclaw/workspace",    },  },}

按智能体覆盖：agents.list[].workspace。

如果工作区不存在，openclaw onboard、openclaw configure 或 openclaw setup 会创建工作区并植入引导文件。

如果你已经自行管理工作区文件，请禁用引导文件创建：

json5
{ agents: { defaults: { skipBootstrap: true } } }

额外工作区文件夹

旧版安装可能创建了 ~/openclaw。保留多个工作区目录可能造成令人困惑的身份验证或状态偏移，因为任何时候都只有一个工作区处于活动状态。

工作区文件映射

OpenClaw 期望工作区内包含的标准文件：

AGENTS.md - 操作说明

智能体的操作说明，以及它应如何使用记忆。每次会话开始时加载。适合存放规则、优先级和“行为方式”等详细信息。

SOUL.md - 角色设定和语气

角色设定、语气和边界。每次会话都会加载。指南：SOUL.md 个性指南。

USER.md - 用户身份

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

IDENTITY.md - 名称、风格、表情符号

智能体的名称、风格和表情符号。在引导仪式期间创建/更新。

TOOLS.md - 本地工具约定

关于本地工具和约定的说明。它不控制工具可用性，仅提供指导。

HEARTBEAT.md - Heartbeat 检查清单

用于 Heartbeat 运行的可选精简检查清单。请保持简短，以免消耗过多 token。

BOOT.md - 启动检查清单

Gateway 网关重启时自动运行的可选启动检查清单（启用内部钩子时）。请保持简短；出站发送请使用消息工具。

BOOTSTRAP.md - 首次运行仪式

一次性的首次运行仪式。仅为全新工作区创建。仪式完成后将其删除。

memory/YYYY-MM-DD.md - 每日记忆日志

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

MEMORY.md - 整理后的长期记忆（可选）

整理后的长期记忆：持久事实、偏好、决策和简短摘要。将详细日志保存在 memory/YYYY-MM-DD.md 中，以便记忆工具按需检索，而无需将其注入每个提示词。仅在主要的私密会话中加载 MEMORY.md（不要在共享/群组上下文中加载）。有关工作流和自动记忆刷新，请参阅记忆。

skills/ - 工作区 Skills（可选）

工作区专用 Skills。当名称冲突时，这是该工作区中优先级最高的 Skills 位置，高于项目智能体 Skills、个人智能体 Skills、托管 Skills、内置 Skills 和 skills.load.extraDirs。

canvas/ - Canvas UI 文件（可选）

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

工作区中不包含的内容

以下内容位于 ~/.openclaw/ 下，不应提交到工作区仓库：

  • ~/.openclaw/openclaw.json（配置）
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（模型身份验证配置文件：OAuth + API 密钥）
  • ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite（会话行、转录记录和按智能体存储的运行时状态）
  • ~/.openclaw/agents/<agentId>/agent/codex-home/（按智能体存储的 Codex 运行时账户、配置、Skills、插件和原生线程状态）
  • ~/.openclaw/credentials/（渠道/提供商状态以及旧版 OAuth 导入数据）
  • ~/.openclaw/agents/<agentId>/sessions/（旧版迁移源和归档/支持工件）
  • ~/.openclaw/skills/（托管 Skills）

如果你需要迁移会话或配置，请单独复制它们，并确保它们不进入版本控制。

Git 备份（建议使用私有仓库）

将工作区视为私密记忆。把它放入私有 Git 仓库，以便备份和恢复。

在运行 Gateway 网关的计算机上执行以下步骤（工作区就在该计算机上）。

  • 初始化仓库

    如果已安装 Git，全新工作区会自动初始化。如果此工作区尚不是仓库，请运行：

    bash
    cd ~/.openclaw/workspacegit initgit add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/git commit -m "Add agent workspace"

  • 添加私有远程仓库

    GitHub Web UI

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

    GitHub CLI (gh)

    bash
    gh auth logingh repo create openclaw-workspace --private --source . --remote origin --push

    GitLab Web UI

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

  • 持续更新

    bash
    git statusgit add .git commit -m "Update memory"git push

    • 不要提交机密信息

    建议的 .gitignore 初始内容：

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

    将工作区迁移到新计算机

  • 克隆仓库

    将仓库克隆到所需路径（默认为 ~/.openclaw/workspace）。

  • 更新配置

    在 ~/.openclaw/openclaw.json 中将 agents.defaults.workspace 设置为该路径。

  • 植入缺失文件

    运行 openclaw setup --workspace <path> 以植入所有缺失文件。

  • 复制会话（可选）

    如果你需要会话，请从旧计算机单独复制 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。仅当你还需要旧版迁移输入或归档/支持工件时，才复制 ~/.openclaw/agents/<agentId>/sessions/。

    • 高级说明

    • 多智能体路由可以通过 agents.list[].workspace 为每个智能体使用不同的工作区。有关路由配置，请参阅渠道路由。
    • 如果启用了 agents.defaults.sandbox，非主要会话可以使用 agents.defaults.sandbox.workspaceRoot 下按会话划分的沙箱工作区。

    相关内容

    Was this useful?
    On this page

    On this page