SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场openclaw-team-handoff

openclaw-team-handoff

智能体与模型

查看项目

更新于 10-16 06:57

技能介绍

用途

Team Handoff 用于把本地工作交接给共享的 OpenClaw Gateway。当用户说“在团队服务器上为这个开一个会话”“把这项工作交接给……”或“为新智能体总结一下并在……上启动它”，且目标是位于身份感知代理（Cloudflare Access）之后的共享 OpenClaw Gateway 时使用。

它通过一次 Gateway 请求，以操作者自己的身份启动一个 worktree 会话，并返回会话 URL。无需浏览器自动化、无需 SSH、无需轮询。

主要能力

  • 以操作者自身身份向共享 OpenClaw Gateway 发起一次请求，创建 worktree 会话。
  • 支持通过 --message-file 传入交接内容，或先推送分支再以简短消息交接。
  • 返回 Control UI 形式的会话 URL、session key 和 run id。
  • 提供 probe、create、status、archive 等子命令。
  • 使用隔离的 CLI profile，不触碰本地 Gateway 配置。

使用方式

一次性设置（每台机器）

操作者配置位于任何仓库之外： ${XDG_CONFIG_HOME:-~/.config}/openclaw/team-handoff.env

配置项包括：

  • OPENCLAW_HANDOFF_URL=https://gateway.example：共享 Gateway 的公开 origin
  • OPENCLAW_HANDOFF_AGENT=main：该 Gateway 上的默认 agent id
  • OPENCLAW_HANDOFF_PROJECT=example-project：默认 projects.list id
  • 可选：OPENCLAW_HANDOFF_CLI、OPENCLAW_HANDOFF_PROFILE_DIR、OPENCLAW_HANDOFF_SSH_HOST

脚本使用隔离的 CLI profile，首次探测时若缺失会写入。OPENCLAW_STATE_DIR 和 OPENCLAW_CONFIG_PATH 指向该 profile 目录，其中的 openclaw.json 仅包含 gateway.mode: "remote"、gateway.remote.url，以及一个 exec secret provider，用于运行 cloudflared access token -app=<url> 以生成 Cf-Access-Token 头（gateway.remote.edgeAuth）。provider 命令必须是真实的 cloudflared 二进制文件，不能是符号链接。

人类需在每个 Access 会话生命周期内登录一次（智能体无法完成）： cloudflared access login https://gateway.example

probe 打印 ok 表示链路正常。若 exec provider "cloudflare-access" 以退出码 1 结束，或升级时出现 HTTP 302，表示登录已过期：请人类重新运行，不要自行切换到 SSH 回退方案。

无需铸造 token 的原因：当 gateway.auth.mode: "trusted-proxy" 时，代理对用户进行认证，Gateway 将身份头映射到 scopes；首次连接会自动配对 CLI 设备，使用代理的 deviceAutoApprove scopes，其中涵盖 sessions.create。

命令

bash scripts/team-handoff.sh probe
bash scripts/team-handoff.sh create \
  --label "Installed-package entry cap durable fix" \
  --name tree-cap-fix --base origin/main \
  --message-file /path/to/handoff.md
bash scripts/team-handoff.sh status <sessionKey>
bash scripts/team-handoff.sh archive <sessionKey> <sessionId>

create 会打印 url:，形式为 Control UI 的 <origin>/chat/<agent>/<label-slug>-<session-key-uuid-without-dashes>，以及 session key 和 run id。把该 URL 交给人类。创建会在 worktree 准备好之前返回；紧接着以 worktree: null 运行是正常的，agent 的第一轮会在 checkout 绑定后开始。只读取一次 status，不要循环。

交接内容

分支优先。推送工作，传入 --base <branch>，把长交接内容放在分支中（例如 .openclaw/handoff.md）；消息则只需三行：分支是什么、首先做什么、不要做什么。本地文件从 Gateway 不可达；请提交它们或总结数字。

如果没有分支，整个交接内容放入 --message-file：第一行是单行标题（会成为会话标题和 URL slug），然后是目标、带数字的已验证事实、负责人文件、商定的计划和顺序、证明预期，以及明确的非目标。

当本地会话保留部分工作时，请说明范围边界，以免两个智能体打开重复的 PR。

适用场景

  • 需要把本地工作交接给共享 OpenClaw Gateway 上的新智能体会话。
  • 团队使用位于 Cloudflare Access 之后的共享 Gateway，希望以操作者身份一键启动会话。
  • 希望避免浏览器自动化、SSH 或轮询的交接流程。

限制与失败模式

  • managed worktree allocation lease .../capacity was lost：Gateway 在缓慢的项目重新获取期间丢失了 worktree 容量租约。在同一会话中重试会因 branch already exists: openclaw/<name> 失败，因为失败尝试泄漏了其分支。请用不同的 --name 创建新会话；归档已死的会话。
  • chat.send requires idempotencyKey；sessions.patch 生命周期变更需要 expectedSessionId。
  • SSH 操作者回退：--via ssh 以 Gateway 的服务用户身份在 Gateway 主机上运行相同的 sessions.create（使用 OPENCLAW_HANDOFF_SSH_HOST、OPENCLAW_HANDOFF_REMOTE_CLI、OPENCLAW_HANDOFF_REMOTE_USER）。此时会话归操作者身份所有，而非人类。仅在人类要求时使用；切勿通过此路径更改 Gateway 配置或重启任何东西。

禁止事项

  • 不要从智能体浏览器驱动 Gateway 的 Web UI，也不要登录身份提供方。
  • 不要将本机的主 openclaw.json 指向共享 Gateway。
  • 不要循环轮询会话历史。