From Hosted Platform to OpenClaw: Migrate Your First Agent Without Losing Your Mind

You spent three weeks wiring up your first agent on Dify or Botpress. It runs, it works, and then you get the pricing email. Or the platform goes down during a demo. Or you realize you can't inspect what the agent actually does between your prompt and the API call — it's just a series of UI panels you don't fully control.

This is the moment most developers start asking the right question: what do I actually own here?

Moving to a self-hosted, file-based setup feels intimidating if you've never done it. But the migration itself is mostly translation work — your agent's logic is already defined, you just need to express it in files you control. This guide walks you through doing exactly that without losing your existing behavior, your memory, or your sanity.

What You're Actually Migrating

Before touching any files, get clear on what your hosted agent actually consists of. Most platforms bundle a few distinct things together in their UI that you'll need to separate out:

• System prompt / personality — the instructions that shape how the agent responds
• Tool definitions — what the agent can call (web search, code execution, APIs, etc.)
• Memory or context — conversation history, RAG indexes, or persistent state
• Workflow logic — routing rules, multi-step sequences, conditional branches
• Integrations — Slack, email, webhooks, database connections

Hosted platforms hide the seams between these. OpenClaw makes them explicit as separate files. That's not extra complexity — it's the complexity that was always there, now visible.

Export What You Can Before You Migrate

Every platform handles exports differently. Here's what to pull before you touch OpenClaw.

Dify lets you export flows as JSON from the app's settings panel. Get that file — it contains your node graph, variable names, and prompt templates in a readable structure.

CrewAI is already Python-based, so your agent definition lives in code. If you used the CrewAI Studio UI, export your crew as a project directory — it generates crew.py, agents.yaml, and tasks.yaml files you can read directly.

Botpress stores conversation flows as JSON. Export from Studio → Conversations → Export. You'll also want to grab your NLU training data and any stored variables.

For all three: screenshot or copy your system prompts before you close any tabs. Platforms don't always surface these cleanly in exports.

Map Your Logic to OpenClaw Files

OpenClaw's workspace is built around a small set of files. Each one has a specific job:

Start with SOUL.md. Paste your system prompt in and clean up any platform-specific syntax (Dify uses {{variable}} templating; OpenClaw uses a different convention depending on your runtime). Strip out anything that was scaffolding for the platform rather than instructions for the agent.

Next, open your exported tool list and write AGENT.md entries for each one. A minimal tool block looks like this:

## Tool: web_search
- allowed: true
- max_calls_per_run: 5
- scope: external

If you're not sure what a tool did inside the hosted platform, don't re-enable it yet. Start with the smallest set and add back as you test.

Recreate Workflow Logic as Tasks

This is where Dify-to-OpenClaw migrations get interesting. Dify's node graph is visual; OpenClaw's equivalent is TASKS.md — a flat file of task definitions with inputs, outputs, and dependencies.

For a simple linear flow (user sends message → agent searches → agent responds), a single task entry is enough. For branching logic — say, "if the user asks a billing question, route to the billing tool; otherwise, use general search" — you'll write conditional logic inside the task or split into multiple tasks with a routing rule.

Here's a minimal TASKS.md entry:

## Task: answer_user_query
- input: user_message
- steps:
  1. Classify intent
  2. If intent == billing: call billing_tool
  3. Else: call web_search
  4. Synthesize response
- output: agent_response

This is more verbose than a drag-and-drop UI, but it's also inspectable, diffable, and version-controllable. When something breaks at 2am, you'll be glad this is a text file in a git repo.

For reference, the approach here is similar to what's covered in migrating from LangChain to a file-based setup — the translation patterns carry over.

Handle Secrets and Environment Variables

Hosted platforms store your API keys in their secrets manager. When you self-host, that responsibility moves to you.

Create a .env file at your workspace root:

OPENAI_API_KEY=sk-...
SERPAPI_KEY=...
SLACK_WEBHOOK_URL=https://hooks.slack.com/...

Never commit this file. Add .env to .gitignore immediately. If you're running OpenClaw on a VPS, set these as system environment variables or use a secrets manager like Vault or Doppler rather than a file on disk.

For a thorough checklist on this, see OpenClaw's security checklist before trusting an agent in production.

Test End-to-End Before You Cut Over

Don't turn off your hosted agent until the OpenClaw version passes a real test suite. Run both in parallel for a week if your budget allows it.

For testing, build a small input corpus from your actual logs — real messages users sent, real edge cases that tripped up the agent before. Run those through the migrated agent and compare outputs.

Things to verify:

• Does the agent stay in character (does SOUL.md match the old persona)?
• Are tool calls firing when expected?
• Does memory persist correctly across a multi-turn conversation?
• Does the agent refuse things it should refuse?
• Are response times acceptable?

If you're running a devops-style agent, you can automate this. Write a test harness in Python that sends messages and checks outputs against expected patterns. It doesn't need to be fancy — even a JSON file of {"input": ..., "expected_contains": ...} pairs run through a loop gets you coverage.

Version Control Everything From Day One

This is the point of the migration. Your agent's behavior is now in files. Put them in git.

git init my-agent
cd my-agent
git add SOUL.md AGENT.md MEMORY.md TASKS.md
git commit -m "initial migration from Dify"

Now every change to your agent is a diff. You can roll back a bad prompt edit. You can branch to test a new behavior without affecting production. You can open a PR if you have collaborators.

None of this is possible when your agent lives in a hosted UI. This is the actual value of the migration — not cost savings, not features, but auditability. When something goes wrong, you can answer the question "what changed?" in under 30 seconds.

This pairs well with turning your first OpenClaw agent into a reliable daily driver — that post covers the operational side of running file-based agents in production.

Common Sticking Points by Platform

Dify: The hardest part is the node graph. Dify lets you build loops and conditional branches visually that have no direct analog in a flat task file. You'll need to flatten these into sequential steps or implement branching inside a single task's logic. If your flow is genuinely complex, consider whether you need a multi-agent setup instead.

CrewAI: The migration is easier because CrewAI is already code-defined. You're mostly rewriting agents.yaml and tasks.yaml into OpenClaw's format and moving your tool definitions. The conceptual model is similar enough that this often takes an afternoon.

Botpress: The NLU layer is the gap. Botpress has intent classification built in. OpenClaw doesn't — you'd rely on the underlying LLM to classify intent, or you'd call an external classifier. For simple agents, the LLM handles this fine. For high-volume customer service bots with hundreds of intents, this is a real tradeoff to consider before migrating.

What You Won't Lose (And What You Might)

You'll keep: your prompt logic, your tool behavior, your memory design, your integrations (with some rewiring), and your ability to inspect everything.

You might lose: any proprietary platform features — Botpress's built-in analytics dashboard, Dify's one-click deployment pipelines, CrewAI Studio's visual flow editor. These aren't hidden costs; they're real features. If you use them heavily, factor that into your decision.

The tradeoff is explicit: you're trading convenience and managed infrastructure for control, portability, and transparency. That's a reasonable trade for most devops-minded builders — but it's worth being clear-eyed about what you're giving up.

For a broader look at how file-based configs compare to black-box builders, this post on why file-based agent configs win lays out the full case.

Migration is rarely glamorous, but this one has a concrete payoff. Every agent behavior you've defined is now a text file in your repo — readable, auditable, and yours. No pricing changes, no platform outages, no UI panels between you and what your agent actually does.

If you've got a working agent on a hosted platform and you're ready to move it, the files are waiting.