跳转至

openclaw agents

管理隔离的智能体(工作区 + 认证 + 路由)。运行 openclaw agents 且不带子命令,等同于运行 openclaw agents list。

示例

openclaw agents list
openclaw agents list --bindings
openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents add work --workspace ~/.openclaw/workspace-work --bind telegram:*
openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactive
openclaw agents add research --role researcher --non-interactive
openclaw agents team create --non-interactive
openclaw agents bindings
openclaw agents bind --agent work --bind telegram:ops
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
openclaw agents delete work

命令总览

agents list

选项:--json、--bindings(包含完整路由规则,而不仅仅是每个智能体的计数/摘要)。

对于显式的多智能体名册,默认徽标和 JSON 的 isDefault 字段使用 agents.defaults.systemAgent.agentId。Doctor 会在重启之间将迁移后的默认值保留在该处。若未指定,每个条目都会报告 isDefault: false;可使用 openclaw config set agents.defaults.systemAgent.agentId <id> 进行设置。Control UI 的 Set Default 操作会写入相同的指定。

Provider 状态标签会在账户 ID 旁包含可选的账户显示名称。路由规则仍通过渠道和账户 ID 来标识账户。

数据库属于另一个智能体的智能体会显示为 degraded(降级),并带有拒绝原因和修复指引。当某个次要智能体被拒绝时,Gateway 仍可继续为健康的智能体提供服务。请遵循 Doctor 的数据库恢复指引,修复文件后重启 Gateway。

Provider 行汇总所显示绑定作用域内的本地账户状态。通配符会将每个本地已知账户包含一次;消息路由仍会应用对端和账户优先级。如果存储的绑定省略或留空账户 ID,则引用字面量 default 账户键,与命令使用的渠道首选账户无关。使用 --json --bindings 可在 JSON 中包含 Provider 行。

配置中保存的身份字段具有更高优先级。未配置的字段会回退到智能体工作区中的 IDENTITY.md。不支持的头像值以及无法读取的本地图像也会回退到工作区头像。

agents add [name]

选项:--role <role>、--workspace <dir>、--model <id>、--agent-dir <dir>、--bind <channel[:accountId]>(可重复)、--non-interactive、--json。

  • 自动化标志 --workspace、--model、--agent-dir、--bind 和 --non-interactive 会选择非交互路径。非交互模式要求提供智能体名称;除非提供了 --role,否则还要求提供 --workspace。
  • 单独使用 --json 时,引导式向导仍保持交互。提示和状态写入 stderr,设置完成后 stdout 包含一条 JSON 摘要。
  • 非交互式 --json 在摘要中报告规范化后的智能体 ID,不会在 stdout 中输出额外状态消息。
  • 如果请求的绑定属于另一个智能体,非交互式创建会保留新智能体及任何无冲突的绑定,但以状态码 1 退出。摘要会指出冲突;请使用 agents bind 和 agents unbind 解决冲突,而不是重新创建该智能体。
  • main 是一个普通智能体 ID。如果安装已被另一个智能体拥有,重新创建 main 可能需要先运行 openclaw doctor --fix 来修复旧会话或共享认证的所有权。
  • 交互模式提供可选的认证复制。当智能体群没有默认智能体时,请选择源智能体或 Skip copying auth profiles(默认选项)。选择源智能体后,复制前仍需确认。除非某个凭据通过 copyToAgents: false 选择退出,否则只会复制可移植的静态凭据(api_key 和静态 token 配置);除非某个提供方通过 copyToAgents: true 选择加入,否则不会复制 OAuth 刷新令牌配置。如果不复制,OAuth 仍可通过共享认证基础使用。如果源智能体有自己的本地 OAuth 配置,请为新智能体单独登录。
  • 删除已完成的智能体 ID 可以通过 agents add 重新创建。创建操作在发布新智能体时会认领已完成的删除记录,包括在向导复制或配置认证时。如果某 ID 的删除清理仍处于待处理状态,则该 ID 会被拒绝,直到该删除操作被重试。

