Haven't installed OpenClaw yet? Click here for one-line install commands
curl -fsSL https://openclaw.ai/install.sh | bash
iwr -useb https://openclaw.ai/install.ps1 | iex
curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Worried about system impact? ClawTank runs OpenClaw in the cloud — no local install needed
Key Findings
  • openclaw agents add is the core command for creating new agents, supporting --model, --identity, --workspace and more — agent registration takes under 30 seconds[1]
  • openclaw agents list with --verbose and --format json flags provides real-time visibility into all registered agents' model configs and status[4]
  • openclaw config set agents.defaults.model.primary sets the global default model; individual agents can override via per-agent config for differentiated model routing[2]
  • OpenClaw's config structure has two layers: project-level openclaw.json and global ~/.config/openclaw/, following a "nearest-first" override mechanism[2]
  • In multi-agent scenarios, model routing lets you assign different models to different agents, balancing cost, latency, and reasoning quality[3]

1. Introduction: Why You Need to Master Agents Commands

OpenClaw is one of the most influential open-source AI agent frameworks today, and its core value lies in enabling developers to rapidly create, configure, and manage multiple intelligent agents through concise CLI commands.[5] MIT Technology Review defines AI agents as "AI systems capable of autonomously executing multi-step tasks"[8] — and OpenClaw's agent management commands are what make this autonomy configurable and reproducible. In practice, however, many developers find themselves confused when first encountering the openclaw agents add command — too many parameter combinations, unclear config hierarchies — wasting valuable development time and potentially causing unexpected agent behavior.

According to the OpenClaw community, over 60% of early-stage issues concentrate on three areas: agents add syntax, agents list output interpretation, and config set model paths.[1] This guide addresses all three comprehensively.

This article follows a "copy-paste ready" principle, breaking down every parameter and option in the OpenClaw agents command family, along with deep dives into the config file structure. After reading, you'll be able to:

  • Master the complete syntax of openclaw agents add and understand every parameter
  • Proficiently use openclaw agents list for agent status monitoring and management
  • Understand how openclaw config set works for model configuration
  • Design multi-agent, multi-model config architectures suited to your needs
  • Quickly troubleshoot common agents command errors

If you've already read our OpenClaw Agent Setup Guide or OpenClaw Config Guide, this article provides a more command-focused operational reference. If you're new to OpenClaw, we recommend starting with the OpenClaw Tutorial for foundational concepts.

2. OpenClaw Config File Structure Overview

Before diving into agents commands, you must first understand OpenClaw's config file architecture — because every agents command you execute ultimately results in changes to the config files.[2]

2.1 Two-Layer Config System

OpenClaw uses a two-layer config system corresponding to "global settings" and "project settings":

Global Config is located under the user's home directory:

~/.config/openclaw/
├── config.json          # Global settings (model API keys, default models, etc.)
├── agents/              # Global agent definitions
│   ├── default/
│   │   └── agent.md     # Default agent identity file
│   ├── code-reviewer/
│   │   └── agent.md
│   └── doc-writer/
│       └── agent.md
├── templates/           # Agent templates
│   ├── minimal.json
│   └── full.json
└── logs/                # Runtime logs
    └── openclaw.log

Project Config is located in the project root:

your-project/
├── openclaw.json        # Project-level config (overrides global)
├── .openclaw/
│   ├── agents/          # Project-specific agents
│   │   └── project-bot/
│   │       └── agent.md
│   └── cache/           # Local cache
└── src/
    └── ...

Config priority follows a "nearest-first" principle: project config > global config > built-in defaults. This means you can define common model keys and default agents at the global level, then override specific settings per project.[2]

2.2 openclaw.json Core Structure

Whether it's the global config.json or the project-level openclaw.json, the core structure contains five top-level sections:

