CLI — openclaw agents

概述

openclaw agents 管理多 Agent 配置：工作区、认证、路由 binding。

openclaw agents                          # 等同于 agents list
openclaw agents list [--bindings] [--json]
openclaw agents add <name> [options]
openclaw agents bindings [--agent <id>]
openclaw agents bind --agent <id> --bind <channel[:accountId]>
openclaw agents unbind --agent <id> --bind <channel[:accountId]>
openclaw agents set-identity [options]
openclaw agents delete <id> [--force]

子命令速查

`agents list`

列出所有已配置的 Agent。

选项	说明
`--bindings`	包含完整路由规则（而非仅计数/摘要）
`--json`	JSON 输出

`agents add [name]`

添加新的隔离 Agent。传入任意显式选项时自动进入非交互模式。

选项	说明
`--workspace <dir>`	Agent 工作区目录
`--model <id>`	默认模型
`--agent-dir <dir>`	Agent 状态目录（auth、session store）
`--bind <channel[:accountId]>`	同时添加路由 binding（可重复）
`--non-interactive`	非交互模式
`--json`	JSON 输出

注意：

非交互模式需要同时提供 agent name 和 --workspace
main 是保留 id，不能用作新 agent id
交互模式下 auth 种子只复制可移植的静态 profile（api_key、静态 token）；OAuth refresh token 只能通过读穿继承自 main agent store，如需独立 OAuth 需单独登录

`agents bindings`

列出路由 binding。

选项	说明
`--agent <id>`	只看指定 agent 的 binding
`--json`	JSON 输出

`agents bind`

添加路由 binding，将指定渠道流量路由到该 agent。

选项	说明
`--agent <id>`	目标 agent（省略则用当前默认 agent）
`--bind <channel[:accountId]>`	binding 规则（可重复）
`--json`	JSON 输出

`agents unbind`

移除路由 binding。

选项	说明
`--agent <id>`	目标 agent（省略则用当前默认 agent）
`--bind <channel[:accountId]>`	要移除的 binding（可重复）
`--all`	移除该 agent 的所有 binding
`--json`	JSON 输出

--all 和 --bind 不能同时使用。

`agents delete <id>`

删除 agent。

选项	说明
`--force`	跳过交互确认
`--json`	JSON 输出

注意：

main 不能删除
不加 --force 需要交互确认
工作区、agent 状态、session transcript 目录移入回收站，不是硬删除
Gateway 可达时通过 Gateway 执行删除（与运行时流量共享同一写入者）；不可达时回退到本地离线路径
若另一个 agent 的工作区与此工作区路径重叠，工作区会被保留，--json 输出 workspaceRetained、workspaceRetainedReason、workspaceSharedWith

`agents set-identity`

将身份字段写入 agents.list[].identity，支持字段：name、theme、emoji、avatar。

选项	说明
`--agent <id>`	目标 agent
`--workspace <dir>`	通过工作区选择 agent
`--identity-file <path>`	指定 IDENTITY.md 路径
`--from-identity`	从工作区根目录的 IDENTITY.md 读取
`--name <name>`	设置名称
`--theme <theme>`	设置主题
`--emoji <emoji>`	设置 emoji
`--avatar <value>`	工作区相对路径、`http(s)` URL 或 data URI
`--json`	JSON 输出

注意：多个 agent 共享同一工作区时，--workspace 会报错，需改用 --agent。

路由 Binding 详解

Binding 将入站渠道流量固定路由到指定 agent。

Binding 格式

<channel>              # 仅渠道，匹配默认账号
<channel>:<accountId>  # 渠道 + 账号

Binding 作用域规则

Binding 类型	匹配范围
无 `accountId`	仅匹配渠道默认账号
显式 `accountId`	精确匹配该账号
`accountId: "*"`	渠道全账号回退（优先级低于显式账号 binding）

升级行为：若同一 agent 已有无 accountId 的渠道 binding，后续绑定显式 accountId 时，OpenClaw 会原地升级该 binding，而不是新增重复条目。

# 初始：仅渠道级 binding
openclaw agents bind --agent work --bind telegram
 
# 升级为账号级 binding（原地替换）
openclaw agents bind --agent work --bind telegram:ops
# 升级后只匹配 telegram:ops，如需同时匹配默认账号需显式添加
openclaw agents bind --agent work --bind telegram:default

常用示例

# 查看所有 binding
openclaw agents bindings
openclaw agents bindings --agent work
openclaw agents bindings --json
 
# 添加多个 binding
openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a
 
# 移除指定 binding
openclaw agents unbind --agent work --bind telegram:ops
 
# 移除所有 binding
openclaw agents unbind --agent work --all

身份配置示例

从 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.json 配置：

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

Wiki AI

目录