Category: OpenClaw Tutorials

If you’re running OpenClaw for your daily batch processing or real-time inference tasks, you’ve likely seen those API bills climb. It’s easy to get lost in the abstraction of “tokens” until the monthly statement hits. The problem isn’t just about the raw number of requests; it’s about the efficiency of those requests. Without a clear picture of token usage per model, per task, and over time, you’re effectively flying blind when it comes to cost optimization.

Affiliate Disclosure: As an Amazon Associate, we earn from qualifying purchases. This means we may earn a small commission when you click our links and make a purchase on Amazon. This comes at no extra cost to you and helps support our site.

Understanding OpenClaw’s Token Reporting

OpenClaw, by default, provides some basic token usage information in its verbose logs, but it’s often not granular enough for real cost analysis. When you execute a command like openclaw process --config my_batch_job.yaml, you’ll see summary lines if your log level is set appropriately. For instance, an entry might look like this:

[INFO] [2024-07-23 10:35:12] [claude-haiku-4-5] Request complete. Prompt: 1200 tokens, Completion: 300 tokens. Total: 1500 tokens. Cost: $0.00315.

This is useful for individual requests, but aggregating this across hundreds or thousands of calls, potentially with different models, is manual and error-prone. The real challenge comes when you want to see which specific parts of your prompts are consuming the most tokens, or if a particular task is consistently over-budget. OpenClaw’s built-in metrics, while present, aren’t exposed in a way that allows for easy, real-time aggregation and visualization without some extra plumbing.

Setting Up Custom Token Monitoring

To get a better handle on costs, we need to capture this data systematically. OpenClaw offers a callback mechanism that can be leveraged. We’ll set up a simple local Redis instance to store token data. This isn’t production-grade telemetry, but for a single VPS or a small cluster, it’s incredibly effective and lightweight. First, ensure Redis is installed and running on your system:

sudo apt update
sudo apt install redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server

Next, we need to configure OpenClaw to send token events to a custom script. Create a new Python file, say ~/.openclaw/callbacks/token_logger.py:

import json
import redis
import os
from datetime import datetime

# Initialize Redis client
REDIS_HOST = os.getenv('OPENCLAW_REDIS_HOST', 'localhost')
REDIS_PORT = int(os.getenv('OPENCLAW_REDIS_PORT', 6379))
REDIS_DB = int(os.getenv('OPENCLAW_REDIS_DB', 0))

try:
    r = redis.Redis(host=REDIS_HOST, port=REDIS_PORT, db=REDIS_DB)
    r.ping() # Test connection
except redis.exceptions.ConnectionError as e:
    print(f"ERROR: Could not connect to Redis: {e}")
    r = None # Disable Redis logging if connection fails

def on_request_complete(data):
    """
    Callback function executed by OpenClaw after each model request.
    Data contains: model_name, prompt_tokens, completion_tokens, total_tokens, cost, task_id (if available), timestamp.
    """
    if r is None:
        return

    try:
        log_entry = {
            "timestamp": datetime.now().isoformat(),
            "model_name": data.get("model_name"),
            "prompt_tokens": data.get("prompt_tokens"),
            "completion_tokens": data.get("completion_tokens"),
            "total_tokens": data.get("total_tokens"),
            "cost": data.get("cost"),
            "task_id": data.get("task_id", "unknown"), # Optional, useful for grouping
            "session_id": data.get("session_id", "default") # Optional, useful for multi-session runs
        }
        # Store as a list, or as a sorted set with timestamp for easier range queries
        r.rpush(f"openclaw:tokens:{log_entry['model_name']}", json.dumps(log_entry))
        r.rpush("openclaw:tokens:all", json.dumps(log_entry)) # Global log
        # You could also use an HASH for daily summaries: r.hincrby("openclaw:daily_tokens:2024-07-23", model_name, total_tokens)
    except Exception as e:
        print(f"ERROR in token_logger callback: {e}")

Now, tell OpenClaw to use this callback. Add this to your ~/.openclaw/config.json:

{
  "callbacks": {
    "on_request_complete": [
      "~/.openclaw/callbacks/token_logger.py:on_request_complete"
    ]
  },
  "redis_host": "localhost",
  "redis_port": 6379
}