{
"agents": {
  "defaults": {
    "model": {
      "primary": "anthropic:claude-opus-4",
      "fallback": "openai:gpt-4.1"
    },
    "workspace": "./",
    "tools": ["file", "shell", "browser"]
  },
  "registered": {
    "code-reviewer": {
      "identity": ".openclaw/agents/code-reviewer/agent.md",
      "model": {
        "primary": "anthropic:claude-opus-4"
      },
      "workspace": "./src"
    }
  }
},
"models": {
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "baseUrl": "https://api.anthropic.com"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    }
  }
},
"tools": {
  "enabled": ["file", "shell", "browser", "mcp"],
  "permissions": {
    "shell": { "allowlist": ["git", "npm", "node"] }
  }
},
"security": {
  "sandbox": true,
  "networkPolicy": "restricted",
  "maxTokensPerRequest": 128000
},
"logging": {
  "level": "info",
  "output": "~/.config/openclaw/logs/openclaw.log"
}
}

The agents section is the focus of this article — it contains both defaults (global default values) and registered (registered agent list). When you run openclaw agents add, the new agent definition is written into the registered object; when you run openclaw config set agents.defaults.*, you're modifying the defaults section.[4]

2.3 Environment Variable Support

OpenClaw config files support ${ENV_VAR} syntax for referencing environment variables — especially important for sensitive data like API keys:

# Set environment variables (add to .bashrc or .zshrc)
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"

# Reference in openclaw.json
"apiKey": "${ANTHROPIC_API_KEY}"

This ensures sensitive keys are never hard-coded into config files, preventing accidental commits to version control.[2] This is not merely a best practice — The Hacker News reported CVE-2026-25253, a critical OpenClaw vulnerability that exploited exposed authentication tokens[10], underscoring why environment variable isolation is essential for any production deployment.

3. openclaw agents add — Complete Syntax

This is the most critical command in OpenClaw agent management — it creates and registers a new agent. Here's the complete syntax breakdown.[1]

3.1 Basic Syntax

openclaw agents add <agent-name> [options]

Where <agent-name> is the only required parameter — the agent's identifier. Naming rules:

  • Only lowercase letters, digits, and hyphens (a-z, 0-9, -)
  • Must start with a letter, cannot end with a hyphen
  • Length: 2 to 64 characters
  • Must be unique within the same config scope

3.2 Complete Parameter Reference

All options supported by openclaw agents add:

openclaw agents add <agent-name>
--model <model-id>            # Set primary model (overrides global default)
--fallback-model <model-id>   # Set fallback model
--identity <path>             # Specify agent.md identity file path
--workspace <directory>       # Set working directory
--tools <tool1,tool2,...>     # Specify allowed tools (comma-separated)
--template <template-name>    # Create from template
--description <text>          # Agent description
--max-tokens <number>         # Max tokens per request
--temperature <float>         # Model temperature (0.0–2.0)
--global                      # Register as global agent (not project-level)
--no-identity                 # Skip auto-creating agent.md
--dry-run                     # Preview changes without executing
--verbose                     # Show detailed execution
--json                        # Output result in JSON format

3.3 Quickstart: Create Your First Agent in 30 Seconds

The simplest way to create an agent — just provide a name:

# Create an agent named my-assistant (uses global default model)
openclaw agents add my-assistant

After execution, OpenClaw automatically:[1]

  • Creates an agent.md identity file under .openclaw/agents/my-assistant/ (with default system prompt)
  • Registers the agent in the agents.registered section of openclaw.json
  • Inherits model, tools, and workspace settings from agents.defaults

Example output:

✓ Agent "my-assistant" created successfully
  Identity: .openclaw/agents/my-assistant/agent.md
  Model:    anthropic:claude-opus-4 (inherited from defaults)
  Workspace: ./
  Tools:    file, shell, browser

3.4 Advanced Example: Full Parameter Configuration

Here's an agent with comprehensive configuration:

# Create a dedicated code review agent
openclaw agents add code-reviewer \
--model anthropic:claude-opus-4 \
--fallback-model openai:gpt-4.1 \
--identity ./agents/code-reviewer/agent.md \
--workspace ./src \
--tools file,shell,git \
--description "Code review agent focused on security vulnerabilities and performance issues" \
--max-tokens 64000 \
--temperature 0.1

