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> 设置一个。控制 UI 的 设置默认 操作会写入相同的指定。

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

如果某个智能体的数据库属于另一个智能体，它会显示为 降级，并附带拒绝原因和修复指南。当次要智能体被拒绝时，Gateway 可以继续为健康智能体提供服务。遵循 Doctor 的数据库恢复指南，然后在修复文件后重启 Gateway。

提供商行汇总了所显示绑定范围内的本地账户状态。通配符会包含每个本地已知账户一次；消息路由仍应用对等方和账户优先级。省略或留空账户 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。

• 自动化标志 --workspace、--model、--agent-dir、--bind 和 --non-interactive 选择非交互路径。非交互模式要求提供智能体名称，并且除非提供 --role，否则还需要 --workspace。
• 单独使用 --json 会保持引导向导为交互模式。提示和状态写入 stderr，stdout 在设置完成后包含一个 JSON 摘要。
• 非交互 --json 在摘要中报告规范化智能体 ID，不输出额外的 stdout 状态消息。
• main 是普通智能体 ID。在另一个智能体拥有该安装后重新创建它，可能需要先使用 openclaw doctor --fix 修复遗留会话或共享认证所有权。
• 交互模式提供可选的认证复制。当智能体群没有默认智能体时，选择源智能体或 跳过复制认证配置（默认）。选择源后，复制前仍需确认。仅可移植静态凭据（api_key 和静态 token 配置）会被复制，除非某个凭据通过 copyToAgents: false 选择退出；OAuth 刷新令牌配置不会被复制，除非某个提供商通过 copyToAgents: true 选择加入。如果不复制，OAuth 仍可通过共享认证基础保持可用。如果源智能体拥有自己的本地 OAuth 配置，请为新智能体单独登录。

角色模板¶

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

角色会初始化 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。

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 清理被跳过，因为实时调度器可能拥有该存储。
• 如果另一个代理的工作区是相同路径、位于此工作区内，或包含此工作区，则工作区会被保留，并且 --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 格式¶

绑定范围行为¶

• 未包含 accountId 的已存储绑定仅匹配字面量 default 账户键。
• accountId: "*" 是频道范围的后备（所有账户），其具体程度不如显式账户绑定。
• 如果同一代理已经存在一个不含 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: {
        default: true,
        identity: {
          name: "OpenClaw",
          theme: "space lobster",
          emoji: "🦞",
          avatar: "avatars/openclaw.png",
        },
      },
    },
  },
}

相关¶

• CLI 参考
• 多代理路由
• 代理工作区
• Skills 配置：技能可见性配置。