> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Migrate from OpenClaw to Octop

One command reads an OpenClaw setup into a single Octop expert: model providers, persona and memory files, skills, MCP servers, and chat channels. The command only reads the source directory. It does not change or delete those files, and both products can keep running. This applies to Octop 1.0.3b5 and later.

For Hermes Agent, use `hermes` in place of `openclaw`. The differences are in [Migrate from Hermes Agent](/en/guide/migrate/hermes.md). LightClaw uses a backup archive. See [Migrate from LightClaw](/en/guide/migrate/lightclaw.md).

## What moves

| Kind               | Where it is in OpenClaw                                                                                                                        | Where it lands in Octop                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Models             | `models.providers` and `agents.defaults.model` in `openclaw.json`. API keys come from `.env`, the env config, or a legacy `auth-profiles.json` | Model providers. When Octop has no default model yet, the previous primary model becomes the default |
| Persona and memory | Workspace `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`, `TOOLS.md`, `HEARTBEAT.md`, and `memory/*.md`                         | The same file names in the expert workspace                                                          |
| Skills             | `<workspace>/skills` and `~/.openclaw/skills`                                                                                                  | Skills on that expert, enabled after migration                                                       |
| MCP servers        | `mcp.servers`                                                                                                                                  | Your custom connectors. Local commands and Streamable HTTP move over                                 |
| Chat channels      | Telegram, Discord, Feishu, QQ, WeCom, and DingTalk under `channels`                                                                            | Channels on the expert, left disabled                                                                |

Items that stay behind are listed at the end of the result. Handle those yourself:

- Scheduled jobs. Create them under **Automation**, or with `octop cron create`. See [Cron jobs](/en/guide/guides/cron-jobs.md).
- MCP servers that use SSE. Custom MCP accepts a local command or Streamable HTTP. Switch the server to a Streamable HTTP URL, then add it under **Connectors**.
- Model accounts that can only sign in with OAuth, and providers Octop has no matching type for.
- Channels Octop does not support yet, such as Slack, Matrix, and Mattermost.
- Agents outside the default workspace.

## Before you start

Install and initialize Octop on the machine that already has OpenClaw.

The command reads `~/.openclaw` by default. Older installs may live in `~/.clawdbot`, `~/.moltbot`, or `~/.moldbot`. When `OPENCLAW_STATE_DIR` is set, that directory is used. Pass `--from` when the directory is somewhere else.

Create an expert to receive the setup. On **Experts**, click **New expert**, or run:

```bash
octop agent create assistant
```

Copy the **Expert ID** under the name on the expert card. The examples below use `XCZQWG`.


![Expert ID on the expert card](/images/migrate/en/expert-id.png "Expert ID")


> **TIP**
> 
> Leave OpenClaw running while you migrate. Stop the old bot only before you enable a chat channel.
> 


## Preview

Add `--dry-run` first. A preview writes nothing.

```bash
octop migrate openclaw --agent XCZQWG --dry-run
```


> **TIP**
> 
> Run `octop agent use XCZQWG` to make this expert the default. Later commands can omit `--agent`.
> 



![OpenClaw preview](/images/migrate/en/openclaw-dry-run.png "Preview")

| Status                   | Meaning                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------- |
| would migrate / migrated | This item will be written, or is already in Octop                                     |
| skipped                  | Octop already has the same item, so it is left as it is. The **Note** column says why |
| failed                   | This item could not be read or is invalid. The **Note** column says why               |

The dotted lines under the table are items that stay behind.

## Run the migration

When the preview looks right, run the command without `--dry-run`:

```bash
octop migrate openclaw --agent XCZQWG
```


![OpenClaw migration finished](/images/migrate/en/openclaw-done.png "Migration finished")


> **NOTE**
> 
> Restart Octop while it is already running so the new providers and channels load. For a system service, run `octop service restart`. If you started it with `octop run` in a terminal, press Ctrl+C and start it again.
> 


## Check the web UI

- **Models** — Open **Admin → Model Configuration**. The migrated providers and models appear in the pool. When a row says the API key was not found, add the key there.
- **Persona and memory** — On the expert card, click **Edit Workspace**. You should see `AGENTS.md`, `SOUL.md`, `USER.md`, `MEMORY.md`, and the `memory` directory.
- **Skills** — Open **Personalization → Skills**. Migrated skills are installed and enabled.
- **MCP** — Open **Connectors → Enabled connectors**. Each MCP server is a custom connector. Open the card to view or change the command, URL, and headers.


![Migrated model providers](/images/migrate/en/models.png "Model configuration")


![Files in the expert workspace](/images/migrate/en/workspace.png "Workspace")


![Migrated skills](/images/migrate/en/skills.png "Skills")


![Migrated MCP servers](/images/migrate/en/connectors.png "Connectors")

## Turn on chat channels


> **WARNING**
> 
> If OpenClaw and Octop both own the same bot, one message is answered twice, or the two sides compete for it. Migrated channels stay disabled for that reason.
> 



![Migrated channels stay disabled](/images/migrate/en/channels.png "Channels")

Switch over in this order:


### Stop the old bot

Stop the OpenClaw gateway or service, and confirm it no longer replies.

### Check the credentials

Open **Personalization → Channels**. Migrated channels are configured and disabled. Open a channel card, confirm the token, App ID, and other credentials came across, then click **Check Connection**.

### Enable it

Turn on **Enable channel** and save. Send the bot a message to try it.


![Channel settings already include the original credentials](/images/migrate/en/channel-telegram.png "Channel settings")

## Options

| Option        | What it does                                                                                         |
| ------------- | ---------------------------------------------------------------------------------------------------- |
| `--agent`     | Expert to migrate into. When omitted, the expert set with `octop agent use` is used                  |
| `--from`      | Source directory when it is not in the default location                                              |
| `--skip`      | Leave one kind out. Repeat it for `models`, `files`, `skills`, `mcp`, or `channels`                  |
| `--overwrite` | Replace existing workspace files, skills, and the default model                                      |
| `--dry-run`   | Preview only. Write nothing                                                                          |
| `--user`      | When an administrator migrates for someone else, the user who owns the MCP connectors                |
| `--json`      | Place it before `migrate`, for example `octop --json migrate openclaw --agent XCZQWG`, to print JSON |

To move persona files, memory, and skills, and leave models, MCP, and channels where they are:

```bash
octop migrate openclaw --agent XCZQWG --skip models --skip mcp --skip channels
```

## Run it again

You can run the command again. Anything that already exists is skipped, so a second run reports every row as skipped.


![A second run skips every row](/images/migrate/en/openclaw-again.png "Run it again")

Add `--overwrite` when you want the newer OpenClaw copies to replace files in Octop. That flag replaces workspace files, skills, and the default model. Providers, MCP connectors, and channels are never overwritten. Delete those entries in the web UI first, then run the command again.

## Common questions

**The command says no OpenClaw installation was found.** The directory is not in a default location. Pass it with `--from`, for example `--from /srv/openclaw`.

**The command says `--agent is required`.** Name the expert with `--agent`, or run `octop agent use` first. You can also pass the root `--agent` option before `migrate`.

**A row says failed.** Read the **Note** column, fix that item, and run the command again. Items that already migrated are skipped. The command exits with status 1 when any item failed.

**After migration you cannot select a model, or chat returns an error.** Confirm Octop was restarted, then check the provider API key and base URL under **Admin → Model Configuration**.

**You use both OpenClaw and Hermes Agent. Can they land in one expert?** Yes. Run the two commands one after the other. The later command skips persona files, skills, and a default model that already exist. Create a separate expert, and pass a different `--agent`, when you want them kept apart.