This command configures:

  • Primary model: Anthropic Claude Opus 4; fallback: OpenAI GPT-4.1
  • Custom agent.md identity file (where you define review criteria and response style)
  • Workspace restricted to ./src, preventing access to files outside the project
  • Only three tools allowed: file (read/write), shell (command execution), git (version control)
  • Temperature 0.1 (reduced randomness for more consistent reviews)

3.5 Create Agents from Templates

OpenClaw includes built-in agent templates for quick setup:[4]

# List available templates
openclaw agents templates list

# Create from "code-assistant" template
openclaw agents add my-coder --template code-assistant

# Create from "doc-writer" template
openclaw agents add my-writer --template doc-writer

Templates pre-configure the agent.md system prompt, tool permissions, and recommended model settings, significantly reducing initial setup time.

3.6 Preview with --dry-run

Before creating an agent, use --dry-run to preview changes:

openclaw agents add data-analyst \
--model openai:gpt-4.1 \
--workspace ./data \
--tools file,shell,python \
--dry-run

Output:

[DRY RUN] The following changes would be applied:

1. Create directory: .openclaw/agents/data-analyst/
2. Create file: .openclaw/agents/data-analyst/agent.md
3. Update openclaw.json:
   + agents.registered.data-analyst = {
       "identity": ".openclaw/agents/data-analyst/agent.md",
       "model": { "primary": "openai:gpt-4.1" },
       "workspace": "./data",
       "tools": ["file", "shell", "python"]
     }

No changes were made (dry run).

This is especially useful in team environments — you can paste the --dry-run output into a Pull Request for team review before creating the agent.

3.7 Creating Global Agents

By default, agents add registers agents at the project level. To create a cross-project global agent, add the --global flag:

# Create a globally available general assistant
openclaw agents add general-assistant \
--model anthropic:claude-sonnet-4 \
--tools file,shell,browser \
--global

Global agent definitions are stored in ~/.config/openclaw/agents/ and ~/.config/openclaw/config.json, accessible from any project directory.[2]

4. openclaw agents list — Viewing and Managing Agents

After creating agents, you need a way to view, monitor, and manage them. openclaw agents list is designed for exactly this.[4]

4.1 Basic Usage

# List all agents in the current project
openclaw agents list

Default output is a concise table:

NAME              MODEL                        STATUS
my-assistant      anthropic:claude-opus-4      active
code-reviewer     anthropic:claude-opus-4      active
data-analyst      openai:gpt-4.1              active
doc-writer        anthropic:claude-sonnet-4   inactive

4.2 Verbose Mode (--verbose)

Add --verbose for full config details per agent:

openclaw agents list --verbose

Example output:

Agent: my-assistant
  Identity:  .openclaw/agents/my-assistant/agent.md
  Model:     anthropic:claude-opus-4 (inherited)
  Fallback:  openai:gpt-4.1 (inherited)
  Workspace: ./
  Tools:     file, shell, browser
  Tokens:    128000 (inherited)
  Temp:      0.7 (inherited)
  Status:    active
  Created:   2026-02-14T10:23:45Z

Agent: code-reviewer
  Identity:  ./agents/code-reviewer/agent.md
  Model:     anthropic:claude-opus-4 (explicit)
  Fallback:  openai:gpt-4.1 (explicit)
  Workspace: ./src
  Tools:     file, shell, git
  Tokens:    64000
  Temp:      0.1
  Status:    active
  Created:   2026-02-14T10:30:12Z

---
Total: 4 agents (3 active, 1 inactive)
Config: 2 explicit, 2 inherited

Note the (inherited) vs (explicit) markers — they clearly indicate whether each setting comes from global defaults or the agent's own override. This is invaluable for debugging.

4.3 JSON Output

For scripting or CI/CD pipeline integration, use --format json:

# Output JSON format
openclaw agents list --format json

# Filter with jq for specific agents
openclaw agents list --format json | jq '.agents[] | select(.model.primary == "anthropic:claude-opus-4")'