角色模板

--role 适用于交互式和非交互式创建,包括 --json。内置角色是 Claw 源:每个角色目录都包含一个带有身份和 SOUL.md 内容的 CLAW.md 清单,以及位于 workspace/AGENTS.md 中的操作程序。可用角色:

角色 标题 用途
coordinator 幕僚长 协调各专家,作为你的单一联系点。
researcher 研究员 收集证据并返回一份带引用的研究简报。
writer 写作者 将简报和源材料整理成可用的草稿。
reviewer 审阅者 对照需求检查产物并返回可操作的发现。

角色会植入 AGENTS.md、SOUL.md 和完整的 IDENTITY.md;USER.md 仍使用标准模板。已有工作区文件会被保留。角色的名称、emoji 和主题会保存到智能体配置中,新的角色工作区会跳过身份仪式:不会创建 BOOTSTRAP.md。内置角色不会改动技能。

角色委派设置也会被应用。独立的幕僚长会指向标准专家 ID;请使用 team 命令创建并连接全部四个智能体。

通过 Ask OpenClaw 创建智能体时,你可以为其设置一个独立于 ID 的显示名称,例如 ID 为 qa-writer 的“QA Writer”。审批会同时包含两者。显式设置的显示名称会替换角色的默认名称,同时保留其 emoji、主题和操作指令。

未知角色会被拒绝,并附上可用角色名称。带有未完成 bootstrap 的工作区无法采用角色。OpenClaw 会在添加角色文件之前检查是否已完成;被拒绝的采用不会更改工作区文件和智能体配置。请完成其 bootstrap,或选择一个新的工作区。

启用实验性 Claws 界面后,从源代码检出中使用的等效源路径为 openclaw claws add docs/reference/templates/roles/<role>。请按照 Claw 预览和同意流程 添加它。使用 agents team create 将这些代理接入一个团队。

agents team create

选项:--preset <name>(默认且唯一内置预设:team)、 --coordinator <id>(默认:coordinator)、--prefix <p>、 --workspace-root <dir>、--non-interactive、--json。

从角色模板创建一个幕僚长(coordinator)以及 researcher、writer 和 reviewer。每个工作区位于 <workspace-root>/<agentId>;默认 根目录是安装的默认工作区目录。--prefix editorial 会为每个 id 添加命名空间,生成 editorial-coordinator、editorial-researcher、 editorial-writer 和 editorial-reviewer。它还会为自定义的 --coordinator id 添加前缀。如果任何生成的 id 已存在,命令会报告冲突 且不添加任何代理。

现有代理会保持原样,包括在已配置安装中隐式的 main。

openclaw agents team create --prefix editorial --workspace-root ~/agents --non-interactive --json
openclaw agent --agent editorial-coordinator --message "Research this topic and draft a brief."

协调者的 subagents.allowAgents 会列出三个专家 id,并且 delegationMode 为 "prefer"。专家会收到 subagents.allowAgents: [] 以及返回结果而不再进一步委派的指令。这不会 更改全局委派默认值或工具策略。参见 团队预设。 委派仍然是配置中的团队接线;一旦独立的 Claw 配置文件支持落地,角色 Claws 将会承载这些 设置。

协调者是显式的聊天目标。如果 agents.defaults.systemAgent.agentId 未设置,团队创建会将其设置为协调者,用于环境系统工作和默认兼容操作。现有 所有者会被保留并报告。频道绑定优先于此默认值。 使用 --json 时,摘要包括 coordinatorId、创建的 agents 及其 路径、ambientOwnerId,以及在保留另一个环境所有者时的 note。

agents bindings

选项:--agent <id>、--json。

agents bind

选项:--agent <id>(默认为当前默认代理)、--bind <channel[:accountId]>(可重复)、--json。

agents unbind

选项:--agent <id>(默认为当前默认代理)、--bind <channel[:accountId]>(可重复)、--all、--json。接受 --all 或一个或多个 --bind 值,二者不可同时使用。