The redis_host and redis_port entries are custom config parameters for our callback script; OpenClaw itself doesn’t use them directly, but our script can pick them up via os.getenv or by reading the config (though os.getenv is often simpler for callback parameters). Every time OpenClaw completes a request, it will call on_request_complete in our Python script, which will push the token data to Redis.

Non-Obvious Insight: Model Selection and Prompt Engineering

Here’s the kicker: the default models recommended in some OpenClaw tutorials, like gpt-4o or claude-3-opus-20240229, are often overkill for 90% of tasks. We’ve found that for summarization, entity extraction, or even light classification, models like claude-haiku-4-5, gpt-3.5-turbo-0125, or even gemini-pro offer a significantly better cost-to-performance ratio. A typical claude-haiku-4-5 interaction might cost $0.00025 per 1K tokens, whereas claude-3-opus could be $0.015 per 1K, a 60x difference. Monitor your Redis logs. If you consistently see gpt-4o or opus models used for simple tasks, you have a prime optimization target.

Another crucial insight comes from prompt engineering. Often, developers use very chatty or verbose system prompts, or include excessive examples in few-shot prompts. For instance, providing 5 examples when 2 would suffice, or using a paragraph-long system instruction when a concise sentence would achieve the same result. The data in Redis will help you identify which models are used for which tasks. If your summarize_document task is pulling 5000 prompt tokens and only 200 completion tokens, investigate the prompt for unnecessary context or overly verbose instructions. Try to front-load important information and be as direct as possible. Avoid “fluff” in your prompts. Small changes here can have massive ripple effects on cost.

Limitations

This Redis-based monitoring setup is fantastic for understanding your own OpenClaw usage on a single machine or a small, self-managed cluster. It’s designed for quick, actionable insights without the overhead of a full-blown monitoring stack like Prometheus and Grafana. However, it does have limitations:

