Migration Overview

Overview

AgentOS provides migration utilities to help you move from other agent frameworks. The migration system scans your existing configuration, converts it to AgentOS format, and generates a detailed migration report.

Supported Frameworks: OpenClaw, LangChain, LangGraph, CrewAI, AutoGen (more coming)

Supported Frameworks

Framework	Status	Completeness	CLI Command
OpenClaw	✅ Full Support	95%	`agentos migrate openclaw`
LangChain	✅ Full Support	85%	`agentos migrate langchain`
LangGraph	🖄️ Partial	70%	`agentos migrate langgraph`
CrewAI	🖄️ Partial	60%	`agentos migrate crewai`
AutoGen	🖄️ Partial	60%	`agentos migrate autogen`
DSPy	⏳ Planned	-	-
LlamaIndex	⏳ Planned	-	-
Semantic Kernel	⏳ Planned	-	-
Haystack	⏳ Planned	-	-

Migration Process

The migration happens in 4 phases:

Scan

Detect installed frameworks and their configuration files:

agentos migrate scan

Output:

{
  "frameworks": [
    {
      "framework": "openclaw",
      "detected": true,
      "configPath": "~/.openclaw/openclaw.json",
      "version": "2.3.1",
      "migratable": true
    },
    {
      "framework": "langchain",
      "detected": true,
      "configPath": "./langchain_config.py",
      "version": "0.1.0",
      "migratable": true
    }
  ],
  "summary": {
    "scanned": 12,
    "found": 2,
    "migratable": 2
  }
}

Dry Run

Preview what will be migrated without making changes:

agentos migrate openclaw --dry-run

Shows what agents, tools, channels, and other resources will be created.

Migrate

Execute the migration:

agentos migrate openclaw

Creates:

