OpenClaw Documentation

OpenClaw is the foundational open-source framework for building autonomous coding agents. It provides the core architecture and patterns that enable AI systems to write, test, and deploy code with minimal human intervention.

Overview

OpenClaw implements a multi-phase approach to software development:

Planning Phase — Understand requirements, design architecture, create implementation plan
Coding Phase — Generate code following the plan, write tests, iterate on feedback
Review Phase — Analyze code quality, identify issues, suggest improvements
Deployment Phase — Build, test, and deploy changes to target environments

Core Architecture

Agent Loop

┌─────────────────────────────────────────────────────────┐
│                    Agent Loop                           │
│                                                         │
│  ┌─────────┐    ┌──────────┐    ┌─────────┐           │
│  │ Perceive │───▶│  Reason  │───▶│   Act   │           │
│  └─────────┘    └──────────┘    └─────────┘           │
│       ▲                               │               │
│       └───────────────────────────────┘               │
│                  (Feedback)                            │
└─────────────────────────────────────────────────────────┘

Key Components

Component	Purpose
Task Planner	Breaks down requirements into executable steps
Code Generator	Produces syntactically correct, idiomatic code
Test Runner	Executes tests and validates outputs
Error Handler	Parses errors and generates fix strategies
Context Manager	Maintains conversation and file state
Tool Interface	Connects to external tools (git, npm, docker)

Setup and Configuration

Prerequisites

LLM Access: Claude Opus 4.6, GPT-5.4, or equivalent frontier model
Environment: Node.js 20+ or Python 3.12+
Tools: Git, package manager (npm/pip), Docker (optional)

Basic Configuration

# openclaw.yaml
agent:
  model: claude-opus-4-6
  max_iterations: 100
  timeout: 300000  # 5 minutes

context:
  max_tokens: 200000
  include_patterns:
    - "src/**/*.ts"
    - "tests/**/*.ts"
  exclude_patterns:
    - "node_modules/**"
    - "*.lock"

tools:
  - git
  - npm
  - docker

output:
  format: markdown
  include_diffs: true
  verbose: true

Model Selection

OpenClaw works best with frontier reasoning models:

Model	Recommended Use	Notes
Claude Opus 4.6	Complex reasoning, security-critical code	Best for production workloads
Claude Sonnet 4.6	Fast drafts, routine changes	Cost-effective for simple tasks
GPT-5.4	Agentic workflows, computer use	Native tool calling, strong integration
Gemini 3.1 Pro	Complex reasoning, multi-step tasks	Strong at ARC-style problem solving

Best Practices

1. Provide Clear Requirements

# Good: Specific and actionable
Implement a REST API endpoint at POST /users that:
- Accepts JSON body with email, name, password
- Validates email format and password strength
- Hashes password with bcrypt
- Returns 201 with user ID on success
- Returns 400 with validation errors

# Bad: Vague and ambiguous
Add user registration

2. Use Incremental Development

Start with core functionality
Add edge cases incrementally
Run tests after each change
Commit working states frequently

3. Maintain Context Hygiene

Keep related files in context
Remove irrelevant files when switching tasks
Use .gitignore patterns to exclude noise
Compact context periodically for long sessions

4. Review Before Committing

Always review generated diffs
Run full test suite before merging
Check for security issues (hardcoded secrets, etc.)
Verify code style matches project conventions

Integration Patterns

Git Workflow

# Feature branch workflow
openclaw --branch feature/user-auth --task "Implement OAuth2 login"

# Direct commit (use with caution)
openclaw --commit --task "Fix typo in README"

CI/CD Integration

# .github/workflows/openclaw-review.yml
name: OpenClaw Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Run OpenClaw Review
        run: openclaw review --pr ${{ github.event.pull_request.number }}

IDE Integration

OpenClaw integrates with major IDEs:

VS Code: Native extension with inline suggestions
JetBrains: Plugin for IntelliJ/PyCharm/WebStorm
Neovim: Lua plugin via LSP integration

Common Patterns

Test-Driven Development

1. Write failing test for feature
2. Run OpenClaw with task: "Make this test pass"
3. Review generated implementation
4. Refactor if needed
5. Commit

Bug Fixing

1. Provide error message and stack trace
2. Include relevant code snippets
3. Describe expected behavior
4. Run OpenClaw with task: "Fix this bug"
5. Verify fix with reproduction case

Refactoring

1. Identify code to refactor
2. Describe desired end state
3. Specify constraints (maintain API, keep tests passing)
4. Run OpenClaw with task: "Refactor X to Y"
5. Verify behavior unchanged

Troubleshooting

Issue	Cause	Solution
Infinite loop	Unclear requirements	Add specific exit criteria
Wrong file modified	Ambiguous context	Use explicit file paths
Syntax errors	Model limitations	Break into smaller steps
Timeout	Task too complex	Split into subtasks
Hallucinated APIs	Insufficient context	Add relevant documentation

Resources

Documentation: openclaw.dev/docs
GitHub: github.com/openclaw/openclaw
Community: Discord server for discussions
Examples: Sample projects in /examples directory

Last updated: March 2026 | For the latest updates, see the Changelog