Configuring Your First Agent

+15 Mana ✨
OpenClaw Agent Configuration(DOCUMENTATION)

Introduction

An OpenClaw agent is an AI persona defined by a system prompt, a model, a set of tools, and a workspace. Agents are the fundamental building blocks of your bot infrastructure, each one acting as a specialized assistant tailored to a specific purpose. In this lesson you will learn how to create and configure an agent from scratch.

Key Concepts

  • Agent: An AI persona configured with a system prompt, model, tools, and workspace that defines its behavior and capabilities.
  • System Prompt: The foundational instruction set that shapes how the agent responds, its personality, and its boundaries.
  • Model Selection: Choosing which language model (e.g., Claude, GPT-4) powers the agent's reasoning.
  • Workspace: The isolated environment where an agent operates, containing its configuration files and state.

Real World Context

Consider a Discord server for a software project. You might configure one agent as a code reviewer that uses Claude and has access to your repository tools, while another agent serves as a community FAQ bot using a lighter model. Each agent has its own system prompt tailored to its role, its own model selection based on the complexity of its task, and its own workspace to keep configurations separate.

Deep Dive

Every agent in OpenClaw is identified by a unique agent ID. The agent's configuration lives in a structured directory under ~/.openclaw/agents/<agentId>/. Let us look at a minimal agent configuration:

json
{
  "agentId": "code-reviewer",
  "displayName": "Code Reviewer",
  "systemPrompt": "You are a senior code reviewer. Analyze code for bugs, style issues, and potential improvements. Be constructive and specific.",
  "model": {
    "primary": "anthropic:claude-sonnet-4-20250514"
  },
  "tools": ["read-file", "search-code", "run-lint"],
  "workspace": "code-review-ws"
}

The configuration above defines an agent named code-reviewer. The systemPrompt field is where you instruct the model on how to behave. This is the most important part of your agent configuration because it determines the agent's personality, capabilities, and limitations.

The model field specifies which language model provider and model to use. The format follows the pattern provider:model-name. Here we use Anthropic's Claude as the primary model.

The tools array lists the tools this agent can invoke. Tools extend the agent's capabilities beyond text generation, allowing it to read files, search code, or run linters.

The workspace field isolates this agent's runtime environment. Workspaces prevent agents from interfering with each other's state or configuration. Each workspace maintains its own conversation history and temporary files.

To create this agent using the CLI, you would run:

json
{
  "command": "openclaw agent create",
  "flags": {
    "--id": "code-reviewer",
    "--model": "anthropic:claude-sonnet-4-20250514",
    "--prompt-file": "./prompts/code-reviewer.md",
    "--workspace": "code-review-ws"
  }
}

This command scaffolds the agent directory structure and writes the initial configuration. After creation, you can verify the agent exists by listing all agents and checking its status.

Common Pitfalls

  • Overly broad system prompts: Writing a system prompt that tries to do everything results in an agent that does nothing well. Keep each agent focused on a specific task.
  • Forgetting workspace isolation: If two agents share a workspace unintentionally, their states can collide, causing unpredictable behavior.
  • Hardcoding model versions: Using a specific model version without configuring fallbacks means your agent stops working if that model is deprecated or unavailable.

Best Practices

  • One agent, one responsibility: Design each agent around a single, well-defined task. This makes system prompts clearer and debugging easier.
  • Version your system prompts: Store system prompts in version-controlled files rather than inline strings so you can track changes over time.
  • Always configure a workspace: Even for simple agents, explicitly setting a workspace prevents accidental state sharing.

Summary

  • An agent is defined by an ID, system prompt, model, tools, and workspace.
  • The system prompt is the most critical configuration element, shaping the agent's behavior and boundaries.
  • Models are specified using the provider:model-name format.
  • Workspaces provide isolation between agents, preventing state collisions.
  • The CLI provides commands to scaffold, configure, and manage agents efficiently.
✓ Completed