很多人第一次接触 OpenClaw 的 workspace会把它理解成“Agent 的项目目录”。这个说法没错但太浅。Workspace 同时承担三种角色默认工作目录 上下文来源 长期记忆和本地约定的承载地但还有一个非常重要的边界workspace 本身不是硬沙箱如果你只记住“workspace 是目录”你会低估它对 Agent 行为的影响。如果你误以为“workspace 天然安全隔离”你会高估它的安全能力。这篇文章把这两个误区一起拆掉。先说结论Workspace 是上下文边界不等于安全边界OpenClaw 官方文档明确说明workspace 是默认 cwd不是硬沙箱。工具会把相对路径解析到 workspace 下但如果没有启用 sandbox绝对路径仍可能访问宿主机其他位置。这句话是理解 workspace 的关键。可以这样画Workspace 负责 默认 cwd 启动文件 Agent 指令 用户信息 工具约定 记忆文件 Canvas 文件 不直接负责 阻止所有宿主文件访问 多租户隔离 命令审批 浏览器权限 网络边界所以 workspace 更像“Agent 的家”和“项目上下文根目录”。真正的安全边界还要靠 sandbox、exec approvals、tool policy、Gateway auth、OS 权限等一起完成。默认位置和 profileOpenClaw 的默认 workspace 通常是~/.openclaw/workspace如果设置了非 default 的OPENCLAW_PROFILE默认位置会变成~/.openclaw/workspace-也可以在配置里覆盖{ agents: { defaults: { workspace: ~/.openclaw/workspace } } }这解释了为什么同一台机器上可能出现多个 workspace。但官方文档也提醒保留多个 workspace 目录可能导致 auth 或状态漂移因为同一时间只有一个 workspace 是活跃的。如果你看到 Agent “好像忘了规则”第一反应不应该是模型变笨。先检查当前 profile 是什么 active workspace 是哪个 AGENTS.md 是否在这个 workspace 里 配置指向了哪个路径Workspace 文件图谱OpenClaw workspace 不是空目录。它有一组约定文件。常见文件包括AGENTS.md Agent 操作规则和使用记忆的方式 SOUL.md persona、语气和边界 USER.md 用户是谁、如何称呼用户 IDENTITY.md Agent 名字、风格、身份信息 TOOLS.md 本地工具约定和使用习惯 HEARTBEAT.md heartbeat run 的轻量 checklist BOOT.md Gateway restart 后的启动检查 BOOTSTRAP.md 第一次初始化 ritual memory/YYYY-MM-DD.md 每日记忆日志 MEMORY.md 可选的长期记忆摘要 skills/ workspace 级别技能 canvas/ Canvas UI 文件这些文件不是装饰。它们会影响 Agent 如何理解你、如何执行任务、如何使用工具、如何保持长期上下文。Workspace 如何进入上下文Agent 不会把整个 workspace 一股脑塞进模型。更合理的方式是启动时加载关键 bootstrap 文件 根据任务读取相关文件 必要时检索 memory 工具执行时以 workspace 为默认 cwd 把结果写回 transcript 或 workspace这背后的原则是常驻上下文要短 任务相关上下文要准 长期记忆要可检索例如AGENTS.md 适合放长期操作原则 TOOLS.md 适合放本机工具命令和路径约定 memory/YYYY-MM-DD.md 适合放当天变化 项目文件 需要时再读取如果你把大量日志、长文档、历史聊天都塞进AGENTS.mdAgent 每次启动都会背负巨大上下文负担。这是 workspace 设计中最常见的问题之一。Workspace 与工具执行工具执行时workspace 通常是默认 cwd。这带来一个好处相对路径稳定例如 Agent 调用rg TODO .它知道.大概率是当前 workspace而不是系统某个随机目录。但这不等于安全隔离。如果没有启用 sandbox绝对路径仍可能指向 workspace 外/Users/me/Desktop /etc /tmp所以你要把“路径组织”和“权限隔离”分开看。Workspace 负责组织。Sandbox 和 approvals 负责限制。Sandbox 启用后workspace 语义会变化官方 workspace 文档提到当 sandboxing 启用且workspaceAccess不是rw时工具会在~/.openclaw/sandboxes下的 sandbox workspace 中运行而不是宿主 workspace。这意味着未启用 sandbox workspace 是宿主机上的默认 cwd 启用 sandbox 工具可能在隔离副本或 sandbox workspace 中运行用户容易困惑的是为什么 Agent 明明改了文件我宿主目录没看到 为什么 shell 看到的路径和我本机不一样 为什么浏览器或命令的环境变了答案往往和 sandbox mode、workspaceAccess、挂载策略有关。什么不应该放进 workspace官方文档列出了一些不应该提交进 workspace repo 的内容例如~/.openclaw/openclaw.json 模型 auth profiles credentials session transcripts managed skills per-agent Codex runtime account/config/thread state这些属于运行状态、密钥、凭证或内部状态。它们不是课程项目、不是可公开资料也不应该随便进 git。一个稳妥原则可解释 Agent 行为的规则可以放 workspace 能恢复用户上下文的私有记忆可以放私有 repo 密钥、token、凭证、session 内部状态不要放项目仓库Workspace skills 的优先级Workspace 下的skills/很重要。官方文档说明workspace-specific skills 是该 workspace 的最高优先级 skill location。当名称冲突时它会覆盖 project、personal、managed、bundled 等其他来源。这意味着workspace 可以定义非常本地化的能力比如你的公司内部有特定部署命令skills/deploy-company-service/这个 skill 可以只在当前 workspace 生效。但这也意味着你要小心命名冲突。如果 workspace skill 和 bundled skill 同名它可能改变 Agent 在这个 workspace 里的行为。一个真实场景你把 OpenClaw 用作个人运维助手。Workspace 里有AGENTS.md 永远先读 runbook危险命令先解释 TOOLS.md 日志目录、kubectl context、常用脚本路径 memory/2026-05-28.md 今天迁移了 billing service skills/deploy-check/ 公司内部部署检查流程你说检查 billing service 昨天发布后有没有异常。Agent 会从 workspace 得到很多隐含信息应该如何行动 哪些工具可用 日志在哪里 今天有什么背景 哪些操作需要谨慎但它是否能执行 shell、能否访问宿主路径、是否需要 approval仍由工具策略和 sandbox 决定。这就是 workspace 的正确位置。常见误解误解一Workspace 就是项目源码目录不只是。它可以包含项目文件也包含 Agent 指令、用户信息、记忆、工具约定、workspace skills 和 Canvas 文件。误解二Workspace 是安全沙箱不是。官方文档明确说 workspace 是默认 cwd不是硬沙箱。需要隔离时应配置 sandbox。误解三把所有东西写进 AGENTS.md 会更聪明不会。过大的常驻上下文会浪费 token稀释重点增加模型误读概率。误解四多个 workspace 可以随便混用不建议。多个活跃路径容易导致配置、认证、记忆和状态漂移。最后总结Workspace 是 OpenClaw 的上下文根目录和默认执行位置。它承载 Agent 指令、用户信息、工具约定、记忆、skills 和 Canvas 文件也为工具提供默认 cwd。但它不是硬安全边界。一句话总结Workspace 负责让 Agent 知道“我在哪、该按什么规则做事”sandbox 和 approvals 才负责限制“我能碰什么”。本节作业检查你的 workspace 里有哪些 bootstrap 文件。用自己的话解释 workspace 和 sandbox 的区别。设计一个合理的TOOLS.md只放本机工具约定不放大段日志。思考为什么多个 workspace 会导致状态漂移列出哪些文件不应该提交到 workspace 私有 repo。下一节预告下一节讲权限模型Shell、Browser、文件读写的安全边界我们会把 Gateway auth、operator trust、exec approvals、browser isolation、sandbox 和 workspaceAccess 放在一张图里讲清楚。参考资料OpenClaw DocsAgent workspaceOpenClaw DocsSandboxingOpenClaw DocsSecurityOpenClaw DocsExec approvals原文链接Workspace文件系统、项目上下文和执行边界 | Harries Blog™
Workspace：文件系统、项目上下文和执行边界
发布时间：2026/6/6 19:54:34
很多人第一次接触 OpenClaw 的 workspace会把它理解成“Agent 的项目目录”。这个说法没错但太浅。Workspace 同时承担三种角色默认工作目录 上下文来源 长期记忆和本地约定的承载地但还有一个非常重要的边界workspace 本身不是硬沙箱如果你只记住“workspace 是目录”你会低估它对 Agent 行为的影响。如果你误以为“workspace 天然安全隔离”你会高估它的安全能力。这篇文章把这两个误区一起拆掉。先说结论Workspace 是上下文边界不等于安全边界OpenClaw 官方文档明确说明workspace 是默认 cwd不是硬沙箱。工具会把相对路径解析到 workspace 下但如果没有启用 sandbox绝对路径仍可能访问宿主机其他位置。这句话是理解 workspace 的关键。可以这样画Workspace 负责 默认 cwd 启动文件 Agent 指令 用户信息 工具约定 记忆文件 Canvas 文件 不直接负责 阻止所有宿主文件访问 多租户隔离 命令审批 浏览器权限 网络边界所以 workspace 更像“Agent 的家”和“项目上下文根目录”。真正的安全边界还要靠 sandbox、exec approvals、tool policy、Gateway auth、OS 权限等一起完成。默认位置和 profileOpenClaw 的默认 workspace 通常是~/.openclaw/workspace如果设置了非 default 的OPENCLAW_PROFILE默认位置会变成~/.openclaw/workspace-也可以在配置里覆盖{ agents: { defaults: { workspace: ~/.openclaw/workspace } } }这解释了为什么同一台机器上可能出现多个 workspace。但官方文档也提醒保留多个 workspace 目录可能导致 auth 或状态漂移因为同一时间只有一个 workspace 是活跃的。如果你看到 Agent “好像忘了规则”第一反应不应该是模型变笨。先检查当前 profile 是什么 active workspace 是哪个 AGENTS.md 是否在这个 workspace 里 配置指向了哪个路径Workspace 文件图谱OpenClaw workspace 不是空目录。它有一组约定文件。常见文件包括AGENTS.md Agent 操作规则和使用记忆的方式 SOUL.md persona、语气和边界 USER.md 用户是谁、如何称呼用户 IDENTITY.md Agent 名字、风格、身份信息 TOOLS.md 本地工具约定和使用习惯 HEARTBEAT.md heartbeat run 的轻量 checklist BOOT.md Gateway restart 后的启动检查 BOOTSTRAP.md 第一次初始化 ritual memory/YYYY-MM-DD.md 每日记忆日志 MEMORY.md 可选的长期记忆摘要 skills/ workspace 级别技能 canvas/ Canvas UI 文件这些文件不是装饰。它们会影响 Agent 如何理解你、如何执行任务、如何使用工具、如何保持长期上下文。Workspace 如何进入上下文Agent 不会把整个 workspace 一股脑塞进模型。更合理的方式是启动时加载关键 bootstrap 文件 根据任务读取相关文件 必要时检索 memory 工具执行时以 workspace 为默认 cwd 把结果写回 transcript 或 workspace这背后的原则是常驻上下文要短 任务相关上下文要准 长期记忆要可检索例如AGENTS.md 适合放长期操作原则 TOOLS.md 适合放本机工具命令和路径约定 memory/YYYY-MM-DD.md 适合放当天变化 项目文件 需要时再读取如果你把大量日志、长文档、历史聊天都塞进AGENTS.mdAgent 每次启动都会背负巨大上下文负担。这是 workspace 设计中最常见的问题之一。Workspace 与工具执行工具执行时workspace 通常是默认 cwd。这带来一个好处相对路径稳定例如 Agent 调用rg TODO .它知道.大概率是当前 workspace而不是系统某个随机目录。但这不等于安全隔离。如果没有启用 sandbox绝对路径仍可能指向 workspace 外/Users/me/Desktop /etc /tmp所以你要把“路径组织”和“权限隔离”分开看。Workspace 负责组织。Sandbox 和 approvals 负责限制。Sandbox 启用后workspace 语义会变化官方 workspace 文档提到当 sandboxing 启用且workspaceAccess不是rw时工具会在~/.openclaw/sandboxes下的 sandbox workspace 中运行而不是宿主 workspace。这意味着未启用 sandbox workspace 是宿主机上的默认 cwd 启用 sandbox 工具可能在隔离副本或 sandbox workspace 中运行用户容易困惑的是为什么 Agent 明明改了文件我宿主目录没看到 为什么 shell 看到的路径和我本机不一样 为什么浏览器或命令的环境变了答案往往和 sandbox mode、workspaceAccess、挂载策略有关。什么不应该放进 workspace官方文档列出了一些不应该提交进 workspace repo 的内容例如~/.openclaw/openclaw.json 模型 auth profiles credentials session transcripts managed skills per-agent Codex runtime account/config/thread state这些属于运行状态、密钥、凭证或内部状态。它们不是课程项目、不是可公开资料也不应该随便进 git。一个稳妥原则可解释 Agent 行为的规则可以放 workspace 能恢复用户上下文的私有记忆可以放私有 repo 密钥、token、凭证、session 内部状态不要放项目仓库Workspace skills 的优先级Workspace 下的skills/很重要。官方文档说明workspace-specific skills 是该 workspace 的最高优先级 skill location。当名称冲突时它会覆盖 project、personal、managed、bundled 等其他来源。这意味着workspace 可以定义非常本地化的能力比如你的公司内部有特定部署命令skills/deploy-company-service/这个 skill 可以只在当前 workspace 生效。但这也意味着你要小心命名冲突。如果 workspace skill 和 bundled skill 同名它可能改变 Agent 在这个 workspace 里的行为。一个真实场景你把 OpenClaw 用作个人运维助手。Workspace 里有AGENTS.md 永远先读 runbook危险命令先解释 TOOLS.md 日志目录、kubectl context、常用脚本路径 memory/2026-05-28.md 今天迁移了 billing service skills/deploy-check/ 公司内部部署检查流程你说检查 billing service 昨天发布后有没有异常。Agent 会从 workspace 得到很多隐含信息应该如何行动 哪些工具可用 日志在哪里 今天有什么背景 哪些操作需要谨慎但它是否能执行 shell、能否访问宿主路径、是否需要 approval仍由工具策略和 sandbox 决定。这就是 workspace 的正确位置。常见误解误解一Workspace 就是项目源码目录不只是。它可以包含项目文件也包含 Agent 指令、用户信息、记忆、工具约定、workspace skills 和 Canvas 文件。误解二Workspace 是安全沙箱不是。官方文档明确说 workspace 是默认 cwd不是硬沙箱。需要隔离时应配置 sandbox。误解三把所有东西写进 AGENTS.md 会更聪明不会。过大的常驻上下文会浪费 token稀释重点增加模型误读概率。误解四多个 workspace 可以随便混用不建议。多个活跃路径容易导致配置、认证、记忆和状态漂移。最后总结Workspace 是 OpenClaw 的上下文根目录和默认执行位置。它承载 Agent 指令、用户信息、工具约定、记忆、skills 和 Canvas 文件也为工具提供默认 cwd。但它不是硬安全边界。一句话总结Workspace 负责让 Agent 知道“我在哪、该按什么规则做事”sandbox 和 approvals 才负责限制“我能碰什么”。本节作业检查你的 workspace 里有哪些 bootstrap 文件。用自己的话解释 workspace 和 sandbox 的区别。设计一个合理的TOOLS.md只放本机工具约定不放大段日志。思考为什么多个 workspace 会导致状态漂移列出哪些文件不应该提交到 workspace 私有 repo。下一节预告下一节讲权限模型Shell、Browser、文件读写的安全边界我们会把 Gateway auth、operator trust、exec approvals、browser isolation、sandbox 和 workspaceAccess 放在一张图里讲清楚。参考资料OpenClaw DocsAgent workspaceOpenClaw DocsSandboxingOpenClaw DocsSecurityOpenClaw DocsExec approvals原文链接Workspace文件系统、项目上下文和执行边界 | Harries Blog™