agents set-identity

选项:--agent <id>、--workspace <dir>、--identity-file <path>、--from-identity、--name <name>、--theme <theme>、--emoji <emoji>、--avatar <value>、--json。参见下文 设置身份。

agents delete <id>

选项:--force、--json。

  • 唯一已配置的代理无法删除。
  • 未使用 --force 时,需要交互式确认(在非 TTY 会话中会失败;请使用 --force 重新运行)。
  • 工作区、代理状态和会话转录目录会被移动到回收站,而不是硬删除。如果回收站不可用,代理配置删除仍会成功,并报告需要手动清理的路径;--json 会在 removed 和 failed 数组中公开路径结果。
  • 如果会话存储清理失败,代理会从配置中移除,但其文件和待清理项会被保留。解决报告的存储错误后,重试相同的删除命令;--json 会报告 purgeFailed: true,直到清理成功。
  • 在尚未迁移共享身份验证的安装中,旧版所有者无法删除。运行 openclaw doctor --fix;迁移到共享状态 SQLite 后,main 遵循与其他代理相同的删除规则。
  • 拥有仍被另一个已配置代理使用的会话数据库的代理无法删除,即使保留文件也是如此。请保持该所有者处于已配置状态;将共享历史迁移到另一个所有者需要受支持的迁移,目前不可用。
  • 当 Gateway 可访问时,删除操作会通过 Gateway 路由,以便配置和会话存储清理与运行时流量共享同一个写入器。如果在连接前无法访问已配置的本地 Gateway,CLI 会回退到离线本地路径,并以事务方式删除该代理的计划任务。如果在 CLI 能够测试可达性之前本地 Gateway 凭据不可用,删除仍会回退到本地,但会警告 cron 清理已被跳过,因为实时调度器可能拥有该存储。
  • 删除会移除该代理的绑定,但不会移除它们所路由的频道账户,并且只移除目标为被删除代理的绑定。如果存在指向另一个代理的账户级或频道级绑定,则整个账户的路由会保留;如果存在指向某个对等方的绑定,则它只覆盖来自该对等方的消息,因此该账户上来自其他对等方的消息仍可能没有所有者。如果删除后只剩一个已配置代理,路由会回退到该唯一代理。当没有可用的回退所有者时,未绑定流量会保持未调度状态;已配置的 agents.defaults.systemAgent.agentId、保留的旧版所有者或调用方提供的所有者仍可以捕获它。保留入站消息以便重试的频道(例如 Telegram)可能在重新绑定后投递仍在队列中的消息;参见 路由重试限制。如果也要停用该代理的机器人,请在删除代理之前移除其频道账户,并指定一个存活的代理,以便频道插件发现拥有工作区所有者:openclaw channels remove --agent <surviving-agent-id> --channel <channel> --account <id> --delete。如果没有 --agent,没有回退所有者的多代理配置会以 AgentSelectionRequiredError 失败。如果另一个代理的绑定仍在使用该账户,请跳过账户移除。
  • 如果另一个代理的工作区是相同路径、位于此工作区内或包含此工作区,则工作区会被保留,并且 --json 会报告 workspaceRetained、workspaceRetainedReason 和 workspaceSharedWith。
  • 清理还会保留包含另一个代理已注册数据库的目录,因此删除父目录不会丢弃存活代理的历史。
  • 清理会使用文件系统含义解析符号链接目标,包括 .. 段,因此悬空的工作区链接无法选择无关的相邻目录。

自动本地回退从不适用于远程 Gateway 或 OPENCLAW_GATEWAY_URL 覆盖,包括回环 SSH 隧道。连接或凭据失败会以错误退出,并保持本地配置、工作区和会话状态不变。请恢复 Gateway 连接和凭据,或在 Gateway 主机上运行该命令。

路由绑定

使用路由绑定将入站渠道流量固定到特定智能体。

如果你还希望每个智能体具有不同的可见技能,请在 openclaw.json 中配置 agents.defaults.skills 和 agents.entries.*.skills。参见 技能配置 和 配置参考。

