English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

基础

Agent 工作区

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

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

默认位置

  • 默认：~/.openclaw/workspace
  • 如果设置了 OPENCLAW_PROFILE 且它不是 "default"，默认值会变为 ~/.openclaw/workspace-<profile>。
  • 在 ~/.openclaw/openclaw.json 中覆盖：
json5
{  agents: {    defaults: {      workspace: "~/.openclaw/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 key）
  • ~/.openclaw/agents/<agentId>/agent/codex-home/（每智能体的 Codex runtime 账户、配置、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>/sessions/。

    • 高级说明

    • 多智能体路由可以为每个智能体使用不同的工作区。请参阅频道路由了解路由配置。
    • 如果启用了 agents.defaults.sandbox，非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的按会话沙箱工作区。

    相关

    Was this useful?
    On this page

    On this page