4 min

Install & Configure

Getting OpenClaw Running

Configuration Is Your First Line of Defense

Before your agent runs a single command, its behavior is shaped by configuration files. A misconfigured agent is more dangerous than no agent at all — it can delete files, leak secrets, or burn through API credits.

OpenClaw's configuration lives in two files: agent-config.yaml for general settings and safety-rules.json for permission boundaries.

Agent Configuration Anatomy

The config/agent-config.yaml file controls the agent's identity and behavior:

Setting	Purpose	Safety Impact
`agent_name`	Human-readable identifier	Appears in audit logs — helps distinguish agents
`model`	Which LLM to use	Affects cost, speed, capability, and data privacy
`max_tokens_per_request`	Token limit per API call	Prevents runaway costs on single requests
`working_directory`	Where the agent operates	Limits the blast radius of mistakes
`dry_run`	Simulate actions without executing	Essential for testing new configurations

Model Selection Tradeoffs

Choosing a model is a multi-dimensional decision:

Factor	Local Model	Cloud API
Privacy	Data never leaves your machine	Data sent to provider
Cost	One-time hardware cost	Per-token charges
Speed	Depends on your GPU	Usually faster
Capability	Limited by model size	Access to frontier models
Offline	Works without internet	Requires connectivity

For personal automation, a local model is often the safest default. For complex reasoning tasks, cloud APIs with strong permission controls are worth the tradeoff.

Working Directory Restrictions

The most important safety decision is where your agent can operate. Think of it as the blast radius:

Too broad (e.g., / or ~) — agent can access anything, including SSH keys, credentials, and system files

Too narrow (e.g., only ~/agent-workspace) — agent is safe but can't automate real tasks

Right-sized — specific directories for specific purposes, with explicit deny rules for sensitive locations

Your safety-rules.json defines this with allow-lists:

allowed_read_dirs — where the agent can read files

allowed_write_dirs — where the agent can create or modify files

blocked_paths — absolute deny-list that overrides allows (e.g., ~/.ssh, ~/.env)

API Key Management

Never hardcode API keys in configuration files. Instead:

Environment variables — export OPENCLAW_API_KEY=sk-... in your shell profile

Key files — .env file in the project root (add to .gitignore immediately)

System keychain — OS-level credential storage for maximum security

If your agent config file ends up in a git repo with an API key, you've just published it to the world.

Dry-Run Mode

Always test new configurations in dry-run mode first. In dry-run:

The agent goes through the full observe-think-act loop

Tool calls are logged but not executed

You can review the audit log to see what *would* have happened

No files are modified, no API calls are made, no money is spent

Think of dry-run as a flight simulator. You practice the full procedure without any risk.

First Run Checklist

Before starting your agent for the first time:

[ ] Review every line of agent-config.yaml

[ ] Verify safety-rules.json — are the allowed directories correct?

[ ] Confirm API keys are in environment variables, not config files

[ ] Set dry_run: true in the config

[ ] Run the agent and review the audit log

[ ] Only after review: set dry_run: false

Key Takeaways

Configuration shapes agent behavior before code ever runs — treat it as a security surface.

Model selection involves tradeoffs between privacy, cost, speed, and capability.

Working directory restrictions limit the blast radius of agent mistakes.

Never hardcode API keys — use environment variables or keychain.

Always test new configurations in dry-run mode before enabling real actions.

This is chapter 2 of Open Source AI Agents (OpenClaw).

Get the full hands-on course — free during early access. Build the complete system. Your projects become your portfolio.

View course details

Ch. 1: What Are AI Agents

Ch. 3: Safety & Guardrails