本页内容
本页内容
CLI 命令
智能体
openclaw agents
管理隔离的代理(工作区 + 认证 + 路由)。不带子命令运行 openclaw agents 等同于 openclaw agents list。
示例
命令界面
agents list
选项:--json、--bindings(包括完整的路由规则,而不仅仅是每个代理的 counts/summaries)。
对于显式多智能体列表,默认徽章和 JSON isDefault 字段使用 agents.defaults.systemAgent.agentId。 Doctor 会在重新启动时保留迁移的默认值。如果没有指定,每个条目都会报告 isDefault: false;用 openclaw config set agents.defaults.systemAgent.agentId <id> 设置一项。 Control UI 的 Set Default 操作写入相同的名称。
提供者状态标签包括帐户 ID 旁边的可选帐户显示名称。路由规则继续按通道和账户 ID 来识别账户。
数据库属于另一个代理的代理显示为 degraded,并带有拒绝原因和修复指南。当辅助代理被拒绝时,网关可以继续为健康的代理提供服务。按照Doctor的数据库恢复指导,修复文件后重新启动网关。
提供商行总结了显示的绑定范围的本地帐户状态。通配符包含每个本地已知帐户一次;消息路由仍然应用对等方和帐户优先级。具有省略或空白帐户 ID 的存储绑定引用文字 default 帐户密钥,与通道的命令首选帐户无关。使用 --json --bindings 将提供程序行包含在 JSON 中。
配置中保存的身份字段优先。未配置的字段将回退到代理工作区中的 IDENTITY.md。不支持的头像值和不可读的本地图像也会回退到工作区头像。
agents add [name]
选项:--role <role>、--workspace <dir>、--model <id>、--agent-dir <dir>、--bind <channel[:accountId]>(可重复)、--non-interactive、--json。
基本非交互式创建在运行时使用本地网关。该命令绑定到该网关的状态所有者;不支持的方法、丢失回复或身份验证失败永远不会在本地重试写入。在重试不确定结果之前检查 agents list。
交互式设置、--role、--agent-dir 和 --bind 需要停止本地网关。这些设置流程通过工作区、凭证和配置结算拥有专有的状态所有权。通过其服务所有者停止网关,等待其退出,然后重新运行相同的命令。
- 自动化标志
--workspace、--model、--agent-dir、--bind和--non-interactive选择非交互式路径。非交互模式需要代理名称,除非提供--role,否则需要--workspace。 --json单独保持引导向导的交互性。设置完成后,提示和状态将写入 stderr,并且 stdout 包含一个 JSON 摘要。- 非交互式
--json在摘要中报告规范化的代理 ID,无需额外的标准输出状态消息。 - 如果请求的绑定属于另一个代理,非交互式创建将保留新代理和任何不冲突的绑定,但会以状态 1 退出。摘要会列出冲突;使用
agents bind和agents unbind解决它们,而不是重新创建代理。 main是普通代理 ID。在另一个代理拥有安装后重新创建它可能需要openclaw doctor --fix首先修复旧会话或共享身份验证所有权。- 交互模式提供可选的身份验证复制。当队列没有默认代理时,请选择源代理或 跳过复制身份验证配置文件(默认)。选择来源在复制之前仍需要确认。仅复制可移植静态凭证(
api_key和静态token配置文件),除非凭证通过copyToAgents: false选择退出;除非提供商选择使用copyToAgents: true,否则不会复制 OAuth 刷新令牌配置文件。如果没有副本,OAuth 仍可通过共享身份验证库保持可用。如果源代理有自己的本地 OAuth 配置文件,请单独登录新代理。 - 删除完成的座席 ID 可以使用
agents add重新创建。 Creation 在发布新代理时(包括向导复制或配置 auth 时)声明已完成的删除记录。删除清理仍待处理的 ID 将被拒绝,直到清理完成。
角色模板
--role适用于交互式和非交互式创作,包括--json。捆绑的角色是Claw来源:每个角色目录包含一个带有身份和SOUL.md内容的CLAW.md清单,以及workspace/AGENTS.md中的其操作程序。可用角色:
| 角色 | 标题 | 用途 |
|---|---|---|
coordinator |
参谋长 | 协调专家作为您的单一联系人。 |
researcher |
研究员 | 收集证据并返回引用的研究摘要。 |
writer |
作家 | 将摘要和源材料转变为可用的草稿。 |
reviewer |
审稿人 | 根据要求检查工件并返回可操作的结果。 |
角色种子AGENTS.md、SOUL.md和完整的IDENTITY.md; USER.md仍然使用标准模板。现有工作区文件将被保留。角色的名称、表情符号和主题保存在代理配置中,新的角色工作区会跳过身份仪式:不会创建 BOOTSTRAP.md。捆绑的角色使技能保持不变。还应用角色委派设置。独立的参谋长以标准专家 ID 为目标;使用 team 命令创建并连接所有四个代理。通过 Ask OpenClaw 创建代理时,您可以为其 id 单独指定显示名称,例如 id 为 qa-writer 的“QA Writer”。批准包括两者。明确的显示名称会替换角色的默认名称,同时保留其表情符号、主题和操作说明。未知角色将被拒绝并带有可用的角色名称。引导程序未完成的工作区无法采用角色。 OpenClaw 添加角色文件前检查完成情况;拒绝采用会使工作区文件和代理配置保持不变。完成其引导程序或选择一个新的工作区。
启用 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。
协调者的subagents.allowAgents命名了三个专家ID,delegationMode是"prefer"。专家收到 subagents.allowAgents: [] 和返回结果的指示,无需进一步授权。这不会更改全局委派默认值或工具策略。请参阅 团队预设 。委派仍然是配置中的团队连接;一旦单独的爪形轮廓支持落地,爪子角色将进行这些设置。
协调员是一个明确的聊天目标。如果 agents.defaults.systemAgent.agentId 未设置,团队创建会将其设置为环境系统工作和默认兼容操作的协调器。现有所有者被保留并报告。通道绑定优先于此默认值。对于 --json,摘要包括 coordinatorId、创建的 agents 及其路径、ambientOwnerId 以及保留另一个环境所有者时的 note。
agents bindings
选项:--agent <id>、--json。
agents bind
选项:--agent <id>(默认为当前默认 agent)、--bind <channel[:accountId]>(可重复)、--json。
agents unbind
选项:--agent <id>(默认为当前默认 agent)、--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重新运行)。 - 工作空间、智能体状态和会话记录目录移至垃圾箱,而不是硬删除。如果垃圾箱不可用,代理将从配置中删除,但清理仍处于待处理状态。配置发布成功后,网关删除将返回
UNAVAILABLE,其错误消息中包含路径失败,并且现有的removed和failed详细信息附加到错误响应。离线删除通过--json报告这些路径结果。 - Gateway 删除会持久关闭新会话、轮次和自动化,然后中止并等待活动轮次和后台 memory/session 工作在退出存储之前解决。在共享会话存储中,删除仅取消已删除代理的工作;幸存的特工仍被接纳。已接受的存储工作在退休前解决。一旦开始耗尽,后期会话写入就会被拒绝,而不会中断清理。网关在重新启动后恢复中断的删除,包括旧版本的日志。
- 当删除清理挂起时,即使耗尽或重新启动恢复失败,新会话写入仍会被拒绝。解决报告的故障并重试删除。在清理完成之前,工作区、代理目录和会话存储重定位也会被拒绝;保持存储目标不变的更新仍然可用。
- Gateway 删除使活动运行有 15 秒的时间耗尽。如果取消后运行未停止,则删除会报告其会话 ID 并保留代理的配置和存储。等待指定的运行结束,然后重试删除。
- Deletion 会关闭代理的每个终端,包括分离的终端和在没有聊天会话的情况下打开的终端,并等待其进程退出,然后再退出存储。幸存代理的终端仍然可用。
- 独立的后台命令在其代理被删除时也会被取消和耗尽。空闲的 MCP 运行时在存储之前退出,而活动的 MCP 视图则保持删除挂起状态;关闭这些视图并重试。跟踪的浏览器选项卡使用与会话删除相同的尽力清理。
- 在升级期间,Doctor 会在删除所有权下备份并准备可恢复的待删除旧数据库架构。然后,在应用记录的文件删除选择之前,网关恢复会完成正常的会话清理,包括本机绑定和相关状态。
- 如果会话存储清理失败,将从配置中删除代理,但保留其文件和挂起的清理。解决报告的存储错误,然后重试相同的删除命令。配置发布成功后,网关删除返回
UNAVAILABLE,在failed中命名失败的清理步骤和数据库路径,并将purgeFailed: true附加到其错误响应中;离线--json报告相同的标志,直到清除成功。 - 在尚未迁移共享身份验证的安装上,无法删除旧所有者。运行
openclaw doctor --fix;重定位到共享状态 SQLite 后,main遵循与任何其他代理相同的删除规则。 - 拥有会话数据库但仍被另一个配置的代理使用的代理无法删除,即使保留文件也是如此。保持该所有者的配置;将共享历史记录移动到另一个所有者需要支持的迁移,但目前不可用。
- 当网关可访问时,删除会通过网关进行路由,因此配置和会话存储清理与运行时流量共享相同的编写器。如果在连接之前无法到达配置的本地网关,CLI 将回退到脱机本地路径并以事务方式删除代理的计划作业。如果在 CLI 测试可达性之前本地网关凭据不可用,则删除仍会在本地回退,但会警告跳过 cron 清理,因为实时调度程序可能拥有该存储。
- Deletion 会删除代理的绑定,但不会删除其路由的通道帐户,并且仅删除针对已删除代理的绑定。与另一个代理的幸存帐户范围或通道范围绑定将保留整个帐户路由;幸存的对等点绑定仅涵盖来自该对等点的消息,因此来自帐户上其他对等点的消息仍然可以保持无主状态。如果删除留下了单个配置的代理,则路由将回退到该唯一代理。当没有后备所有者解析时,未调度的未绑定流量不会被分派;配置的
agents.defaults.systemAgent.agentId、保留的旧所有者或调用者提供的所有者仍然可以捕获它。保留入站消息以进行重试的通道(例如 Telegram)可能会在重新绑定后传递仍在排队的消息;请参阅 路由重试限制 。要同时停用代理的机器人,请在删除代理之前删除其通道帐户,命名幸存的代理,以便通道插件发现拥有工作区所有者:openclaw channels remove --agent <surviving-agent-id> --channel <channel> --account <id> --delete。如果没有--agent,没有后备所有者的多代理配置将失败并显示AgentSelectionRequiredError。如果另一个代理的绑定仍然使用该帐户,请跳过帐户删除。 - 如果另一个 agent 的工作区与此工作区是同一路径、位于此工作区内,或包含此工作区,则会保留该工作区,并且
--json会报告workspaceRetained、workspaceRetainedReason和workspaceSharedWith。 - Cleanup 还保留包含另一个代理的注册数据库的目录,因此删除父目录不能丢弃幸存者的历史记录。
- Cleanup 使用其文件系统含义解析符号链接目标,包括
..段,因此悬空工作区链接无法选择不相关的相邻目录。
自动本地回退永远不会应用于远程网关或 OPENCLAW_GATEWAY_URL 覆盖,包括环回 SSH 隧道。连接或凭据失败会出现错误并退出,并保留本地配置、工作区和会话状态。恢复网关连接和凭据,或在网关主机上运行命令。
路由绑定
使用路由绑定将入站频道流量固定到特定的 agent。
如果您还希望每个座席有不同的可见技能,请在 openclaw.json 中配置 agents.defaults.skills 和 agents.entries.*.skills。参见技能配置和配置参考。
列出绑定:
添加绑定:
你也可以在创建 agent 时添加绑定:
如果你省略 accountId(--bind <channel>),OpenClaw 会从插件设置钩子、强制账户绑定或该频道配置的账户数量中解析它。
如果对于 bind 或 unbind 省略 --agent,则 OpenClaw 将以当前默认代理为目标。
--bind 格式
| 格式 | 含义 |
|---|---|
--bind <channel>:* |
匹配该频道上的所有账户。 |
--bind <channel>:<account> |
匹配一个账户。 |
--bind <channel> |
仅匹配默认账户,除非 CLI 能安全解析出特定于插件的账户作用域。 |
绑定作用域行为
- 没有
accountId的 A 存储绑定仅与文字default帐户密钥匹配。 accountId: "*"是频道级回退(所有账户),其具体性低于显式账户绑定。- 绑定冲突、重复检测、移除比较规范化账户ID,就像消息路由一样;帐户 ID 大小写不会创建单独的路由。
- 如果同一个 agent 已经有一个不带
accountId的匹配频道绑定,而你随后使用显式或已解析的accountId进行绑定,OpenClaw 会就地升级现有绑定,而不是添加重复项。
示例:
升级后,该绑定的路由将限定为 telegram:alerts。如果你还想要默认账户路由,请显式添加它(例如 --bind telegram:default)。
移除绑定:
身份文件
每个 agent 工作区都可以在工作区根目录包含一个 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 加载:
显式覆盖字段:
重新定位存储的工作空间:
配置示例: