Gateway 与 Workspace 理解_OpenClaw入门基础教程

正式教程页概念澄清页

如果只用一句话区分：Gateway 是一直在跑的消息与控制中枢，Workspace 是 agent 默认工作的目录和上下文入口。 这两个概念一旦混了，后面你会在排障、配渠道、装 Skill、改配置时到处绕弯。

这页最值得解决的问题

很多人不是不会装，也不是不会发消息，而是分不清“问题到底出在服务、目录、配置，还是会话状态”。这页就是帮你先把这几个层级拆开。

先把最核心的区别讲清楚

Gateway

一个常驻进程
负责 routing、control plane 和 channel connections
更像“服务”和“消息总枢纽”

Workspace

agent 默认工作的目录
更像“工作现场”和“上下文入口”
影响文档读取、本地 Skill 和项目文件操作

最实用的判断方式

平台没回消息、控制台打不开 → 先查 Gateway
读错文档、Skill 行为怪 → 先查 Workspace
配置和会话去哪了 → 多半去 `~/.openclaw/` 找

Gateway 到底负责什么

官方 runbook 把 Gateway 定义得很明确：它是 always-on process for routing, control plane, and channel connections。翻成更容易理解的话，就是：

外部消息先进 Gateway。
Gateway 决定这条消息该落到哪个会话、哪个 agent、哪个渠道绑定。
Control UI / Dashboard 依赖 Gateway 提供状态和控制面。
飞书、Telegram、Discord 这类渠道连接，本质上也挂在 Gateway 上。

大多数人不需要多个 Gateway。官方也明确建议：绝大多数安装只跑一套 Gateway 就够了，只有当你真的需要严格隔离或冗余时，才考虑多实例。

平时最常用的 Gateway 命令

openclaw gateway status
openclaw gateway restart
openclaw gateway stop
openclaw logs --follow

如果你只记前两条，其实已经够处理很多日常问题了：先看状态，再决定要不要重启。

Workspace 到底是什么

Workspace 更像 agent 的“工作现场”。它通常是 agent 默认的当前目录，也是它读取项目文档、写本地文件、加载 workspace-local skills 的起点。官方默认路径一般是：

~/.openclaw/workspace

但要特别注意：Workspace 不是 OpenClaw 所有状态的总目录。它只是 agent 工作时最常站着的地方。

哪些东西通常在 Workspace 里

面向当前项目的文档和说明，比如 AGENTS.md。
你希望 agent 优先读取的项目文件。
workspace-local skills，例如 <workspace>/skills。
你让它新建或修改的普通项目文件。

这也是为什么很多人会觉得“工作区会影响结果”了，因为 agent 在这里最容易读到上下文，也最容易碰到你额外放进去的说明和技能。

哪些东西不在 Workspace，而在 OpenClaw 状态目录里

这是最容易搞混的一块。真正的状态和配置更多在 ~/.openclaw/ 下，例如：

~/.openclaw/openclaw.json
~/.openclaw/credentials/
~/.openclaw/agents/<agentId>/sessions/
~/.openclaw/skills/

也就是说：

配置不主要存 workspace。
凭证不主要存 workspace。
会话记录 不主要存 workspace。
共享技能 也不一定在 workspace 里。

这就是为什么“删掉一个项目目录”并不等于“把 OpenClaw 整个状态清干净”。

Bootstrapping 和 Skills 为什么会让 Workspace 更容易被误解

首次 bootstrapping 时，官方会在 workspace 里播种几份关键文件，例如 AGENTS.md、BOOTSTRAP.md、IDENTITY.md、USER.md。随后一部分内容会继续写入或整理，BOOTSTRAP.md 最终会被移除。

与此同时，技能系统又支持 workspace-local skills，而且 workspace 里的 skills 优先级高于共享技能。这意味着同一个名字、同一种用途的 Skill，如果你在工作区里放了一份本地版本，它很可能会覆盖共享版本的行为。

“为什么我装了一个 Skill，但表现跟别人不一样？” 可能是 workspace 里已经有本地版本。
“为什么换了项目目录，行为突然变了？” 可能是你切换了另一套工作区上下文。

Workspace 不是安全沙箱

Workspace 是默认工作目录，不等于硬沙箱。它会影响 agent 默认在哪儿读写文件，但并不意味着系统绝对不可能访问其他路径。

所以不要把“切到某个 workspace”理解成“已经获得完整文件隔离”。真正的权限边界，还是要靠工具权限、运行环境和更上层的安全策略来控制。

新手最常见的 4 个误解

把 Gateway 当成一个目录：其实它是服务和控制面，不是文件夹。
把 Workspace 当成全部状态目录：实际上凭证、配置、会话多数在 ~/.openclaw/。
以为多开几个 workspace 就等于多智能体隔离：真正隔离还要看 agent、bindings 和状态目录。
一出问题就删 workspace：很多问题根本不在 workspace，而是在 Gateway、配置、设备授权或模型连接。

最实用的判断口诀

“消息没进来、控制台打不开、渠道掉线” → 先查 Gateway。
“上下文不对、读错文档、Skill 行为怪” → 先查 Workspace。
“配置丢了、凭证不见了、会话没了” → 多半去 ~/.openclaw/ 里找，不是去 workspace 里找。