• No long-term persistence: While Redis is persistent, it’s not designed for petabytes of historical data. For year-long trends or compliance, you’d want to periodically dump this data to a data warehouse or object storage.
• Manual aggregation: You’ll need to write simple Python scripts to query Redis and aggregate the data into daily, weekly, or per-task summaries. It doesn’t give you a fancy dashboard out-of-the-box.
• Scalability: For very high-throughput OpenClaw deployments across many machines, a single Redis instance might become a bottleneck. In such cases, a centralized logging solution like ELK or a dedicated metrics pipeline would be more appropriate.
• Resource usage: While lightweight, Redis does consume some RAM. On a tiny VPS (e.g., a 512MB RAM instance), running OpenClaw, your application, and Redis might push memory limits. This setup is generally fine for VPS instances with at least 2GB RAM. Raspberry Pi 4 (4GB or 8

  Want to see what OpenClaw can really do? Check out this wild project building AI agents with physical bodies →

If you’re running OpenClaw and trying to get your AI agents to interact with files on your server – whether it’s reading logs, writing reports, or processing data – you’ve likely hit a wall. By default, OpenClaw agents are sandboxed for security reasons, meaning they can’t just waltz into your file system. This is a good thing for preventing accidental data loss or malicious actions, but it also makes many practical automation tasks impossible. Here’s how to safely grant your OpenClaw agents file system access on a Linux-based server, focusing on a scenario where you want an agent to read configuration files from a specific directory and write output to another.

Understanding OpenClaw’s Sandbox and Permissions

OpenClaw agents, by design, operate within a constrained environment. When an agent requests a file operation (like read_file or write_file), the OpenClaw runtime intercepts this. It doesn’t directly map to a system call. Instead, it checks against an internal permissions manifest defined in your OpenClaw configuration. If the requested path isn’t explicitly allowed, the operation fails with a permission denied error, which often manifests as an “Agent Error: Permission denied for file operation” in your OpenClaw logs.

The key to enabling file access is to configure these permissions in your .openclaw/config.json file. You define specific directories or files that agents are allowed to interact with, and crucially, what type of interaction (read, write, or both) is permitted. This granular control is essential for maintaining security, as you want to avoid granting blanket access to your entire file system.

Configuring File System Access in OpenClaw

Let’s say you want your OpenClaw agent to read configuration files located in /opt/myapp/configs/ and write its processed output to /var/lib/openclaw_data/output/. You’ll need to modify your .openclaw/config.json. If you don’t have this file, create it in your OpenClaw working directory.

First, ensure the directories actually exist on your file system and have the correct owner and permissions. For instance:

sudo mkdir -p /opt/myapp/configs
sudo mkdir -p /var/lib/openclaw_data/output
sudo chown -R openclaw_user:openclaw_group /var/lib/openclaw_data/output
sudo chmod -R 750 /var/lib/openclaw_data/output

Replace openclaw_user and openclaw_group with the actual user and group under which your OpenClaw process runs. This is critical; if OpenClaw doesn’t have the underlying OS permissions, its internal configuration won’t matter.

Now, add the following to your .openclaw/config.json:

{
  "file_permissions": {
    "/opt/myapp/configs/": {
      "read": true,
      "write": false
    },
    "/var/lib/openclaw_data/output/": {
      "read": false,
      "write": true
    }
  },
  "agent_defaults": {
    "model": "claude-haiku-4-5"
  }
}

In this snippet, we’ve defined two distinct permission sets. The /opt/myapp/configs/ directory is marked as “read”: true, allowing agents to read any file within it. Crucially, “write”: false prevents accidental modification or deletion. Conversely, /var/lib/openclaw_data/output/ is “write”: true, enabling agents to create or modify files there, but “read”: false prevents them from reading potentially sensitive output from previous runs or other agents. This separation of concerns is a powerful security practice.

Non-Obvious Insight: Trailing Slashes and Subdirectories

One common pitfall is the use of trailing slashes. When you define a path like "/opt/myapp/configs/" in file_permissions, OpenClaw interprets this as granting access to all files and subdirectories within that path. If you omit the trailing slash, e.g., "/opt/myapp/configs", OpenClaw treats it as a specific file named “configs”. This distinction is subtle but important. For directory access, always include the trailing slash. If you only want to grant access to a single file, say /etc/myapp.conf, then define it explicitly:

{
  "file_permissions": {
    "/etc/myapp.conf": {
      "read": true,
      "write": false
    }
  }
}

Another insight: while the OpenClaw documentation might suggest using larger, more capable models for agents, for many file processing tasks, especially those involving structured data or simple parsing, a smaller model like claude-haiku-4-5 is often sufficient. It’s significantly cheaper than models like claude-opus-20240229 and can easily handle tasks like extracting data from a log file or formatting text for output. Only upgrade to a larger model if you encounter persistent issues with parsing complex, unstructured data or require advanced reasoning capabilities.

Limitations and Security Considerations

This approach to file system access has limitations. Firstly, it relies on the underlying operating system permissions. If the OpenClaw process itself doesn’t have permission to access a directory, no amount of configuration in .openclaw/config.json will grant it. Always double-check your chown and chmod commands.

Secondly, this method doesn’t provide fine-grained control over individual files within an allowed directory beyond what the OS provides. If an agent has write access to /var/lib/openclaw_data/output/, it can write to any file within that directory, including potentially overwriting files created by other agents or processes. For more complex multi-agent scenarios, consider implementing a custom tool that uses a more robust permission layer or a database for shared data, rather than relying solely on the file system.

Finally, this setup only works if your OpenClaw instance has enough resources to run the agents and process the files. Reading and writing small configuration files is trivial, but if your agents are processing gigabytes of log data, you’ll need a VPS with sufficient RAM and CPU. A basic Hetzner CX11 (2GB RAM) will likely struggle with very large file operations. For anything substantial, aim for at least a CX21 (4GB RAM) or higher.

The next step is to ensure your .openclaw/config.json file contains the necessary file_permissions block and is located in the directory where you typically run your openclaw command, then restart your OpenClaw instance to apply the changes.

Want to see what OpenClaw can really do? Check out this wild project building AI agents with physical bodies →

If you’ve been running OpenClaw for a while, you’re likely using it for the common tasks: automating email responses, summarizing long articles, or perhaps even generating blog drafts. While OpenClaw excels at these, its underlying flexibility with various LLMs and its robust agent framework open up a much wider, often overlooked, range of practical applications. This isn’t about theoretical possibilities; these are concrete use cases I’ve implemented on my own Hetzner VPS instances, often saving significant time or money.

1. Proactive Server Log Analysis and Alerting

Forget sifting through syslog or Nginx access logs manually. OpenClaw can act as an intelligent log parser. Set up a cron job to feed it recent log entries, and instruct it to identify anomalies or potential security threats. Instead of just regex matching, OpenClaw can contextualize errors. For example, a surge of 404s from specific IPs might indicate a bot attack, which a simple `grep` would miss if the pattern varied. I use this to detect early signs of SSH brute-force attempts that fail to trigger Fail2Ban due to distributed attacks or subtle misconfigurations.

# /etc/cron.d/openclaw-log-analyzer
0 3 * * * root /usr/bin/openclaw agent analyze_logs --model claude-haiku-4-5 --input-file /var/log/auth.log --prompt-file /opt/openclaw/prompts/auth_log_analysis.txt > /var/log/openclaw/auth_log_report.txt 2>&1

The prompt file, /opt/openclaw/prompts/auth_log_analysis.txt, instructs OpenClaw to look for patterns indicating failed logins, user enumeration, or suspicious privilege escalations. If it finds anything critical, it can trigger an alert via a custom script. For this to work efficiently, you’ll need to configure OpenClaw’s output to pipe into a notification system, like a simple sendmail command or a script that pushes to a Telegram bot. This only works on systems with sufficient I/O; analyzing multi-gigabyte logs on a low-end VPS will create disk contention.

2. Automated Code Review for Small Pull Requests

Before pushing small utility changes or configuration updates to a development branch, I use OpenClaw for an initial, superficial code review. It’s not a replacement for a human reviewer, but it catches common mistakes like forgotten debug prints, unhandled errors, or inconsistent formatting. I’ve found claude-haiku-4-5 to be surprisingly effective for this, keeping API costs low. It’s particularly useful for shell scripts or Python snippets where a full static analysis tool might be overkill or not configured. I hook this into a pre-commit git hook.

# .git/hooks/pre-commit
#!/bin/sh
# Get staged files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)

for FILE in $STAGED_FILES; do
    if echo "$FILE" | grep -E '\.(py|sh|js|yaml|json)$'; then
        echo "Running OpenClaw review on $FILE..."
        # Pass file content directly to OpenClaw
        git show ":$FILE" | openclaw agent review_code --model claude-haiku-4-5 --input-stdin --prompt-file ~/.openclaw/prompts/code_review.txt
        if [ $? -ne 0 ]; then
            echo "OpenClaw review failed for $FILE. Aborting commit."
            exit 1
        fi
    fi
done

The prompt ~/.openclaw/prompts/code_review.txt usually includes instructions to check for common security vulnerabilities (e.g., SQL injection patterns, shell command injection), best practices (e.g., error handling, logging), and readability. This is best for small, incremental changes; large feature branches will overwhelm the context window and lead to poor results.

3. Intelligent Data Extraction from Unstructured Text

Many business processes involve pulling specific pieces of information from emails, PDFs (after OCR), or web pages. Instead of writing custom parsers for each variant, OpenClaw can extract structured data from unstructured text. Think invoice numbers, dates, client names, or product codes from a sales inquiry email. I use this for automating data entry into a local SQLite database that tracks client interactions. The key is to provide clear examples in your prompt.

# Example input file: invoice.txt (content of a scanned invoice)
# Use a prompt like: "Extract the Invoice Number, Total Amount, and Date from the following text.
# Return as JSON: {"invoice_number": "", "total_amount": "", "date": ""}"
openclaw agent extract_invoice_data --model claude-3-sonnet-20240229 --input-file ~/invoices/invoice_12345.txt --prompt-file ~/.openclaw/prompts/extract_invoice.txt > extracted_data.json

For highly variable input, I’ve found Claude 3 Sonnet or Opus to be significantly more reliable than Haiku, justifying the higher cost. The trick is to be very specific about the desired output format (e.g., JSON schema) in the prompt to ensure consistency. This works well for data with moderate variability; highly ambiguous text will still require human intervention. Ensure your VPS has adequate RAM for larger inputs, as the entire context needs to be loaded.

4. Custom Knowledge Base Querying

OpenClaw isn’t just for external LLM calls. You can augment it with local retrieval-augmented generation (RAG) using your own documents. I’ve built a small knowledge base of personal documentation, common troubleshooting steps for my servers, and even specific code snippets. When I have a problem, instead of searching through dozens of files, I can query OpenClaw, which uses an embedded vector store (like FAISS) to find relevant chunks of text before sending them to an LLM for summarization or direct answers.

# First, index your documents (one-time setup or on change)
openclaw agent index_docs --input-dir ~/knowledge_base/ --output-index ~/.openclaw/kb_index.faiss --chunk-size 1000

# Then, query it
openclaw agent query_kb --query "how to reset nginx cache" --model claude-haiku-4-5 --index ~/.openclaw/kb_index.faiss

This is a game-changer for reducing “context switching” when working on multiple projects. The performance hinges on having a decent vector database setup; for simple use cases, OpenClaw’s built-in FAISS integration is sufficient. For larger datasets, consider integrating with something like Qdrant or ChromaDB, though that requires more setup. The local indexing process can be CPU-intensive depending on the document size, so run it during off-peak hours on your VPS.

5. Dynamic Configuration File Generation

Instead of templating configuration files with Jinja2 or similar tools, OpenClaw can generate complex configurations based on high-level natural language instructions or structured inputs. For example, generating Nginx virtual host configurations, Docker Compose files, or even Kubernetes manifests based on a few parameters like “app name”, “domain”, “port”, and “database type.” This is particularly useful when you have many similar services but each has slight variations. It reduces the chance of manual copy-paste errors.

# Create a new Nginx config for 'myapp' on 'myapp.example.com'
openclaw agent generate_nginx_config --app-name myapp --domain myapp.example.com --port 8000 --proxy-pass http://127.0.0.1:8000 --model claude-sonnet-3-20240229 > /etc/nginx/sites-available/myapp.conf

The agent generate_nginx_config would internally use a prompt containing a base Nginx configuration template and instruct the LLM to fill in the blanks and ensure syntax correctness. I recommend using a more capable model like Sonnet for this, as syntax errors can be costly. The generated config should always be validated (e.g., nginx -t) before deployment. This only really pays off if you’re generating many similar configurations; for one-off tasks, manual templating is faster.

6. Automated Script Refactoring and Simplification

Got a sprawling shell script or a convoluted Python utility that you inherited? OpenClaw can help refactor it. Feed it the script with instructions like “Simplify this script, make it more readable, add comments, and ensure error handling for file operations.” It won’t write perfect code, but it often identifies verbose sections or suggests more idiomatic approaches. I’ve used this to clean up old cron jobs written by others, making them easier to maintain.

Want to see what OpenClaw can really do? Check out this wild project building AI agents with physical bodies →

If you’re running OpenClaw and paying for Claude API calls, you know that those Anthropic credits can evaporate quickly if you’re not careful. The official documentation often steers you towards the most powerful models by default, which, while capable, are also the most expensive. My goal here is to help you get the most out of every dollar, specifically by optimizing your OpenClaw setup for cost-efficiency without a drastic drop in quality for common tasks.

Affiliate Disclosure: As an Amazon Associate, we earn from qualifying purchases. This means we may earn a small commission when you click our links and make a purchase on Amazon. This comes at no extra cost to you and helps support our site.

Understanding Claude’s Pricing Tiers and OpenClaw Defaults

Anthropic’s pricing is primarily based on input and output tokens, and the model you choose significantly impacts the cost per token. For instance, at the time of writing, claude-opus-20240229 is orders of magnitude more expensive than claude-haiku-20240307. OpenClaw, by default, will often try to use the most capable model it’s configured for if you don’t explicitly specify one. This is great for performance but terrible for your wallet if you’re not paying attention.

A common scenario I’ve seen is users kicking off a batch of summarization or categorization tasks with OpenClaw, only to find their credit balance significantly depleted because the jobs were run against opus when haiku would have sufficed. The non-obvious insight here is that while the official Claude docs might highlight opus for its reasoning capabilities, for about 90% of typical OpenClaw tasks – like content moderation, simple data extraction, or basic content generation – claude-haiku-20240307 is not only good enough but also dramatically cheaper, often by a factor of 10x or more per token. Even claude-sonnet-20240229 offers a significant cost saving over opus for moderately complex tasks.

Configuring OpenClaw for Cost-Efficiency

The key to saving money is to explicitly tell OpenClaw which model to use. You can do this in two primary ways: via your global configuration file or on a per-task basis. For most users, a sensible global default combined with task-specific overrides is the most effective strategy.

First, let’s adjust your global default. Locate your OpenClaw configuration directory, typically ~/.openclaw/. Inside, you should find config.json. If it doesn’t exist, create it. Add or modify the anthropic section to specify a default model:

{
  "anthropic": {
    "api_key": "your_anthropic_api_key_here",
    "default_model": "claude-haiku-20240307"
  },
  "logging": {
    "level": "INFO",
    "file": "/var/log/openclaw/openclaw.log"
  }
}

Replace "your_anthropic_api_key_here" with your actual key. By setting "default_model": "claude-haiku-20240307", any OpenClaw command that doesn’t explicitly specify a Claude model will now default to the much cheaper Haiku. This is a game-changer for background tasks or scripts that might omit model selection for brevity.

For tasks that genuinely require a more powerful model, you can override the default directly in your OpenClaw command or task definition. For example, if you’re running a complex analysis script called analyze_data.py, you might invoke it like this:

openclaw run analyze_data.py --model claude-sonnet-20240229 --provider anthropic

This ensures that only the specific, demanding tasks use the more expensive Sonnet model, while everything else benefits from the Haiku default. If you’re using OpenClaw’s internal task scheduling, you’d specify the model within the task’s JSON definition:

{
  "name": "complex_report_generation",
  "provider": "anthropic",
  "model": "claude-opus-20240229",
  "prompt": "Generate a detailed quarterly report based on the following data: {{data}}",
  "input_data": {
    "data": "..."
  }
}

The critical insight here is to be deliberate. Don’t let OpenClaw implicitly choose for you; it will almost always pick a more expensive option if not constrained. Think of it like managing cloud instances – you wouldn’t spin up an r5d.24xlarge for a simple web server, and you shouldn’t use Opus for a Haiku-level task.

Monitoring and Resource Considerations

While model choice primarily impacts API costs, it’s worth noting the resource implications for OpenClaw itself. Running OpenClaw to coordinate many API calls can consume local resources, especially if you’re processing large volumes of data before sending it to Claude. However, the models themselves run on Anthropic’s infrastructure, so local CPU and RAM are less of a concern for the actual inference step.

This strategy of using cheaper models is particularly effective on modest OpenClaw setups, such as a 2GB RAM VPS. A Raspberry Pi might struggle if you’re doing heavy local pre-processing of data (e.g., parsing massive log files) before sending it to Claude, but the API interaction itself is lightweight. The bottleneck will almost certainly be your Anthropic credits, not your local hardware, when optimizing for cost.

OpenClaw’s logging capabilities can also help you monitor your model usage. Ensure your config.json has logging enabled, e.g., "logging": { "level": "INFO", "file": "/var/log/openclaw/openclaw.log" }. Reviewing these logs can confirm which models are being invoked for which tasks, allowing you to identify any unexpected usage patterns that might be draining your credits.

Conclusion

Optimizing your OpenClaw setup for Claude API credits boils down to being intentional about model selection. The default, most powerful models are rarely the most cost-effective for everyday tasks. By leveraging the cheaper models like Haiku and Sonnet for the majority of your workloads, you can drastically reduce your Anthropic bill without a significant compromise in performance for most common OpenClaw use cases.

Your immediate next step should be to edit your ~/.openclaw/config.json file to set "default_model": "claude-haiku-20240307" within the "anthropic" section.

Frequently Asked Questions

Want to see what OpenClaw can really do? Check out this wild project building AI agents with physical bodies →