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。参见 技能配置 和 配置参考。
列出绑定:
添加绑定:
你也可以在创建智能体时添加绑定:
如果省略 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)。
移除绑定:
身份文件¶
每个智能体工作区都可以在工作区根目录中包含一个 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 --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png
迁移已存储的工作区:
配置示例:
{
agents: {
entries: {
main: {
identity: {
name: "OpenClaw",
theme: "space lobster",
emoji: "🦞",
avatar: "avatars/openclaw.png",
},
},
},
},
}
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw