For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/migrate/openclaw.md.
  • 简体中文
  • 从 OpenClaw 迁移到 Octop

    一条命令把 OpenClaw 的模型、人设与记忆、技能、MCP 服务器和聊天通道读进 Octop 的一位专家。命令只读取原来的目录,不会修改或删除其中的文件,迁移后两边可以并存。适用于 Octop 1.0.3b5 及以上。

    Hermes Agent 把命令里的 openclaw 换成 hermes。差异见从 Hermes Agent 迁移。LightClaw 走备份恢复,见从 LightClaw 迁移。

    会迁移什么

    类别OpenClaw 里的位置迁到 Octop 之后
    模型openclaw.json 的 models.providers 和 agents.defaults.model。API Key 取自 .env、env 配置或旧版 auth-profiles.json模型供应商。Octop 还没有默认模型时,原来的主模型成为默认模型
    人设与记忆工作区的 AGENTS.md、SOUL.md、IDENTITY.md、USER.md、MEMORY.md、TOOLS.md、HEARTBEAT.md、memory/*.md专家工作区里的同名文件
    技能<工作区>/skills、~/.openclaw/skills这位专家的技能,迁移后即启用
    MCP 服务器mcp.servers你的自定义连接器。本地命令和 Streamable HTTP 可以迁入
    聊天通道channels 下的 Telegram、Discord、飞书、QQ、企业微信、钉钉专家的通道,默认不启用

    不会迁入的内容出现在结果末尾,需要你手动处理:

    • 定时任务。在 自动化 里新建,或用 octop cron create。见定时任务。
    • 使用 SSE 传输的 MCP 服务器。自定义 MCP 只支持本地命令和 Streamable HTTP。换成 Streamable HTTP 地址后,在 连接器 里手动添加。
    • 只能用 OAuth 登录的模型账号,以及 Octop 里没有对应类型的模型供应商。
    • Octop 暂不支持的通道,例如 Slack、Matrix、Mattermost。
    • 默认工作区以外的其他 Agent。

    开始之前

    在装有 OpenClaw 的那台机器上安装并初始化 Octop。

    默认读取 ~/.openclaw。更早的安装也可能在 ~/.clawdbot、~/.moltbot 或 ~/.moldbot。设置了 OPENCLAW_STATE_DIR 时读那个目录。目录不在这些位置时,给命令加上 --from。

    准备一位接收内容的专家。在 专家 页点 新建专家,或运行:

    octop agent create assistant

    记下 专家 ID,它显示在专家卡片的名字下面。下文示例用 XCZQWG。

    专家卡片上的专家 ID

    专家 ID
    提示

    迁移时不必停掉 OpenClaw。只有在启用聊天通道之前,才需要先停掉原来的机器人。

    预演

    先加 --dry-run。预演不写入任何内容。

    octop migrate openclaw --agent XCZQWG --dry-run
    提示

    先运行 octop agent use XCZQWG 把这位专家设为默认,之后的命令就可以不带 --agent。

    OpenClaw 预演结果

    预演结果
    状态含义
    将迁移 / 已迁移这一项会写入,或已经写入 Octop
    已跳过Octop 里已经有同名内容,不会覆盖。说明列写了原因
    失败这一项读不出来或不合法。说明列写了原因

    表格下方带圆点的几行,是不会迁移、需要手动处理的内容。

    执行迁移

    确认预演结果后,去掉 --dry-run 再运行一次:

    octop migrate openclaw --agent XCZQWG

    OpenClaw 迁移完成

    迁移完成
    说明

    Octop 正在运行时需要重启,新的模型供应商和通道才会加载。用系统服务运行时执行 octop service restart。在终端里用 octop run 运行的,按 Ctrl+C 停止后重新运行。

    在页面上核对

    • 模型 — 打开 管理 → 模型配置。可用模型池里能看到迁过来的供应商和模型。某一项的说明是「未找到 API Key」时,在这里补上密钥。
    • 人设与记忆 — 在专家卡片上点 编辑工作区。可以看到 AGENTS.md、SOUL.md、USER.md、MEMORY.md 和 memory 目录。
    • 技能 — 打开 个性化 → 技能。迁过来的技能已经安装并启用。
    • MCP — 打开 连接器 → 已启用连接器。每个 MCP 服务器是一个自定义连接器。点卡片可以查看或修改命令、地址和请求头。

    迁移过来的模型供应商

    模型配置

    专家工作区里的文件

    工作区

    迁移过来的技能

    技能

    迁移过来的 MCP 服务器

    连接器

    启用聊天通道

    注意

    同一个机器人如果同时被 OpenClaw 和 Octop 接管,一条消息会被回复两次,或者两边互相抢消息。所以迁过来的通道默认不启用。

    迁移过来的通道默认不启用

    通道

    按这个顺序切换:

    停掉原来的机器人

    停掉 OpenClaw 的网关或服务,确认它已经不再回复。

    核对凭证

    打开 个性化 → 通道。迁过来的通道显示为已配置、未启用。点通道卡片,确认 Token、App ID 等凭证已经带过来,点 检测连接。

    启用

    打开 启用频道 并保存。给机器人发一条消息试试。

    通道设置里已经带上原来的凭证

    通道设置

    命令选项

    选项作用
    --agent迁到哪位专家。不填时用 octop agent use 设置的默认专家
    --from原来的目录不在默认位置时,指定那个目录
    --skip跳过一类内容,可写多次:models、files、skills、mcp、channels
    --overwrite覆盖已存在的工作区文件、技能和默认模型
    --dry-run只预演,不写入
    --user管理员替其他用户迁移时,指定 MCP 连接器归属的用户
    --json写在 migrate 前面,例如 octop --json migrate openclaw --agent XCZQWG,以 JSON 输出结果

    只迁人设、记忆和技能,不动模型、MCP 和通道:

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

    再跑一次

    可以重复运行。已经存在的内容一律跳过,不会被替换,所以第二次运行时每一项都显示「已跳过」。

    再次运行,每一项都已跳过

    再次运行

    想用 OpenClaw 里更新过的版本替换 Octop 里的文件,加上 --overwrite。它只覆盖工作区文件、技能和默认模型。模型供应商、MCP 连接器和通道永远不会被覆盖。需要重新迁移它们时,先在页面里删掉对应条目,再运行一次。

    常见问题

    提示「未找到 OpenClaw 的安装目录」。 目录不在默认位置。用 --from 指定,例如 --from /srv/openclaw。

    提示 --agent is required。 没有指定迁到哪位专家。加上 --agent,或先运行 octop agent use。也可以在命令最前面写根选项 --agent。

    有一项显示「失败」。 看 说明 列的原因,修正后再运行一次。已经成功的内容会跳过。有失败项时退出码为 1。

    迁完后对话里选不到模型,或对话报错。 确认已经重启 Octop,并在 管理 → 模型配置 里检查供应商的 API Key 和地址。

    OpenClaw 和 Hermes Agent 都在用,能迁到同一位专家吗? 可以,先后运行两条命令。后运行的那条遇到同名的人设文件、技能或已经设置的默认模型会跳过,不会覆盖先迁入的内容。希望两边分开时,各建一位专家,分别用 --agent 指定。