# List only active agent names
openclaw agents list --format json | jq -r '.agents[] | select(.status == "active") | .name'

4.4 Filtering and Search

agents list supports various filter parameters:

# List agents using a specific model
openclaw agents list --model anthropic:claude-opus-4

# List only active agents
openclaw agents list --status active

# List only global agents
openclaw agents list --global

# Show both global and project agents
openclaw agents list --all

# Sort by creation time
openclaw agents list --sort created

# Sort by name
openclaw agents list --sort name

4.5 Other Management Commands

Beyond list, openclaw agents provides these subcommands for agent management:[1]

# View detailed config for a single agent
openclaw agents show code-reviewer

# Update an existing agent's settings
openclaw agents update code-reviewer --model openai:gpt-4.1

# Temporarily disable an agent
openclaw agents disable doc-writer

# Re-enable an agent
openclaw agents enable doc-writer

# Remove an agent (requires confirmation)
openclaw agents remove data-analyst

# Force remove (skip confirmation)
openclaw agents remove data-analyst --force

# Clone an existing agent's config to create a new one
openclaw agents clone code-reviewer security-reviewer

5. openclaw config set — Model Configuration

openclaw config set is the Swiss Army knife of OpenClaw config management — nearly every setting can be modified through this command. In the context of agent management, the most commonly used paths are model-related.[2]

5.1 Setting the Global Default Model

The most common model config operation — setting the default primary model for all agents:

# Set global default primary model
openclaw config set agents.defaults.model.primary anthropic:claude-opus-4

# Set global default fallback model
openclaw config set agents.defaults.model.fallback openai:gpt-4.1

# Verify the setting
openclaw config get agents.defaults.model

Output:

agents.defaults.model:
  primary: anthropic:claude-opus-4
  fallback: openai:gpt-4.1

When you run openclaw config set agents.defaults.model.primary, the setting is written to the current directory's openclaw.json (project level). To modify the global setting, add --global:[4]

# Modify the global default model
openclaw config set agents.defaults.model.primary anthropic:claude-opus-4 --global

5.2 Setting Per-Agent Models

To override model settings for a specific agent, use the agents.registered.<agent-name> path:

# Set a dedicated model for code-reviewer
openclaw config set agents.registered.code-reviewer.model.primary anthropic:claude-opus-4

# Set a different model for data-analyst
openclaw config set agents.registered.data-analyst.model.primary openai:gpt-4.1

# Set a cost-effective model for doc-writer
openclaw config set agents.registered.doc-writer.model.primary anthropic:claude-haiku-4

5.3 Complete Config Path Reference

All agent model-related config paths:

# ── Global Defaults ──
agents.defaults.model.primary          # Default primary model
agents.defaults.model.fallback         # Default fallback model
agents.defaults.model.temperature      # Default temperature
agents.defaults.model.maxTokens        # Default max tokens
agents.defaults.model.topP             # Default Top-P value
agents.defaults.model.topK             # Default Top-K value
agents.defaults.model.stopSequences    # Default stop sequences

# ── Per-Agent ──
agents.registered.<name>.model.primary
agents.registered.<name>.model.fallback
agents.registered.<name>.model.temperature
agents.registered.<name>.model.maxTokens

# ── Model Providers ──
models.providers.<provider>.apiKey
models.providers.<provider>.baseUrl
models.providers.<provider>.rateLimit
models.providers.<provider>.timeout

5.4 config get & config list

After setting config values, verify they're correct:

# Check a specific config value
openclaw config get agents.defaults.model.primary
# Output: anthropic:claude-opus-4

# View an agent's full config
openclaw config get agents.registered.code-reviewer
# Output:
# agents.registered.code-reviewer:
#   identity: ./agents/code-reviewer/agent.md
#   model:
#     primary: anthropic:claude-opus-4
#     fallback: openai:gpt-4.1
#   workspace: ./src
#   tools: [file, shell, git]

# List all config items (with source markers)
openclaw config list --show-origin

