Implementation:Openclaw Openclaw AgentsAddCommand

AgentsAddCommand

AgentsAddCommand documents the agentsAddCommand function in src/commands/agents.commands.add.ts, which provisions a new isolated agent with its own workspace directory, session store, and configuration entry.

Principle:Openclaw_Openclaw_Agent_Creation

Source Location

File	Lines	Description
src/commands/agents.commands.add.ts	L51-367	agentsAddCommand function
src/commands/agents.commands.add.ts	L32-40	AgentsAddOptions type

Function Signature

export async function agentsAddCommand(
  opts: AgentsAddOptions,
  runtime: RuntimeEnv = defaultRuntime,
  params?: { hasFlags?: boolean },
): Promise<void>

Parameters

Parameter	Type	Default	Description
opts	AgentsAddOptions	(required)	Command options including name, workspace, model, agentDir, bind specs, and output flags.
runtime	RuntimeEnv	defaultRuntime	Runtime environment providing log, error, exit, and config access.
params	{ hasFlags?: boolean }	undefined	When hasFlags is true, forces non-interactive mode.

AgentsAddOptions Type

type AgentsAddOptions = {
  name?: string;
  workspace?: string;
  model?: string;
  agentDir?: string;
  bind?: string[];
  nonInteractive?: boolean;
  json?: boolean;
};

Option	Description
name	Agent name. Normalized to a lowercase agentId. Required in non-interactive mode.
workspace	Workspace directory path. Required in non-interactive mode. Defaults to ~/.openclaw/workspace-<agentId> in interactive mode.
model	Optional model identifier (e.g., "anthropic/claude-sonnet-4-5").
agentDir	Optional agent state directory override. Defaults to ~/.openclaw/agents/<agentId>/agent.
bind	Array of binding specs in channel[:accountId] format (e.g., ["whatsapp:personal", "telegram"]).
nonInteractive	Skip interactive prompts when true.
json	Output result as JSON when true.

Return Value

Returns Promise<void>. Results are communicated via runtime.log (success output) and runtime.error (errors). Exits via runtime.exit(1) on validation failures in non-interactive mode.

Non-Interactive Flow (L74-176)

When flags are present (hasFlags or nonInteractive):

1. Validates that --workspace and --name are provided.
2. Normalizes the name to an agentId via normalizeAgentId().
3. Rejects the reserved id "main".
4. Checks for duplicate agents via findAgentEntryIndex().
5. Resolves workspace and agentDir paths using resolveUserPath() and resolveAgentDir().
6. Applies the agent config entry via applyAgentConfig().
7. Parses binding specs via parseBindingSpecs() and applies them via applyAgentBindings().
8. Writes the config file and ensures the workspace directory exists with bootstrap files.
9. Outputs the result (JSON or human-readable).

Interactive Flow (L178-366)

When no flags are present, launches the Clack wizard:

1. Prompts for agent name and validates.
2. Checks for existing agent and offers update.
3. Prompts for workspace directory (default: ~/.openclaw/workspace-<agentId>).
4. Offers to copy auth profiles from the default agent.
5. Optionally configures model/auth via promptAuthChoiceGrouped().
6. Warns if model configuration looks misconfigured.
7. Sets up channels via setupChannels().
8. Offers to create channel bindings for selected channels.
9. Writes config and ensures workspace with bootstrap files.
10. Outputs summary via prompter.outro().

Key Dependencies

Function	Source	Purpose
applyAgentConfig()	src/commands/agents.config.ts	Adds or updates an agent entry in the config.
applyAgentBindings()	src/commands/agents.bindings.ts	Applies bindings with conflict detection.
parseBindingSpecs()	src/commands/agents.bindings.ts	Parses channel[:accountId] strings into AgentBinding[].
ensureWorkspaceAndSessions()	src/commands/onboard-helpers.ts	Creates workspace directory and seeds bootstrap files.
resolveAgentDir()	src/agents/agent-scope.ts	Resolves the agent state directory path.
resolveAgentWorkspaceDir()	src/agents/agent-scope.ts	Resolves the workspace directory path.
normalizeAgentId()	src/routing/session-key.ts	Normalizes agent name to a valid id.
writeConfigFile()	src/config/config.ts	Persists the updated config to disk.

Error Handling

• Non-interactive mode exits with code 1 for missing required flags, reserved agent ids, or duplicate agents.
• Interactive mode catches WizardCancelledError and exits gracefully with code 0.
• Binding conflicts are reported but do not prevent agent creation -- only the conflicting bindings are skipped.

CLI Usage

# Interactive wizard
openclaw agents add

# Non-interactive with flags
openclaw agents add --name work --workspace ~/.openclaw/workspace-work --model anthropic/claude-sonnet-4-5 --bind whatsapp:biz --bind telegram

# JSON output
openclaw agents add --name work --workspace ~/.openclaw/workspace-work --json