OpenClaw v1 to v2 Migration Guide
Breaking Changes Ahead
OpenClaw v2 introduces significant changes. Use our Config Wizard to generate v2-compatible configs automatically.
What Changed in v2?
1️⃣ Config Format: YAML → JSON
v1 used YAML, v2 requires strict JSON. No more indentation errors!
2️⃣ Plugin System Overhaul
New skill registry. Old plugins need updates. Browse v2-compatible plugins.
3️⃣ Docker Strongly Recommended
v2 has stricter dependency requirements. See our Docker setup guide.
Migration Steps
Step 1: Backup Your v1 Config
cp config.yaml config.yaml.backupStep 2: Convert YAML to JSON
Option A (Recommended): Use our Config Wizard
- Paste your v1 YAML config
- Click "Convert to v2"
- Download the generated
clawhub.json
Option B (Manual): Rewrite from scratch
llm:
provider: openai
api_key: sk-...
model: gpt-4{
"llm": {
"provider": "openai",
"apiKey": "sk-...",
"model": "gpt-4o"
}
}Step 3: Update Plugin References
Browse our Skill Registry to find v2-compatible versions of your plugins.
{
"skills": [
"browser-use", // v2 compatible
"memory-core", // v2 compatible
"crypto-tracker" // v2 compatible
]
}Step 4: Test Your Config
Run our Local Doctor to validate:
npx clawkit-doctor@latestCommon Migration Issues
JSON Parse Error
Likely cause: Trailing commas or unescaped backslashes. Use our Config Wizard to auto-fix.
Plugin Not Found
Your v1 plugin may not have a v2 version yet. Check our Skill Registry for alternatives.
Connection Refused
v2 prefers 127.0.0.1 over localhost. See our troubleshooting guide.
Rollback Plan
If migration fails, revert to v1:
# Restore backup
cp config.yaml.backup config.yaml
# Downgrade to v1
npm install -g [email protected]Why Migrate?
Better Performance
v2 is 30% faster with optimized LLM calls
Improved Security
Sandboxed plugin execution
Active Development
v1 is in maintenance mode only
New Features
Multi-agent orchestration, streaming responses
Need Help?
Last Updated: February 6, 2026 | Migration Time: 15-30 minutes