For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/guide/migrate/openclaw.md.
  • English
  • 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. LightClaw uses a backup archive. See Migrate from LightClaw.

    What moves

    KindWhere it is in OpenClawWhere it lands in Octop
    Modelsmodels.providers and agents.defaults.model in openclaw.json. API keys come from .env, the env config, or a legacy auth-profiles.jsonModel providers. When Octop has no default model yet, the previous primary model becomes the default
    Persona and memoryWorkspace AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, TOOLS.md, HEARTBEAT.md, and memory/*.mdThe same file names in the expert workspace
    Skills<workspace>/skills and ~/.openclaw/skillsSkills on that expert, enabled after migration
    MCP serversmcp.serversYour custom connectors. Local commands and Streamable HTTP move over
    Chat channelsTelegram, Discord, Feishu, QQ, WeCom, and DingTalk under channelsChannels 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.
    • 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:

    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

    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.

    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

    Preview
    StatusMeaning
    would migrate / migratedThis item will be written, or is already in Octop
    skippedOctop already has the same item, so it is left as it is. The Note column says why
    failedThis 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:

    octop migrate openclaw --agent XCZQWG

    OpenClaw migration finished

    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

    Model configuration

    Files in the expert workspace

    Workspace

    Migrated skills

    Skills

    Migrated MCP servers

    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

    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

    Channel settings

    Options

    OptionWhat it does
    --agentExpert to migrate into. When omitted, the expert set with octop agent use is used
    --fromSource directory when it is not in the default location
    --skipLeave one kind out. Repeat it for models, files, skills, mcp, or channels
    --overwriteReplace existing workspace files, skills, and the default model
    --dry-runPreview only. Write nothing
    --userWhen an administrator migrates for someone else, the user who owns the MCP connectors
    --jsonPlace 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:

    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

    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.