列出绑定:

openclaw agents bindings
openclaw agents bindings --agent work
openclaw agents bindings --json

添加绑定:

openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a

你也可以在创建智能体时添加绑定:

openclaw agents add work --workspace ~/.openclaw/workspace-work --bind telegram:* --bind discord:*

如果省略 accountId(--bind <channel>),OpenClaw 会从插件设置钩子、强制账户绑定或该渠道已配置的账户数量中解析它。

如果在 bind 或 unbind 中省略 --agent,OpenClaw 会针对当前默认智能体。

--bind 格式

格式 含义
--bind <channel>:* 匹配该渠道上的所有账户。
--bind <channel>:<account> 匹配一个账户。
--bind <channel> 仅匹配默认账户,除非 CLI 能够安全地解析插件特定的账户范围。

绑定范围行为

  • 未包含 accountId 的已存储绑定仅匹配字面量 default 账户键。
  • accountId: "*" 是渠道范围的后备项(所有账户),其具体程度低于显式账户绑定。
  • 绑定冲突、重复检测和删除都会比较规范化后的账户 ID,与消息路由相同;账户 ID 的大小写不会创建单独的路由。
  • 如果同一智能体已经存在一个匹配的、未包含 accountId 的渠道绑定,而你之后使用显式或解析得到的 accountId 进行绑定,OpenClaw 会就地升级该现有绑定,而不是添加重复项。

示例:

# match all accounts on the channel
openclaw agents bind --agent work --bind telegram:*

# match a specific account
openclaw agents bind --agent work --bind telegram:ops

# initial channel-only binding
openclaw agents bind --agent work --bind telegram

# later upgrade to account-scoped binding
openclaw agents bind --agent work --bind telegram:alerts

升级后,该绑定的路由范围限定为 telegram:alerts。如果你还需要默认账户路由,请显式添加(例如 --bind telegram:default)。

移除绑定:

openclaw agents unbind --agent work --bind telegram:ops
openclaw agents unbind --agent work --all

身份文件

每个智能体工作区都可以在工作区根目录中包含一个 IDENTITY.md:

  • 示例路径:~/.openclaw/workspace/IDENTITY.md
  • set-identity --from-identity 从工作区根目录读取(或显式指定的 --identity-file)。

头像路径相对于工作区根目录解析,并且无法逃逸出该目录,即使通过符号链接也不行。

设置身份

set-identity 会将字段写入 agents.entries.*.identity:name、theme、emoji、avatar(工作区相对路径、http(s) URL 或 data URI)。

  • --agent 或 --workspace 选择目标智能体。如果 --workspace 匹配到多个智能体,命令会失败并要求你传入 --agent。
  • --workspace 和 --identity-file 仅用于选择智能体或身份文件。它们不会更改 agents.entries.*.workspace。 对于 --json,workspace 是解析后的身份目录:--workspace 定位器、--identity-file 的父目录,或从该处读取身份时的智能体工作区。仅当通过标志提供身份且没有身份目录时,它才为 null。storedWorkspace 报告智能体的持久化工作区。
  • 使用 openclaw config set agents.entries.<id>.workspace <dir> 迁移现有智能体,然后按照 CLI 重启提示操作,并使用 openclaw agents list 确认。
  • 本地工作区相对头像图像文件限制为 2 MB。HTTP(S) URL 和 data: URI 不会按本地文件大小限制进行检查。
  • 当未提供显式身份字段时,命令会从 IDENTITY.md 读取身份数据。

从 IDENTITY.md 加载:

openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity

显式覆盖字段:

openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png

迁移已存储的工作区:

openclaw config set agents.entries.work.workspace ~/.openclaw/workspace-work
openclaw agents list

配置示例:

{
  agents: {
    entries: {
      main: {
        identity: {
          name: "OpenClaw",
          theme: "space lobster",
          emoji: "🦞",
          avatar: "avatars/openclaw.png",
        },
      },
    },
  },
}

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw