部署团队服务器
本指南将生产团队部署的各个部分连接起来:一个持久化 Gateway、Cloudflare Tunnel 和 Access、个人登录、GitHub 身份、操作员角色,以及来自另一个 Gateway 的可选只读共享。从一台服务器开始。当需要不同的凭据、更新时机或操作员时,再添加一个独立的发布或预发布服务器。
对于更简短的协作演练,请参见团队设置。本指南使用 team.example.com 进行协作,并使用 release.example.com 作为可选的第二个 Gateway。请将其替换为你自己的主机名;每个 Gateway 都需要自己的配置和状态。
我们如何用 OpenClaw 构建 OpenClaw¶
我们使用 team.openclaw.ai 作为 OpenClaw 本身的共享开发工作区。维护者和代理在相同的对话中处理仓库更改:
- 开始一个仓库任务。 在新对话中选择 OpenClaw 项目,并选择 Worktree 以使用受管理的分支和检出。给代理一个具体的更改以及证明其有效的检查。
- 协作。 有访问权限的队友可以打开会话、添加上下文并引导下一轮。分配所有者 以便跟进;创建者和参与者的归属保持独立。
- 审查工作。 检查代理的结果和检出差异,运行相关测试,并在合并前解决审查发现。
- 发布并跟踪 CI。 在检查所选的GitHub 发布账户后,使用发布 PR。关联的拉取请求及其 CI 详情仍可在对话中查看。
该截图显示一个实时仓库任务,裁剪到其对话。有关差异、文件和 PR 控件,请参见聊天和代码审查。
构建下一个版本不会替换正在运行的服务器。我们将部署交由其自身的审批和生命周期负责人管理,并进行协调激活和验证。参见保持运维可恢复。
开始之前¶
- 一台具有持久存储和专用服务账户的 Linux 主机。使用受支持的 Node 运行时和一个OpenClaw 安装。
- 一个由 Cloudflare 管理的域名、Zero Trust 账户,以及主机上的
cloudflared。 - 一个身份提供商,以及关于谁可以登录的明确策略。
- 模型凭据,以及(如需要)用于团队聊天的机器人账户。
- 管理 SSH 访问权限、私有密钥存储,以及位于服务器故障域之外的备份目标。
一个 Gateway 是一个信任边界。角色和会话所有权支持协作;它们不会将敌对用户彼此隔离。将不受信任的代码保留在沙箱或远程工作器中。对于互不信任的团队,使用独立的 Gateway、操作系统用户或主机。参见安全信任模型。
1. 在单一服务账户下安装¶
以将运行 Gateway 的账户完成入门指南,包括模型设置和托管服务安装:
后续的配置、备份和更新命令都应使用同一账户执行。之后以 root 身份运行设置会创建不同的主目录,并可能选择另一个 Gateway。在服务和维护环境中保留任何自定义的 OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH 和配置文件选择器。在 Linux 上,验证用户服务在注销后仍可用;参见Gateway 服务管理。
仅允许从管理网络访问 SSH。将 Gateway 保持在回环地址上,不要公开开放 TCP 18789。Cloudflare Tunnel 建立出站连接;它不需要入站 Gateway 防火墙规则。
选择一个代理 ID,例如 assistant,并在通道绑定和角色代理列表中一致使用它。以下示例假设该代理已存在。保持共享工作区说明简洁,并将部署密钥排除在 AGENTS.md、IDENTITY.md 和个人说明之外。
2. 配置公共 URL 和经过身份验证的入口¶
在暴露隧道之前,为 team.example.com 创建一个 Access 应用。最初仅允许将完成设置的管理员加入。选择由预期身份提供商支持的 Access 策略;不要为 Control UI 或其 WebSocket 创建公开绕过。
按照Cloudflare Tunnel 和 Access创建隧道和 DNS 记录。其入口应仅将所选主机名路由到回环 Gateway:
tunnel: <tunnel-id>
credentials-file: /etc/cloudflared/<tunnel-id>.json
ingress:
- hostname: team.example.com
service: http://localhost:18789
- service: http_status:404
保护隧道凭据文件,并将 cloudflared 作为服务运行。使用SecretRef保留一个私有的本地维护密码;以下示例期望 OPENCLAW_GATEWAY_PASSWORD 对 Gateway 服务和拥有账户的 CLI 均可用。不要将该密码分发给队友:本地密码访问权限代表共享所有者。
将以下内容合并到现有配置中,同时保留你的代理、模型和通道:
{
gateway: {
mode: "local",
bind: "loopback",
publicOrigin: "https://team.example.com",
trustedProxies: ["127.0.0.1", "::1"],
auth: {
mode: "trusted-proxy",
password: { source: "env", provider: "default", id: "OPENCLAW_GATEWAY_PASSWORD" },
identityScopes: {
"admin@example.com": ["operator.admin"],
},
trustedProxy: {
userHeader: "cf-access-authenticated-user-email",
requiredHeaders: ["cf-access-jwt-assertion"],
allowLoopback: true,
deviceAutoApprove: {
enabled: true,
scopes: ["operator.read", "operator.write", "operator.approvals", "operator.questions"],
},
},
},
roles: {
default: "observer",
definitions: {
observer: {
sessions: { others: "view" },
agents: [],
scopes: ["operator.read"],
},
member: {
sessions: { others: "write" },
agents: ["assistant"],
scopes: ["operator.read", "operator.write", "operator.approvals", "operator.questions"],
},
administrator: {
sessions: { others: "write" },
agents: "*",
scopes: ["operator.admin"],
},
},
},
},
}
切换到可信代理身份验证时,删除任何早先的 gateway.auth.token 和 OPENCLAW_GATEWAY_TOKEN:共享令牌与此模式不兼容。支持私有的本地密码回退。验证配置,然后使用所属服务的生命周期来使设置更改生效:
allowLoopback 会信任本地进程以及 cloudflared。OpenClaw 会检查代理来源和必需请求头;这些请求头的存在并不等同于 Access JWT 签名验证。外部身份验证边界是 Access 加上私有源。不要运行可以访问此监听器的恶意工作负载。有关请求头和客户端地址要求,请参阅可信代理身份验证。
设置一次公共 URL¶
publicOrigin 告诉 OpenClaw 要对外提供哪个外部 URL,并提供默认的浏览器源允许列表。对于从同一源提供的 Control UI,请保持 gateway.controlUi.allowedOrigins 未设置。
仅当你需要不同的浏览器策略(例如单独托管的 Control UI)时,才设置显式的 allowedOrigins 列表。显式列表会取代公共源默认值;如果两者都应连接,也请包含公共源。显式空列表不会继承 publicOrigin。现有的本地和私有网络源规则仍然适用。
如果没有 gateway.publicOrigin,浏览器可能可以工作,但代理的会话查找没有链接构建规则,其运行时上下文也没有会话 URL。请设置裸 HTTPS 源,不要包含路径、查询或凭据。如果 Control UI 使用路径前缀,请单独配置 gateway.controlUi.basePath。
对于仅缺少此设置的现有服务器:
此条件写入拒绝覆盖现有值。启用实时配置重载后,公共源无需重启 Gateway 即可生效。当允许列表是继承时,使用旧源的浏览器必须从被接受的源重新连接。显式允许列表保持不变。新准备的工具上下文会接收链接规则;已在运行的回合可以保留其先前的上下文。在第二台服务器上设置 https://release.example.com,而不是复制第一台服务器的 URL。
现有安装会保留其显式允许列表,包括早先设置或 Doctor 运行保存的值。升级到具有此默认值的版本后,如果你希望它遵循 publicOrigin,请使用 openclaw config unset gateway.controlUi.allowedOrigins 删除该列表;先检查是否不需要额外的 UI 源。启动和 Doctor 不会将继承的默认值写入保存的配置。
3. 引导管理员并分配角色¶
让管理员通过 Access 登录一次。其持久 Gateway 配置文件会被创建,初始为观察者角色。从本地维护 Shell 中列出配置文件并识别已验证的人员:
openclaw users list --json
openclaw gateway call users.setRole \
--params '{"profileId":"<administrator-profile-id>","role":"administrator"}' \
--json
角色更改会关闭该人员活动的 Gateway 连接。重新连接浏览器。管理员需要显式的 identityScopes 授权和管理员角色上限。本地共享所有者仍可用于维护,并且不能被分配个人角色。
将 Access 策略扩展到你的团队。每位成员首次登录后,通过相同方法为其配置文件分配 member 角色。观察者可以读取可见会话,但在此示例中不能启动代理工作。不要临时将默认角色设为管理员来引导某人。
此示例有意自动批准具有非管理员作用域的 UI 设备,然后通过角色限制每个人。如果你希望手动设备注册,请省略自动批准。不要将 operator.admin 添加到自动设备授权中;请改用选定的已验证身份。有关更窄的仅限会话和需要沙箱的角色,请参阅操作者作用域。
对于发布 Gateway,保持观察者默认设置并只分配少数发布操作者会很有用。角色分配是本地于每个 Gateway 的;被协作服务器接纳不会授予发布权限。
4. 使用已验证的 GitHub 身份同步人员¶
保持这些职责分离:
| 职责 | 配置或所有者 |
|---|---|
| 谁可以访问网站 | Cloudflare Access 及其身份提供程序 |
| 哪位用户已登录 | 已验证登录和 Gateway 配置文件 |
| 该用户可以执行哪些操作 | 连接作用域和命名操作者角色 |
| 哪个账户发布代码 | 系统、代理或个人 GitHub 连接 |
在 Access 中使用 GitHub 身份提供程序时,OpenClaw 会查询 Access 的身份端点,验证其邮箱与已认证的代理主体匹配,并将不可变的数字 GitHub 账户 ID 解析为其当前登录名。然后,姓名和头像可以通过正常的登录/配置文件同步进行更新。保存的自定义配置文件选择仍由用户模型管理。
这是由登录驱动的同步,而不是在后台导入每个 GitHub 组织成员。配置文件和角色是本地于每个 Gateway 的。同一个已验证的 GitHub 账户可以在两台服务器上识别一个人,而无需使其本地配置文件 ID 相等。
使用 OIDC 提供程序而不丢失现有配置文件¶
OIDC 登录可以通过其已验证邮箱保留现有配置文件。在更改提供程序或邮箱地址之前,从管理员的维护会话中将新的已验证地址链接到现有人员:
Before switching sign-in, also add the new verified address to any
gateway.auth.identityScopes grants that person needs. For the administrator
above, the new address needs its own ["operator.admin"] entry: linking an email
preserves the profile and role but does not copy the old address's scope grant.
Update any Access policy or trustedProxy.allowUsers email allowlist as needed.
Keep the old grant during the migration, verify the profile, aliases, role, and
effective permissions after reconnecting with the new address, then retire the
old grant if that identity should no longer have access. Do not merge people by
display name or copy profile databases between live servers.
在切换登录之前,还需将新的已验证地址添加到该人员所需的任何
gateway.auth.identityScopes 授权中。对于上述管理员,新地址需要拥有自己的
["operator.admin"] 条目:关联电子邮件会保留个人资料和角色,但不会复制旧地址的范围授权。
根据需要更新任何 Access 策略或 trustedProxy.allowUsers 电子邮件允许列表。
在迁移期间保留旧授权,使用新地址重新连接后,验证个人资料、别名、角色和
有效权限,然后如果该身份不应再拥有访问权限,则弃用旧授权。不要通过显示名称
合并人员,也不要生产服务器之间复制个人资料数据库。
For verified GitHub credit through OIDC, configure the explicit
cloudflareAccessOidc issuer, provider ID, and account-ID claim described in
Cloudflare OIDC setup.
The provider must verify the linked GitHub account, and Access must forward its
numeric account ID claim. A username or arbitrary OIDC subject is not a verified
GitHub account ID. Conflicts require administrator linking; the claim does not
assign a role or change the account that publishes code.
对于通过 OIDC 验证的 GitHub 署名,请配置
Cloudflare OIDC 设置 中描述的显式
cloudflareAccessOidc 颁发者、提供商 ID 和账户 ID 声明。
提供商必须验证关联的 GitHub 账户,并且 Access 必须转发其
数字账户 ID 声明。用户名或任意 OIDC 主体不是经过验证的
GitHub 账户 ID。冲突需要管理员关联;该声明不会
分配角色,也不会更改发布代码的账户。
If admission depends on GitHub organization membership or repository permission, enforce that in Access or the identity provider. An organization policy for the GitHub IdP does not automatically cover a separate OIDC IdP. Understand when eligibility is rechecked and revoke existing Access sessions when removal must take effect before their normal expiry.
如果准入取决于 GitHub 组织成员身份或仓库权限, 请在 Access 或身份提供商中强制执行。针对 GitHub IdP 的组织策略不会自动覆盖单独的 OIDC IdP。了解 资格何时重新检查,并在移除必须在正常过期前生效时撤销现有 Access 会话。
为仓库工作配置 GitHub 访问¶
Install gh for the Gateway service account. In Settings → Profile → GitHub
connections, an administrator chooses For the system to connect the shared
publication account. An agent can have an administrative override under
Agents → Tools. Verify the selected account before publishing.
为 Gateway 服务账户安装 gh。在 Settings → Profile → GitHub
connections 中,管理员选择 For the system 以连接共享
发布账户。代理可以在
Agents → Tools 下拥有管理员覆盖。发布前验证所选账户。
My GitHub is a separate personal connection for explicitly selected publication. It does not change the shared shell account or establish verified sign-in identity. Git co-author credit is also separate: it uses verified human participants and their saved consent preference.
My GitHub 是一个独立的个人连接,用于明确选择的 发布。它不会更改共享 shell 账户,也不会建立经过验证的 登录身份。Git 共同作者署名也是独立的:它使用经过验证的人类 参与者及其保存的同意偏好。
Use the Gateway's Publish PR action for its managed publication path. Managed identity does not rewrite an existing local repository's SSH remote or Git network credentials. Successful account verification also does not prove write permission to every repository. See GitHub identity for agent tools.
使用 Gateway 的 Publish PR 操作来使用其受管理的发布路径。 受管理的身份不会重写现有本地仓库的 SSH 远程或 Git 网络凭据。成功的账户验证也不能证明 对每个仓库都有写入权限。参见 代理工具的 GitHub 身份。
An optional gateway.controlUi.github.token serves GitHub lookups and project
discovery. For Enterprise, set gateway.controlUi.github.host to the selected
gateway.github.host so the service credential is used only for that host.
Keep it in a dedicated SecretRef instead of accidentally selecting a
publisher through a process-wide GH_TOKEN or GITHUB_TOKEN. Read credentials,
publication credentials, and each person's sign-in identity have different jobs.
可选的 gateway.controlUi.github.token 用于 GitHub 查找和项目
发现。对于 Enterprise,请将 gateway.controlUi.github.host 设置为所选的
gateway.github.host,以便服务凭据仅用于该主机。
将其保存在专用的 SecretRef 中,而不是通过进程范围的 GH_TOKEN 或 GITHUB_TOKEN 意外选择
发布者。读取凭据、
发布凭据和每个人的登录身份都有不同的职责。
5. 连接聊天和远程客户端¶
Follow Team setup for channel allowlists, mention requirements, and DM pairing. Website admission does not configure the bot's channel allowlist. If a channel sender should resolve to an existing person, use the explicit administrator-attested channel identity links in User model; matching display names are insufficient.
按照 团队设置 配置频道 允许列表、提及要求和 DM 配对。网站准入不会 配置机器人的频道允许列表。如果频道发送者应解析为现有人员,请使用 用户模型 中显式管理员证明的频道身份链接;匹配的显示名称是不够的。
Browser cookies do not authenticate CLI, TUI, or node connections. Remote CLI
clients need gateway.remote.edgeAuth and their own Access login; see
Remote access.
浏览器 Cookie 不会认证 CLI、TUI 或节点连接。远程 CLI
客户端需要 gateway.remote.edgeAuth 和它们自己的 Access 登录;参见
远程访问。
Nodes and cloud workers need a route that authenticates every required join,
WebSocket, and transfer request. Prefer the Access service-token setup in
Cloudflare machine access.
A browser working while openclaw connect receives HTTP 302 means the machine
request reached Access, not that node pairing succeeded. Keep machine credentials
out of browser links and do not bypass Access for the whole Gateway.
节点和云工作器需要一个路由,以认证每个必需的加入、
WebSocket 和传输请求。优先使用 Cloudflare 机器访问 中的 Access 服务令牌设置。
当 openclaw connect 收到 HTTP 302 时浏览器可以工作,意味着机器
请求到达了 Access,而不是节点配对成功。将机器凭据
保留在浏览器链接之外,不要为整个 Gateway 绕过 Access。
6. 为小部件提供单独的沙箱源¶
Inline Canvas widgets and MCP Apps use a separate sandbox listener. Behind HTTPS ingress, configure a second hostname that reaches that listener instead of letting the browser try the Gateway's public hostname on port 18790:
内联 Canvas 小部件和 MCP Apps 使用单独的沙箱监听器。在 HTTPS 入口后面,请配置一个到达该监听器的第二个主机名,而不是 让浏览器尝试 Gateway 的公共主机名和端口 18790:
Create a separate proxied DNS CNAME for team-sandbox.example.com pointing to
<tunnel-id>.cfargotunnel.com, then add
team-sandbox.example.com -> http://localhost:18790 to the tunnel ingress before
its catch-all rule, using the configured sandbox port if different. Adding an
ingress rule alone does not create the DNS record. See Cloudflare's
tunnel DNS routing.
Keep this hostname outside the interactive Access application and route it only
to the sandbox listener, never the main Gateway. The sandbox serves the isolated
renderer shell; authenticated widget content travels through the Gateway. Do not
put other authenticated applications on the sandbox origin.
为 team-sandbox.example.com 创建单独的已代理 DNS CNAME,指向
<tunnel-id>.cfargotunnel.com,然后在隧道入口的 catch-all 规则之前添加
team-sandbox.example.com -> http://localhost:18790,如果不同则使用已配置的沙箱端口。仅添加入口规则不会创建 DNS 记录。参见 Cloudflare 的
隧道 DNS 路由。
将此主机名保留在交互式 Access 应用程序之外,并且仅将其路由到
沙箱监听器,绝不路由到主 Gateway。沙箱提供隔离的
渲染器 shell;经过身份验证的小部件内容通过 Gateway 传输。不要
将其他经过身份验证的应用程序放在沙箱源上。
Canvas can start this listener lazily even when MCP Apps are not enabled. Enable MCP Apps separately only if you need that capability; see MCP Apps. Test a real widget after setup: a healthy chat page does not prove its iframe can load.
即使未启用 MCP Apps,Canvas 也可以延迟启动此监听器。 仅当你需要该功能时,才单独启用 MCP Apps;参见 MCP Apps。设置后测试一个真实小部件:健康的聊天页面 不能证明其 iframe 可以加载。
7. 从另一个 Gateway 共享选定会话¶
To show release-server conversations on the collaboration server, configure Session Share. On the source, enable the plugin with an explicit group:
要在协作服务器上显示 release-server 对话,请配置 Session Share。在源上,使用显式组启用插件:
{
plugins: {
entries: {
"session-share": {
enabled: true,
config: { share: { groups: ["Team"] } },
},
},
},
}
On the receiver, the gateway.publicOrigin configured above supplies the join
endpoint when the loopback Gateway has no other advertised route. For the Access
service-token topology above, use that same HTTPS hostname. If you operate a
separate authenticated machine endpoint, set
plugins.entries.device-pair.config.publicUrl to its URL instead:
在接收方,上述配置的 gateway.publicOrigin 在 loopback Gateway 没有其他通告路由时提供加入
端点。对于上述 Access
服务令牌拓扑,请使用相同的 HTTPS 主机名。如果你运营一个
单独的经过身份验证的机器端点,请将
plugins.entries.device-pair.config.publicUrl 设置为其 URL:
加入代码会保留现有的 Tailscale、远程和 bind 派生路由,然后回退到 publicOrigin。配对专用的 publicUrl 覆盖优先于发现机制。核心加入代码创建不需要启用 device-pair 插件。
参见 节点入门。
在源端,以源 Gateway 的账户、状态目录和配置运行节点,并仅使用以下两个只读会话命令:
openclaw connect <join-url> --service \
--commands openclaw.sessions.list.v1,openclaw.sessions.read.v1
在接收端批准目标设备,并确认两条命令的允许列表。将选定的源会话移动到 Team 组。子代理和隐身会话仍被排除。删除该组会撤销新的读取,但无法撤回他人已经读取的文本。
接收端的 linkGitHubIdentities: true,针对已配对的节点 ID 配置后,可以将已验证的远程 GitHub 账户 ID 显示为匹配的本地个人资料。
这是归属标识,不是角色或所有权授权。该视图保持只读;它不会授权继续源会话或在那里执行命令。
普通的源会话 URL 仍指向该源自己的 publicOrigin,并且需要源访问权限。
验证完整流程¶
使用主机检查和两个真实用户账户:
- 以服务所有者身份运行
openclaw config validate --json、openclaw gateway status --deep和openclaw security audit。解决非预期暴露。 - 确认未认证的公共请求会到达 Access,然后登录并进入已连接的 Control UI。仅有 Access 重定向不足以证明 Gateway 健康。
- 确认两个人的不同个人资料、管理员/成员行为以及观察者限制。更改角色后重新连接。
- 向代理请求当前会话的链接和另一个可见会话的链接。打开两者并检查主机和目的地。缺失的链接规则指向
publicOrigin,而不是allowedOrigins。 - 测试一次模型轮次、预期的频道回复、如果启用了 widget 则测试 widget,以及如果使用则测试一次节点连接。在请求发布前,检查所选 GitHub 账户和实际仓库权限。
- 如果共享会话,从接收端读取一个选定的源对话,然后从源组中删除一个一次性共享会话,并验证新的接收端读取被拒绝。
保持运维可恢复¶
每个安装使用一个生命周期所有者。对于常规托管安装,使用 openclaw update 和原生 Gateway 服务命令。如果外部部署系统拥有该服务,则改用该所有者;不要通过第二个更新器、直接重启或就地源码构建与之竞争。与团队协调中断,并在激活后验证服务版本。
参见 更新 和 重启恢复。
协作服务器和发布服务器可以有意遵循不同的更新计划。明确每项策略;复制配置不应在另一台服务器上静默启用自动部署。通过 gateway.controlUi.environment 保持视觉环境标签不同。
在重大更新前创建并验证备份:
openclaw backup create --verify
openclaw backup restore <archive.tar.gz> --target <fresh-restore-directory>
恢复命令会暂存恢复数据;激活它是单独的离线操作。保护凭据并保留主机外副本。使用原生备份所有者的 SQLite 快照,而不是复制实时数据库/WAL 文件。不要用旧快照覆盖当前数据库来回滚实时服务器。参见 备份。
为依赖项、构建、SQLite 快照验证和备份预留持久磁盘和临时空间。根磁盘空间很大并不能解决较小的 /tmp 配额问题。在实际服务环境中配置所需的临时空间,而不仅仅是在 SSH shell 中。在 Btrfs 上,除了 df,还要检查元数据分配和保留的快照:快照可能在文件删除后仍占用空间。只清理已知可丢弃的数据和已完成的恢复点。
监控进程重启、就绪状态、频道连接、存储以及真实的会话/模型故障。将事件告警放在可能宕机的 Gateway 之外。HTTP 根路径正常、机器人安静或 Access 登录成功,都不足以证明服务能够完成工作。
故障排查¶
| 症状 | 检查 |
|---|---|
| 浏览器可用,但代理无法提供会话链接 | 设置本服务器的 gateway.publicOrigin;重新加载后准备一个新轮次。 |
| Access 成功,但 Gateway 拒绝连接 | 检查回环信任、转发的客户端地址、必需的身份头以及 allowedOrigins。 |
| 管理员以观察者身份登录 | 为真实个人资料分配管理角色,并为已验证身份授予 operator.admin,然后重新连接。 |
| OIDC 迁移创建了另一个人 | 验证登录邮箱,并将其别名显式链接到现有个人资料。 |
| GitHub 登录看起来正确,但发布使用了另一个账户 | 分别检查系统/代理/个人发布选择和仓库 Git 认证。 |
| 聊天可用,但 widget 失败 | 检查独立的沙箱源、隧道端口,以及该主机名上不存在交互式 Access 质询。 |
| 症状 | 检查项 |
|---|---|
| 节点加入时收到 HTTP 302 | 在所有必需路由上提供机器 Access 身份验证。 |
| 共享会话缺失或名称未关联 | 检查源组、节点账户/状态、双命令允许列表、接收者角色以及已验证的数字 GitHub ID。 |
| 尽管磁盘空间充足,更新仍失败 | 重试前,检查服务临时空间配额、文件系统元数据以及保留的快照。 |
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw