智能体工作区
工作区是代理的主目录:用于文件工具和工作区上下文的工作目录。请保持其私密性,并将其视为记忆。
这与 ~/.openclaw/ 相互独立,后者存储配置、凭据和会话。
Warning
工作区是默认的 cwd,而非硬性沙箱。工具基于工作区解析相对路径,但除非启用沙箱功能,否则绝对路径仍可访问主机上的其他位置。如果需要隔离,请使用 agents.defaults.sandbox(和/或按代理的沙箱配置)。
当沙箱功能启用且 workspaceAccess 不是 "rw" 时,工具会在 ~/.openclaw/sandboxes 下的沙箱工作区中运行,而非您的主机工作区。
默认位置¶
- 默认:
~/.openclaw/workspace - 如果设置了
OPENCLAW_PROFILE且其值不是"default",则默认值变为~/.openclaw-<profile>/workspace。 - 设置
OPENCLAW_WORKSPACE_DIR后会覆盖上述两者。 - 非默认的
OPENCLAW_STATE_DIR会将默认工作区保留在<state-dir>/workspace,包括计划维护和初始main代理条目。 - 唯一配置的代理会继承默认工作区,除非其条目中设置了
workspace。 - 在显式多代理名册中,未设置
workspace的条目会在配置了该根目录时使用<agents.defaults.workspace>/<agentId>,否则使用<state-dir>/workspace-<agentId>。指定共享根目录并不会将其分配给某个代理。
在 ~/.openclaw/openclaw.json 中覆盖:
按代理覆盖:agents.entries.*.workspace。要在多代理名册中将 main 保留在现有的共享根目录,请将 agents.entries.main.workspace 显式固定到该根目录;仅更改 agents.defaults.workspace 只会设置未固定条目的基础路径。
Run 的工作区选择会拒绝显式提供的空白或无效代理 ID。省略选择器以使用已配置的所有权,或提供预期的代理 ID。
openclaw onboard、openclaw configure 或 openclaw setup 会创建工作区,并在缺少引导文件时填充这些文件。
Note
沙箱填充副本只接受工作区内的常规文件;解析到源工作区之外的符号链接/硬链接别名会被忽略。
如果您自行管理工作区文件,请禁用引导文件创建:
额外工作区文件夹¶
较旧的安装可能创建了 ~/openclaw。每个代理使用一个解析后的工作区;保留额外的目录不会将其人格或记忆文件合并到活动工作区中。
Note
在保留旧目录时,请显式指定每个代理的工作区路径。在切换回旧工作区之前,请停止 Gateway,配置目标路径,运行 openclaw doctor --fix 迁移已停用的设置状态,然后重新启动。Doctor 还会在仍然配置的 agents.defaults.workspace 根目录中发现遗留的设置文件,即使当前没有代理直接使用该根目录。只有在确认要保留哪些文件之后,才可归档未使用的文件夹。
工作区文件映射¶
使用 Control UI 中的 设置 → 代理 → 文件 编辑这些文件。预览 显示当前草稿;编辑 返回编辑器以便继续输入,而 关闭 返回 预览。
OpenClaw 期望工作区内包含的标准文件:
AGENTS.md - 操作说明
面向代理的操作说明,以及它应如何使用记忆。在每次会话开始时加载。适合放置规则、优先级和“行为方式”等细节。模板:AGENTS.md。
SOUL.md - 人格与语气
人格、语气和边界。每个会话都会加载。指南:SOUL.md 人格指南。
USER.md - 基于指令的用户模型(可选)
稳定的偏好、沟通风格、人际关系和活动项目上下文。将条目编写为带日期的有效或已取代指令。每个会话都会加载,并拥有独立的 4,000 字符预算。参见 用户模型。模板:USER.md。
IDENTITY.md - 名称、风格、表情符号
代理的名称、风格和表情符号。在引导仪式期间创建/更新。模板:IDENTITY.md。
AGENTS.md Tools 部分 - 本地工具约定
## Tools 部分包含本地环境说明和约定。它不控制工具的可用性,仅作为指导。模板:AGENTS.md Tools 部分。
BOOT.md - 启动清单
可选的启动清单,在启用 boot-md 钩子 时于 Gateway 启动时运行。启用其他内部钩子不会启用 boot-md。请保持简短;对外发送请使用消息工具。模板:BOOT.md。
BOOTSTRAP.md - 首次运行仪式
一次性的首次运行仪式。仅为全新工作区创建。仪式完成后删除它。模板:BOOTSTRAP.md。
memory/YYYY-MM-DD.md - 每日记忆日志
每日记忆日志(每天一个文件)。建议在会话开始时阅读今天和昨天的日志。
MEMORY.md - 精选长期记忆(可选)
精选的长期记忆:持久性的非档案事实、决策和简短摘要。将详细日志保存在 memory/YYYY-MM-DD.md 中,以便记忆工具可按需检索它们,而无需将它们注入到每个 prompt 中。仅在主要的私密会话(而非共享/群组上下文)中加载 MEMORY.md。有关工作流程和自动记忆刷新,请参见 记忆。
skills/ - 工作区技能(可选)
工作区专属技能。对于该工作区而言,这是优先级最高的技能位置,优先于项目代理技能、个人代理技能、托管技能、内置技能以及 skills.load.extraDirs(当名称冲突时)。
Note
如果必需的引导文件缺失,OpenClaw 会在会话中注入一个“缺失文件”标记并继续运行。可选的 USER.md 和 MEMORY.md 文件在不存在时会被省略。大型引导文件在注入时会被截断;可通过 agents.defaults.bootstrapMaxChars(默认:20000)和 agents.defaults.bootstrapTotalMaxChars(默认:60000)调整通用限制。USER.md 保留其独立的 4,000 字符上限。openclaw setup 可以重新创建缺失的默认文件,而不会覆盖现有文件。
工作区中不应包含的内容¶
以下内容存放在 ~/.openclaw/ 下,不应提交到工作区仓库:
~/.openclaw/openclaw.json(配置)~/.openclaw/state/openclaw.sqlite(共享工作区设置状态与证明记录)~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite(模型认证配置、路由状态、常驻意图、会话行、对话记录、记忆索引状态,以及其他按代理维度存储的运行时持久化数据)~/.openclaw/agents/<agentId>/agent/codex-home/(每个代理的 Codex 运行时账户、配置、技能、插件及原生线程状态)~/.openclaw/credentials/(渠道/提供方状态以及旧版 OAuth 导入数据)~/.openclaw/agents/<agentId>/sessions/(旧版迁移来源及归档/支持产物)~/.openclaw/skills/(受管技能)
如果需要迁移会话或配置,请单独复制它们,并使其保持不受版本控制。
旧版 OpenClaw 版本会将 openclaw-workspace-state.json 和 .attested 作为工作区伴生文件写入。当前运行时仅使用共享 SQLite 数据库来保存该状态。如果 Doctor 报告了这些文件之一,请运行 openclaw doctor --fix;Doctor 会导入有效的旧版状态,并在验证数据库行之后才删除源文件。workspace-attestations/ 下空的保留哈希文件会被丢弃,因为它们不包含可导入的状态;其他无法读取的源文件会保留在原位置,Doctor 会列出它们的路径。
七月之前的 .openclaw/workspace-state.json 布局不在支持的迁移窗口内。请先升级到 2026.9.7 并在此版本上运行 openclaw doctor --fix,然后再进行更新;当前版本的 Doctor 不会改动该文件。请参阅保留策略。
Git 备份(推荐,私有)¶
将工作区视为私有记忆。把它放在私有 git 仓库中,以便进行备份和恢复。
请在运行 Gateway 的机器上执行以下步骤(工作区就位于该机器上)。
1. 初始化仓库
如果已安装 git,全新的工作区会自动初始化。如果此工作区尚不是仓库,请运行:
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md IDENTITY.md USER.md memory/
git commit -m "Add agent workspace"
2. 添加私有远程仓库
- 在 GitHub 上创建一个新的私有仓库。
- 不要使用 README 初始化(避免合并冲突)。
- 复制 HTTPS 远程仓库 URL。
- 添加远程仓库并推送:
3. 持续更新
不要提交机密信息¶
Warning
即使在私有仓库中,也应避免在工作区中存储机密信息:
- API 密钥、OAuth 令牌、密码或私有凭据。
~/.openclaw/下的任何内容。- 聊天记录的原始导出或敏感附件。
如果必须存储对敏感信息的引用,请使用占位符,并将真实机密保存在其他位置(密码管理器、环境变量或 ~/.openclaw/ 中)。
建议的 .gitignore 入门配置:
将工作区迁移到新机器¶
1. 克隆仓库
将仓库克隆到目标路径(默认为 ~/.openclaw/workspace)。
2. 更新配置
在 ~/.openclaw/openclaw.json 中,为应使用该工作区的代理将 agents.entries.<agentId>.workspace 设置为克隆路径。如果没有逐代理覆盖配置,单独的代理可以使用 agents.defaults.workspace;在多代理阵容中,该设置只会更改未固定条目的基础目录。
3. 验证工作区
在启动 Gateway 之前,运行 openclaw agents list 并确认目标代理指向克隆路径。迁移现有工作区无需重新运行引导流程。
4. 复制会话(可选)
如果需要会话,请从旧机器单独复制 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。仅当还需要旧版迁移输入或归档/支持产物时,才复制 ~/.openclaw/agents/<agentId>/sessions/。
高级说明¶
- 多代理路由可以通过
agents.entries.*.workspace为每个代理使用不同的工作区。路由配置请参阅渠道路由。 - 如果启用了
agents.defaults.sandbox,非主会话可以使用agents.defaults.sandbox.workspaceRoot下按会话隔离的沙箱工作区。
相关文档¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw