System Acting Weird? Advanced Settings and Debugging Guide

If you made it this far, you already built OpenClaw from zero to working. Nice job.

This final article collects the habits that make your setup more stable and easier to maintain.

What You'll Learn

Find the config file and understand the two editing methods
Recognize the structure of a minimal working config
Store API keys safely with environment variables
Use the most useful debugging command and read common error messages
Pick the right release track

Where Is the Config File?

~/.openclaw/openclaw.json

The format is JSON5, which means comments and trailing commas are allowed. Much friendlier than plain JSON.

You can edit it in two ways:

Use the form mode in Control UI if you want something beginner-friendly
Switch to Raw JSON if you want precision and speed

Both modes edit the same file and save back to the same path.

What Does a Minimal Working Config Look Like?

{
  "agents": {
    "list": [
      { "id": "main", "workspace": "~/.openclaw/workspace-main", "default": true }
    ]
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your bot token"
    }
  },
  "bindings": [
    { "agentId": "main", "match": { "channel": "telegram" } }
  ]
}

Get the simple version working first. Then add more features gradually.

The Right Way to Store API Keys

Do not hard-code API keys into config if you can avoid it.

Environment variables are safer:

# Put this in .env or in your system environment
ANTHROPIC_API_KEY=sk-ant-xxxxx

⚠️ If the Gateway runs as a system service such as systemd, make sure the service loads your .env. Otherwise the assistant may fail because it cannot see the API key, and you may run into errors like "Shell env off".

The Universal Debugging Tool

When something feels wrong, start here:

openclaw logs --follow

Real-time logs answer a surprising number of questions.

Common errors:

Error message	Likely cause
`HTTP 429`	Too many API requests, you hit a rate limit
`unauthorized`	Token problem or `gateway.bind` issue
`content tool_use input field required`	Model compatibility issue, check the docs
Context got truncated	Start a new session or compact context as recommended

Which Release Track Should You Use?

Release track	Best for
Stable	Everyday use, safest default
Beta	Trying new features and accepting some bugs
Dev	Developers who want the newest changes first

💡 Before a major upgrade, back up ~/.openclaw so you always have a rollback path.

Series Complete: What Can You Do Now?

Across these articles, you learned how to:

Understand the core idea behind OpenClaw
Install it and launch it for the first time
Handle dashboard authentication
Connect Telegram and other channels
Make the assistant more capable with Skills
Manage memory and workspaces
Split work across multiple assistants
Deploy the Gateway to a VPS
Automate jobs with Cron
Debug and configure the system like a grown-up

For deeper details, always treat the official docs at docs.openclaw.ai as the source of truth.

Your AI assistant is ready. Go make it work for you.

← Previous: Scheduling and automation | Back to the first article