agents/*/agent.toml - Converted agent configurations
integrations/*.toml - Tool/integration mappings
config/channels/*.toml - Channel configurations
hands/*/HAND.toml - Cron jobs as autonomous hands
data/sessions/*.json - Session history
data/migrations/openclaw-{timestamp}.json - Migration report

Review & Test

Review migration report and test agents:

# View migration report
agentos migrate report

# Test migrated agent
agentos chat my-migrated-agent

Quick Start

# 1. Scan for OpenClaw
agentos migrate scan

# 2. Preview migration
agentos migrate openclaw --dry-run

# 3. Migrate
agentos migrate openclaw

# 4. Review
agentos migrate report

What Gets Migrated

Agents

Agent configurations are converted to TOML format:

Before (OpenClaw)
After (AgentOS)

openclaw.json

{
  "agents": {
    "my-agent": {
      "model": "gpt-4",
      "system_prompt": "You are a helpful assistant",
      "tools": ["web_search", "file_read"],
      "temperature": 0.7
    }
  }
}

agents/my-agent/agent.toml

[agent]
name = "my-agent"
description = "Migrated from OpenClaw"
module = "builtin:chat"

[agent.model]
provider = "anthropic"
model = "claude-sonnet-4-6"  # Auto-mapped from gpt-4
max_tokens = 4096

[agent.capabilities]
tools = ["tool::web_search", "tool::file_read"]
memory_scopes = ["self.*", "shared.*"]
network_hosts = ["*"]

[agent.resources]
max_tokens_per_hour = 500000

system_prompt = """
You are a helpful assistant
"""

tags = ["migrated", "openclaw"]

Tools & Integrations

Tools are mapped to AgentOS equivalents or converted to integrations:

Source	AgentOS Mapping
`web_search`, `google_search`	`tool::web_search`
`file_read`, `read_file`	`tool::file_read`
`file_write`, `write_file`	`tool::file_write`
`shell`, `terminal`	`tool::shell_exec`
`python_repl`, `code_interpreter`	`tool::shell_exec`
`memory`, `retriever`	`memory::store`, `memory::recall`
Custom tools	`integrations/{name}.toml`

Channels

Communication channels (Slack, Discord, etc.) are converted:

config/channels/slack.toml

[channel]
id = "slack"
type = "slack"
webhook = "https://hooks.slack.com/..."
token = "xoxb-..."

Scheduled Jobs

Cron jobs become autonomous hands:

Before (OpenClaw)
After (AgentOS)

{
  "cron": {
    "daily-report": {
      "schedule": "0 9 * * *",
      "agent": "reporter",
      "task": "Generate daily metrics report"
    }
  }
}

hands/daily-report/HAND.toml

[hand]
id = "daily-report"
name = "daily-report"
description = "Migrated cron from OpenClaw: Generate daily metrics report"
enabled = true
schedule = "0 9 * * *"

[hand.tools]
allowed = ["tool::*"]

[hand.agent]
max_iterations = 40
temperature = 0.3
system_prompt = """Execute the following task: Generate daily metrics report"""

Sessions

Conversation history is preserved:

data/sessions/session-1.json

{
  "id": "session-1",
  "agent": "my-agent",
  "history": [
    { "role": "user", "content": "Hello" },
    { "role": "assistant", "content": "Hi there!" }
  ],
  "created": "2025-03-01T10:00:00Z",
  "migrated": "2025-03-09T15:30:00Z",
  "source": "openclaw"
}

Model Mapping

Models are automatically mapped to AgentOS equivalents:

Source Model	AgentOS Model
`gpt-4`, `gpt-4o`, `gpt-4-turbo`	`claude-sonnet-4-6`
`gpt-4o-mini`, `gpt-3.5-turbo`	`claude-haiku-3.5`
`claude-3-opus`	`claude-opus-4`
`claude-3-sonnet`, `claude-3.5-sonnet`	`claude-sonnet-4-6`
`claude-3-haiku`	`claude-haiku-3.5`
`gemini-pro`, `gemini-1.5-pro`	`claude-sonnet-4-6`
`llama-3`	`llama-3.3-70b`
`mixtral`	`mixtral-8x7b`

You can customize model mappings after migration.

Migration Report

After migration, generate a report:

agentos migrate report

Output (markdown):

# AgentOS Migration Report

Generated: 2025-03-09T15:45:00Z
Total Migration Runs: 1
Total Items Processed: 23

## Summary by Framework

| Framework | Total | Migrated | Skipped | Errors |
|-----------|-------|----------|---------|--------|
| openclaw  | 23    | 20       | 2       | 1      |

## Summary by Type

| Type    | Migrated | Skipped | Errors |
|---------|----------|---------|--------|
| agent   | 5        | 0       | 0      |
| channel | 3        | 1       | 0      |
| tool    | 8        | 1       | 1      |
| cron    | 4        | 0       | 0      |

## Skipped Items

- **channel/webhook-test**: No channel type specified
- **tool/custom-db**: Requires manual migration review

## Errors

- **tool/legacy-api**: Connection refused: ECONNREFUSED

## Successfully Migrated

- **agent/coder**: openclaw:agents.coder -> agents/coder/agent.toml
- **agent/researcher**: openclaw:agents.researcher -> agents/researcher/agent.toml
- **channel/slack**: openclaw:channels.slack -> config/channels/slack.toml
- ...

## Next Steps

1. Review migrated agent system prompts in `agents/*/agent.toml`
2. Configure integration API keys in `integrations/*.toml`
3. Test migrated hands/cron jobs in `hands/*/HAND.toml`
4. Verify session data integrity in `data/sessions/*.json`

Post-Migration Checklist

Review System Prompts

System prompts are migrated as-is but may need refinement:

# Review all migrated agents
for agent in agents/*/agent.toml; do
  echo "Reviewing: $agent"
  cat "$agent" | grep -A 10 "system_prompt"
done

Configure API Keys

Set up API keys for integrations:

# Set LLM provider keys
agentos config set-key anthropic $ANTHROPIC_API_KEY
agentos config set-key openai $OPENAI_API_KEY

# Set integration keys
export TAVILY_API_KEY=...
export BRAVE_API_KEY=...

Test Agents

Test each migrated agent:

# List migrated agents
agentos agent list | grep migrated

# Test each agent
agentos chat coder
agentos message researcher "Search for recent AI papers"

Verify Integrations

Ensure tools work correctly:

# List registered functions
curl http://localhost:3111/functions | jq '.[].id'

# Test specific tool
agentos message coder "Read the file README.md"

Test Scheduled Hands

Verify cron jobs work:

# List hands
agentos hand list

# Run hand manually
agentos hand run daily-report

Clean Up

Remove old framework files (optional):

# Backup first
cp -r ~/.openclaw ~/.openclaw.backup

# Remove old config (optional)
rm -rf ~/.openclaw

Common Issues

Model not supported

If a model isn’t automatically mapped:

# Edit agent.toml
vim agents/my-agent/agent.toml

# Change model
[agent.model]
provider = "anthropic"
model = "claude-sonnet-4-6"  # Use supported model

See supported models for the full list.

Tool not found

If a tool isn’t automatically mapped:

# Check migration report
agentos migrate report | grep -A 5 "Skipped"

# Create custom integration
mkdir integrations/my-tool
vim integrations/my-tool.toml

See creating tools for custom tools.

Config file not found

If migration can’t find your config:

# Specify config path explicitly
agentos migrate openclaw --config-path /path/to/openclaw.json

# Or copy to standard location
mkdir -p ~/.openclaw
cp /path/to/config.json ~/.openclaw/openclaw.json
agentos migrate openclaw

Migration incomplete

If some items weren’t migrated:

# View detailed report
agentos migrate report --format json | jq '.aggregated.byType'

# Re-run migration for specific items
# (Manual migration may be required)

Manual Migration

For unsupported frameworks, migrate manually:

Identify Components: List agents, tools, configurations
Create Agent Configs: Write agent.toml files
Map Tools: Create tool mappings or custom integrations
Convert System Prompts: Adapt prompts to AgentOS format
Test: Verify each agent works correctly

See specific migration guides:

Migration API

You can also migrate programmatically:

import { init } from "iii-sdk";

const { trigger } = init("ws://localhost:49134", { workerName: "migration" });

// Scan for frameworks
const scanResult = await trigger("migrate::scan", {}, 30_000);
console.log(scanResult.frameworks);

// Migrate OpenClaw
const migrateResult = await trigger("migrate::openclaw", {
  dryRun: false,
  configPath: "~/.openclaw/openclaw.json"
}, 120_000);

console.log(migrateResult.summary);

// Generate report
const report = await trigger("migrate::report", {
  format: "markdown"
}, 30_000);

console.log(report.markdown);

Next Steps

LangChain Migration

Detailed guide for migrating from LangChain

OpenClaw Migration

Detailed guide for migrating from OpenClaw

Creating Agents

Customize migrated agents

Testing

Test your migrated setup

Developer Guide

Migration

Migration Overview

Overview

Supported Frameworks

Migration Process

Quick Start

What Gets Migrated

Agents

Tools & Integrations

Channels

Scheduled Jobs

Sessions

Model Mapping

Migration Report

Post-Migration Checklist

Common Issues

Manual Migration

Migration API

Next Steps

LangChain Migration

OpenClaw Migration

Creating Agents

Testing

Build docs developers (and LLMs) love

Developer Guide

Migration

​Overview

​Supported Frameworks

​Migration Process

​Quick Start

​What Gets Migrated

​Agents

​Tools & Integrations

​Channels

​Scheduled Jobs

​Sessions

​Model Mapping

​Migration Report

​Post-Migration Checklist

​Common Issues

​Manual Migration

​Migration API

​Next Steps

LangChain Migration

OpenClaw Migration

Creating Agents

Testing

Build docs developers (and LLMs) love

Overview

Supported Frameworks

Migration Process

Quick Start

What Gets Migrated

Agents

Tools & Integrations

Channels

Scheduled Jobs

Sessions

Model Mapping

Migration Report

Post-Migration Checklist

Common Issues

Manual Migration

Migration API

Next Steps