# List only agent-related config
openclaw config list --filter agents

# Output full config as JSON
openclaw config list --format json

5.5 config unset & config reset

To remove an override (letting the agent fall back to global defaults):

# Remove code-reviewer's model override, inherit global default
openclaw config unset agents.registered.code-reviewer.model.primary

# Reset the entire agents.defaults section to factory defaults
openclaw config reset agents.defaults

# Reset all config to factory defaults (requires confirmation)
openclaw config reset --all

6. Real-World Example: Multi-Agent Model Configuration

In real enterprise development environments, you typically need multiple agents working in concert, each with distinct model requirements.[3] Harvard Business Review projects that AI agents will "reshape every industry" by enabling autonomous task execution at scale[9] — but realizing this vision requires carefully designed multi-agent architectures. The following complete example demonstrates how to design a multi-agent model configuration architecture.

6.1 Scenario

Your team needs four agents:

  • architect: System architect for high-level design decisions — needs the strongest reasoning capability
  • coder: Developer for writing and modifying code — needs a balance of speed and quality
  • reviewer: Code reviewer for quality and security checks — needs precision
  • documenter: Documentation writer — can use a more cost-effective model

6.2 Step 1: Set Global Defaults and Model Providers

# Set model provider API keys
openclaw config set models.providers.anthropic.apiKey '${ANTHROPIC_API_KEY}' --global
openclaw config set models.providers.openai.apiKey '${OPENAI_API_KEY}' --global

# Set global default model (applies to agents without specific config)
openclaw config set agents.defaults.model.primary anthropic:claude-sonnet-4 --global
openclaw config set agents.defaults.model.fallback openai:gpt-4.1-mini --global
openclaw config set agents.defaults.model.temperature 0.5 --global
openclaw config set agents.defaults.model.maxTokens 64000 --global

6.3 Step 2: Create Four Agents

# Architect — strongest model, high token limit
openclaw agents add architect \
--model anthropic:claude-opus-4 \
--fallback-model anthropic:claude-sonnet-4 \
--max-tokens 128000 \
--temperature 0.3 \
--tools file,shell,browser,mcp \
--description "System architect: high-level design, tech selection, and architecture decisions"

# Developer — balance speed and quality
openclaw agents add coder \
--model anthropic:claude-sonnet-4 \
--fallback-model openai:gpt-4.1 \
--max-tokens 64000 \
--temperature 0.4 \
--tools file,shell,git,npm \
--workspace ./src \
--description "Developer: code writing, feature implementation, and unit testing"

# Reviewer — low temperature for consistency
openclaw agents add reviewer \
--model anthropic:claude-opus-4 \
--fallback-model anthropic:claude-sonnet-4 \
--max-tokens 64000 \
--temperature 0.1 \
--tools file,git \
--workspace ./src \
--description "Code reviewer: security vulnerabilities, performance bottlenecks, and code style"

# Documenter — cost-effective model
openclaw agents add documenter \
--model anthropic:claude-haiku-4 \
--fallback-model openai:gpt-4.1-mini \
--max-tokens 32000 \
--temperature 0.7 \
--tools file,shell \
--workspace ./docs \
--description "Documentation writer: README, API docs, and technical guides"

6.4 Step 3: Verify Configuration

# List all agents with their config
openclaw agents list --verbose

# Verify a specific agent's model setting
openclaw config get agents.registered.architect.model
# Output:
# agents.registered.architect.model:
#   primary: anthropic:claude-opus-4
#   fallback: anthropic:claude-sonnet-4

# Test agent startup with --dry-run
openclaw agents test architect --dry-run

6.5 Step 4: Resulting openclaw.json

After completing the above steps, your openclaw.json will look like this:

