MIGRATION.md
This guide covers migrating from OpenClaw (and other frameworks) to OpenFang. The migration engine handles config conversion, agent import, memory transfer, channel re-configuration, and skill scanning.
Run a single command to migrate your entire OpenClaw workspace:
openfang migrate --from openclaw
This auto-detects your OpenClaw workspace at ~/.openclaw/ and imports everything into ~/.openfang/.
# Specify a custom source directory
openfang migrate --from openclaw --source-dir /path/to/openclaw/workspace
# Dry run -- see what would be imported without making changes
openfang migrate --from openclaw --dry-run
After a successful migration, a migration_report.md file is saved to ~/.openfang/ with a summary of everything that was imported, skipped, or needs manual attention.
LangChain and AutoGPT migration support is planned:
openfang migrate --from langchain # Coming soon
openfang migrate --from autogpt # Coming soon
| Item | Source (OpenClaw) | Destination (OpenFang) | Status |
|---|---|---|---|
| Config | ~/.openclaw/config.yaml | ~/.openfang/config.toml | Fully automated |
| Agents | ~/.openclaw/agents/*/agent.yaml | ~/.openfang/agents/*/agent.toml | Fully automated |
| Memory | ~/.openclaw/agents/*/MEMORY.md | ~/.openfang/agents/*/imported_memory.md | Fully automated |
| Channels | ~/.openclaw/messaging/*.yaml | ~/.openfang/channels_import.toml | Automated (manual merge) |
| Skills | ~/.openclaw/skills/ | Scanned and reported | Manual reinstall |
| Sessions | ~/.openclaw/agents/*/sessions/ | Not migrated | Fresh start recommended |
| Workspace files | ~/.openclaw/agents/*/workspace/ | Not migrated | Copy manually if needed |
Channel configurations (Telegram, Discord, Slack) are exported to a channels_import.toml file. You must manually merge the [channels] section into your ~/.openfang/config.toml.
OpenClaw skills (Node.js) are detected and listed in the migration report but not automatically converted. After migration, reinstall skills using:
openfang skill install <skill-name-or-path>
OpenFang automatically detects OpenClaw-format skills and converts them during installation.
If you prefer migrating by hand (or need to handle edge cases), follow these steps:
openfang init
This creates ~/.openfang/ with a default config.toml.
Translate your config.yaml to config.toml:
OpenClaw (~/.openclaw/config.yaml):
provider: anthropic
model: claude-sonnet-4-20250514
api_key_env: ANTHROPIC_API_KEY
temperature: 0.7
memory:
decay_rate: 0.05
OpenFang (~/.openfang/config.toml):
[default_model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
api_key_env = "ANTHROPIC_API_KEY"
[memory]
decay_rate = 0.05
[network]
listen_addr = "127.0.0.1:4200"
Translate each agent.yaml to agent.toml:
OpenClaw (~/.openclaw/agents/coder/agent.yaml):
name: coder
description: A coding assistant
provider: anthropic
model: claude-sonnet-4-20250514
tools:
- read_file
- write_file
- execute_command
tags:
- coding
- dev
OpenFang (~/.openfang/agents/coder/agent.toml):
name = "coder"
version = "0.1.0"
description = "A coding assistant"
author = "openfang"
module = "builtin:chat"
tags = ["coding", "dev"]
[model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
[capabilities]
tools = ["file_read", "file_write", "shell_exec"]
memory_read = ["*"]
memory_write = ["self.*"]
OpenClaw (~/.openclaw/messaging/telegram.yaml):
type: telegram
bot_token_env: TELEGRAM_BOT_TOKEN
default_agent: coder
allowed_users:
- "123456789"
OpenFang (add to ~/.openfang/config.toml):
[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
default_agent = "coder"
allowed_users = ["123456789"]
Copy any MEMORY.md files from OpenClaw agents to OpenFang agent directories:
cp ~/.openclaw/agents/coder/MEMORY.md ~/.openfang/agents/coder/imported_memory.md
The kernel will ingest these on first boot.
| Aspect | OpenClaw | OpenFang |
|---|---|---|
| Format | YAML | TOML |
| Config location | ~/.openclaw/config.yaml | ~/.openfang/config.toml |
| Agent definition | agent.yaml | agent.toml |
| Channel config | Separate files per channel | Unified in config.toml |
| Tool permissions | Implicit (tool list) | Capability-based (tools, memory, network, shell) |
| Model config | Flat (top-level fields) | Nested ([model] section) |
| Agent module | Implicit | Explicit (module = "builtin:chat" / "wasm:..." / "python:...") |
| Scheduling | Not supported | Built-in ([schedule] section: reactive, continuous, periodic, proactive) |
| Resource quotas | Not supported | Built-in ([resources] section: tokens/hour, memory, CPU time) |
| Networking | Not supported | OFP protocol ([network] section) |
Tools were renamed between OpenClaw and OpenFang for consistency. The migration engine handles this automatically.
| OpenClaw Tool | OpenFang Tool | Notes |
|---|---|---|
read_file | file_read | Noun-first naming |
write_file | file_write | |
list_files | file_list | |
execute_command | shell_exec | Capability-gated |
web_search | web_search | Unchanged |
fetch_url | web_fetch | |
browser_navigate | browser_navigate | Unchanged |
memory_search | memory_recall | |
memory_recall | memory_recall | |
memory_save | memory_store | |
memory_store | memory_store | |
sessions_send | agent_send | |
agent_message | agent_send | |
agents_list | agent_list | |
agent_list | agent_list |
These tools have no OpenClaw equivalent:
| Tool | Description |
|---|---|
agent_spawn | Spawn a new agent from within an agent |
agent_kill | Terminate another agent |
agent_find | Search for agents by name, tag, or description |
memory_store | Store key-value data in shared memory |
memory_recall | Recall key-value data from shared memory |
task_post | Post a task to the shared task board |
task_claim | Claim an available task |
task_complete | Mark a task as complete |
task_list | List tasks by status |
event_publish | Publish a custom event to the event bus |
schedule_create | Create a scheduled job |
schedule_list | List scheduled jobs |
schedule_delete | Delete a scheduled job |
image_analyze | Analyze an image |
location_get | Get location information |
OpenClaw's tool profiles map to explicit tool lists:
| OpenClaw Profile | OpenFang Tools |
|---|---|
minimal | file_read, file_list |
coding | file_read, file_write, file_list, shell_exec, web_fetch |
messaging | agent_send, agent_list, memory_store, memory_recall |
research | web_fetch, web_search, file_read, file_write |
full | All 10 core tools |
| OpenClaw Name | OpenFang Name | API Key Env Var |
|---|---|---|
anthropic | anthropic | ANTHROPIC_API_KEY |
claude | anthropic | ANTHROPIC_API_KEY |
openai | openai | OPENAI_API_KEY |
gpt | openai | OPENAI_API_KEY |
groq | groq | GROQ_API_KEY |
ollama | ollama | (none required) |
openrouter | openrouter | OPENROUTER_API_KEY |
deepseek | deepseek | DEEPSEEK_API_KEY |
together | together | TOGETHER_API_KEY |
mistral | mistral | MISTRAL_API_KEY |
fireworks | fireworks | FIREWORKS_API_KEY |
| Provider | Description |
|---|---|
vllm | Self-hosted vLLM inference server |
lmstudio | LM Studio local models |
| Feature | OpenClaw | OpenFang |
|---|---|---|
| Language | Node.js / TypeScript | Rust |
| Config format | YAML | TOML |
| Agent manifests | YAML | TOML |
| Multi-agent | Basic (message passing) | First-class (spawn, kill, find, workflows, triggers) |
| Agent scheduling | Manual | Built-in (reactive, continuous, periodic, proactive) |
| Memory | Markdown files | SQLite + KV store + semantic search + knowledge graph |
| Session management | JSONL files | SQLite with context window tracking |
| LLM providers | ~5 | 11 (Anthropic, OpenAI, Groq, OpenRouter, DeepSeek, Together, Mistral, Fireworks, Ollama, vLLM, LM Studio) |
| Per-agent models | No | Yes (per-agent provider + model override) |
| Security | None | Capability-based (tools, memory, network, shell, agent spawn) |
| Resource quotas | None | Per-agent token/hour limits, memory limits, CPU time limits |
| Workflow engine | None | Built-in (sequential, fan-out, collect, conditional, loop) |
| Event triggers | None | Pattern-matching event triggers with templated prompts |
| WASM sandbox | None | Wasmtime-based sandboxed execution |
| Python runtime | None | Subprocess-based Python agent execution |
| Networking | None | OFP (OpenFang Protocol) peer-to-peer |
| API server | Basic REST | REST + WebSocket + SSE streaming |
| WebChat UI | Separate | Embedded in daemon |
| Channel adapters | Telegram, Discord | Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email |
| Skills/Plugins | npm packages | TOML + Python/WASM/Node.js, FangHub marketplace |
| CLI | Basic | Full CLI with daemon auto-detect, MCP server |
| MCP support | No | Built-in MCP server (stdio) |
| Process supervisor | None | Health monitoring, panic/restart tracking |
| Persistence | File-based | SQLite (agents survive restarts) |
The migration engine looks for ~/.openclaw/ by default. If your OpenClaw workspace is elsewhere:
openfang migrate --from openclaw --source-dir /path/to/your/workspace
Check the converted agent.toml for:
module field (should be "builtin:chat" for standard LLM agents)OpenClaw Node.js skills must be reinstalled:
openfang skill install /path/to/openclaw/skills/my-skill
The installer auto-detects OpenClaw format and converts the skill manifest.
After migration, channels are exported to channels_import.toml. You must merge them into your config.toml manually:
cat ~/.openfang/channels_import.toml
# Copy the [channels.*] sections into ~/.openfang/config.toml
Then restart the daemon:
openfang start