Implementation:Openclaw Openclaw AgentsListCommand

AgentsListCommand

AgentsListCommand documents the agentsListCommand function in src/commands/agents.commands.list.ts and the buildAgentSummaries function in src/commands/agents.config.ts. These implement the agent listing and routing verification command that displays all configured agents with their bindings, models, workspace paths, and provider status.

Principle:Openclaw_Openclaw_Routing_Verification

Source Locations

File	Lines	Description
src/commands/agents.commands.list.ts	L74-134	agentsListCommand()
src/commands/agents.config.ts	L89-130	buildAgentSummaries()
src/commands/agents.config.ts	L15-29	AgentSummary type
src/commands/agents.commands.list.ts	L22-72	formatSummary() (internal display formatter)

agentsListCommand

Signature

export async function agentsListCommand(
  opts: AgentsListOptions,
  runtime: RuntimeEnv = defaultRuntime,
): Promise<void>

Parameters

Parameter	Type	Default	Description
opts	AgentsListOptions	(required)	Command options.
runtime	RuntimeEnv	defaultRuntime	Runtime environment for logging and config access.

Options Type

type AgentsListOptions = {
  json?: boolean;
  bindings?: boolean;
};

Option	Description
json	Output agent summaries as JSON.
bindings	Include detailed binding rules per agent in the output.

Algorithm

1. Load and validate the config via requireValidConfig(runtime).
2. Build agent summaries via buildAgentSummaries(cfg).
3. Build binding map: Group all bindings by normalized agentId.
4. Attach binding details: When --bindings is set, attach human-readable binding descriptions to each summary via describeBinding().
5. Build provider status index via buildProviderStatusIndex(cfg).
6. Enrich each summary:
   • Compute route summaries from bindings via summarizeBindings().
   • For the default agent with no explicit rules, show "default (no explicit rules)".
   • Attach per-channel provider status lines via listProvidersForAgent().
7. Output: JSON via JSON.stringify or human-readable via formatSummary().

Human-Readable Output Format

The formatSummary() function produces output like:

- home (default) (Home)
  Identity: Home Bot (IDENTITY.md)
  Workspace: ~/.openclaw/workspace-home
  Agent dir: ~/.openclaw/agents/home/agent
  Model: anthropic/claude-sonnet-4-5
  Routing rules: 2
  Routing: whatsapp (personal)
  Providers:
    - whatsapp: connected (personal)
  Routing rules:
    - whatsapp accountId=personal
    - whatsapp accountId=personal peer=group:120363...@g.us

The output includes a footer suggesting --bindings for full rules and openclaw channels status --probe for live health checks.

buildAgentSummaries

Signature

export function buildAgentSummaries(cfg: OpenClawConfig): AgentSummary[]

Parameters

Parameter	Type	Description
cfg	OpenClawConfig	The full gateway configuration.

Return Type

export type AgentSummary = {
  id: string;
  name?: string;
  identityName?: string;
  identityEmoji?: string;
  identitySource?: "identity" | "config";
  workspace: string;
  agentDir: string;
  model?: string;
  bindings: number;
  bindingDetails?: string[];
  routes?: string[];
  providers?: string[];
  isDefault: boolean;
};

Algorithm

1. Resolve the default agent id via resolveDefaultAgentId(cfg).
2. List configured agents. If none are configured, use just the default agent id.
3. Count bindings per agent by iterating cfg.bindings.
4. Deduplicate agent ids while preserving order.
5. For each agent:
   • Resolve workspace path via resolveAgentWorkspaceDir(cfg, id).
   • Load identity from workspace via loadAgentIdentity(workspace) (parses IDENTITY.md).
   • Fall back to config identity from agents.list[].identity.
   • Track identity source as "identity" (file) or "config".
   • Resolve agent name from config.
   • Resolve agent directory via resolveAgentDir(cfg, id).
   • Resolve model via agent-specific config or agents.defaults.model.
   • Count bindings for this agent.
   • Set isDefault when the id matches the default agent.

Supporting Functions

Function	File	Purpose
listAgentEntries(cfg)	src/commands/agents.config.ts	Filters and returns valid agent entries from cfg.agents.list.
findAgentEntryIndex(list, agentId)	src/commands/agents.config.ts	Finds the index of an agent by normalized id.
loadAgentIdentity(workspace)	src/commands/agents.config.ts	Loads and parses IDENTITY.md from a workspace directory.
describeBinding(binding)	src/commands/agents.bindings.ts	Produces a human-readable description of a binding's match criteria.
buildProviderStatusIndex(cfg)	src/commands/agents.providers.ts	Builds a per-channel status index for credential/connectivity state.
summarizeBindings(cfg, bindings)	src/commands/agents.providers.ts	Produces route summary strings from an agent's bindings.
listProvidersForAgent(params)	src/commands/agents.providers.ts	Lists per-channel provider status lines for an agent.

CLI Usage

# List all agents with summary info
openclaw agents list

# Include full binding rules
openclaw agents list --bindings

# Machine-readable JSON output
openclaw agents list --json

# Live channel health check (separate command)
openclaw channels status --probe