{
"agents": {
  "defaults": {
    "model": {
      "primary": "anthropic:claude-sonnet-4",
      "fallback": "openai:gpt-4.1-mini",
      "temperature": 0.5,
      "maxTokens": 64000
    }
  },
  "registered": {
    "architect": {
      "identity": ".openclaw/agents/architect/agent.md",
      "model": {
        "primary": "anthropic:claude-opus-4",
        "fallback": "anthropic:claude-sonnet-4",
        "temperature": 0.3,
        "maxTokens": 128000
      },
      "tools": ["file", "shell", "browser", "mcp"],
      "description": "System architect"
    },
    "coder": {
      "identity": ".openclaw/agents/coder/agent.md",
      "model": {
        "primary": "anthropic:claude-sonnet-4",
        "fallback": "openai:gpt-4.1",
        "temperature": 0.4,
        "maxTokens": 64000
      },
      "workspace": "./src",
      "tools": ["file", "shell", "git", "npm"],
      "description": "Developer"
    },
    "reviewer": {
      "identity": ".openclaw/agents/reviewer/agent.md",
      "model": {
        "primary": "anthropic:claude-opus-4",
        "fallback": "anthropic:claude-sonnet-4",
        "temperature": 0.1,
        "maxTokens": 64000
      },
      "workspace": "./src",
      "tools": ["file", "git"],
      "description": "Code reviewer"
    },
    "documenter": {
      "identity": ".openclaw/agents/documenter/agent.md",
      "model": {
        "primary": "anthropic:claude-haiku-4",
        "fallback": "openai:gpt-4.1-mini",
        "temperature": 0.7,
        "maxTokens": 32000
      },
      "workspace": "./docs",
      "tools": ["file", "shell"],
      "description": "Documentation writer"
    }
  }
}
}

6.6 Cost Considerations

A major advantage of multi-agent configuration is cost optimization. Harvard Business Review emphasizes that successful AI strategy requires matching model capability to task complexity — not every task needs the most powerful model.[7] Using the four agents above as an example, with this daily usage distribution:

  • architect: ~5 conversations/day (high token consumption, low frequency)
  • coder: ~50 conversations/day (medium token consumption, high frequency)
  • reviewer: ~20 conversations/day (medium token consumption, medium frequency)
  • documenter: ~10 conversations/day (low token consumption, low frequency)

By assigning different-tier models to different agents, you can reduce API costs by an estimated 40–60% compared to uniformly using the top-tier model, without sacrificing reasoning quality for critical tasks (architecture design, security review).[3]

7. Common Troubleshooting

Below are the most frequently encountered errors when using agents commands and their solutions.[1]

7.1 Error: Agent name already exists

$ openclaw agents add coder
Error: Agent "coder" already exists in project config.
Use --force to overwrite, or choose a different name.

Cause: An agent with the same name already exists in the same config scope.

Solutions:

# Option 1: Use a different name
openclaw agents add coder-v2

# Option 2: Remove and recreate
openclaw agents remove coder
openclaw agents add coder --model anthropic:claude-sonnet-4

# Option 3: Update existing agent
openclaw agents update coder --model anthropic:claude-sonnet-4

7.2 Error: Model not found

$ openclaw agents add my-bot --model anthropic:claude-5
Error: Model "anthropic:claude-5" not found.
Available models for provider "anthropic":
  - anthropic:claude-opus-4
  - anthropic:claude-sonnet-4
  - anthropic:claude-haiku-4

Cause: Incorrect model ID or the model hasn't been enabled for that provider.

Solutions:

# View all available models
openclaw models list

# View models for a specific provider
openclaw models list --provider anthropic

# Use the correct model ID
openclaw agents add my-bot --model anthropic:claude-opus-4

7.3 Error: API key not configured

$ openclaw agents add my-bot --model anthropic:claude-opus-4
Error: No API key configured for provider "anthropic".
Set it with: openclaw config set models.providers.anthropic.apiKey <your-key>

Cause: API key not yet configured for the corresponding model provider.

Solutions:

# Option 1: Via config set
openclaw config set models.providers.anthropic.apiKey 'sk-ant-xxxx' --global

# Option 2: Via environment variable (recommended)
export ANTHROPIC_API_KEY="sk-ant-xxxx"
openclaw config set models.providers.anthropic.apiKey '${ANTHROPIC_API_KEY}' --global

7.4 Error: Invalid agent name

$ openclaw agents add My_Agent
Error: Invalid agent name "My_Agent".
Agent names must match pattern: ^[a-z][a-z0-9-]{1,63}(?<!-)$
  - Only lowercase letters, digits, and hyphens
  - Must start with a letter
  - Must not end with a hyphen
  - Length: 2-64 characters

Solution: Use a name that follows the naming rules, e.g., my-agent.

7.5 Error: Workspace directory not found

$ openclaw agents add my-bot --workspace ./nonexistent
Error: Workspace directory "./nonexistent" does not exist.
Create it first, or use --create-workspace to auto-create.

Solutions:

# Option 1: Create the directory first
mkdir -p ./nonexistent
openclaw agents add my-bot --workspace ./nonexistent

# Option 2: Use --create-workspace flag
openclaw agents add my-bot --workspace ./nonexistent --create-workspace

7.6 Config Path Typos

This is the most insidious issue — config set accepts arbitrary paths without errors, but typos won't take effect:

# Wrong: path has a typo (defautls instead of defaults)
openclaw config set agents.defautls.model.primary anthropic:claude-opus-4
# No error, but the setting won't be read by any agent!

# Correct: verify after setting
openclaw config set agents.defaults.model.primary anthropic:claude-opus-4
openclaw config get agents.defaults.model.primary
# Output: anthropic:claude-opus-4

Best practice: Always config get immediately after config set to verify. You can also use openclaw config validate to check the entire config file:[2]

# Validate config structure and values
openclaw config validate

# Example output
✓ Config structure: valid
✓ Model references: all resolved
✓ Agent identities: all files exist
⚠ Warning: agents.defautls.model.primary — unrecognized path (did you mean "agents.defaults"?)
✓ API keys: all configured

7.7 Debugging Inheritance Issues

When an agent doesn't behave as expected, it's usually a config inheritance chain issue. Use these commands to trace the full resolution process:

# Show the agent's fully resolved config (with inheritance sources)
openclaw agents show code-reviewer --resolve

# Example output
Agent: code-reviewer (resolved config)
  model.primary:     anthropic:claude-opus-4    [source: project/agents.registered.code-reviewer]
  model.fallback:    openai:gpt-4.1            [source: project/agents.registered.code-reviewer]
  model.temperature: 0.1                        [source: project/agents.registered.code-reviewer]
  model.maxTokens:   64000                      [source: project/agents.registered.code-reviewer]
  workspace:         ./src                      [source: project/agents.registered.code-reviewer]
  tools:             file, shell, git           [source: project/agents.registered.code-reviewer]

# Compare inheritance vs overrides
openclaw agents diff code-reviewer --vs defaults

8. Conclusion

OpenClaw's agents command family — from agents add for creation, agents list for monitoring, to config set for model configuration — forms the core of the agent management workflow.[3] Mastering these commands not only boosts daily development efficiency but also enables you to design config architectures that balance performance, cost, and security in complex multi-agent, multi-model scenarios.

Key takeaways:

  • Config structure: Understanding the two-layer system (global vs. project) and the nearest-first principle is the foundation for everything
  • agents add: Master the full parameter syntax; use --template for rapid setup and --dry-run to preview changes
  • agents list: Combine --verbose and --format json for real-time agent visibility and programmatic processing
  • config set: Know the model config paths (especially agents.defaults.model.primary) and always verify after setting
  • Multi-agent architecture: Assign the right model tier to each agent's role to significantly reduce API costs without sacrificing critical quality — a principle Harvard Business Review identifies as essential to sustainable AI strategy[7]

If you're evaluating how to adopt AI agents in an enterprise environment or want to optimize your existing multi-agent configuration, contact the Meta Intelligence team — we have extensive experience in enterprise OpenClaw deployments and can help design the agent architecture that best fits your organization's needs.

Further reading: OpenClaw Agent Setup Guide | OpenClaw Config Guide | OpenClaw Command Reference