migrate-from-openclaw
Skill1 starsChanged 6 months agoMITView on GitHub
Migrate from OpenClaw to ClawBridge. Detects existing OpenClaw installation, extracts identity, channel credentials, scheduled tasks, and other config, then guides interactive migration. Triggers on "migrate from openclaw", "openclaw migration", "import from openclaw".
- Reads credentials
7 other projects use a version of this, 7 of them edited.
Adopted by
Most recently taken up by
- nanocoai/nanoclawedited, first seen Nov 15, 2026
- ss2code/nanoclaw-opsedited, first seen Oct 15, 2026
- prathish-ks/isthmusedited, first seen Oct 12, 2026
- gavrielc/nanoclawedited, first seen Oct 8, 2026
- qwibitai/nanoclawedited, first seen Oct 8, 2026
- TomGranot/groupguardedited, first seen Sep 3, 2026
Used with
Projects with it also use add-anydoc, add-clidash and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
TomGranotSkilladd-anydoc
Add local office-document-to-Markdown conversion to NanoClaw agent containers with the pinned Firecrawl AnyDoc CLI. Use when agents need to read attached Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, or text-based PDF files without uploading them to a hosted parser.
Also in 5 projects that use this
TomGranotSkilladd-clidash
Add clidash — a zero-dependency, read-only web dashboard that derives its tabs and tables at runtime from any CLI that lists resources as JSON. Ships pre-wired for NanoClaw's ncl CLI (agent groups, sessions, channels, users, roles), plus message-activity charts, a log tail, and a read-only file viewer for group skills/CLAUDE.md/profiles.
Also in 5 projects that use this
qwibitaiSkilladd-iron-proxy
Install or refresh Iron Proxy and its official Iron Control web console for NanoClaw. Use when selecting the Iron gateway, adding its management UI, configuring credentials and grants, or restoring the proxy, approval bridge, and agent guidance.
Also in 4 projects that use this
qwibitaiSkilladd-mattermost
Add a self-hosted or cloud Mattermost bot channel through the Chat SDK bridge, reusing a healthy server when available and linking to official server setup guidance when needed.
Also in 4 projects that use this
b1rdmaniaSkillmigrate-memory
Migrate from monolith CLAUDE.md to the three-file memory system (identity + state + log). Non-destructive — backs up the original first.
Also in 6 projects that use this
nanocoaiSkilladd-cursor
Use Cursor (local Agent SDK) as a full agent provider — planning, tool orchestration, MCP tools, session resume — alongside or instead of Claude. Cursor-account sign-in or API key, held by the credential gateway. Per-group via `ncl groups config update --provider cursor`. Distinct from using Cursor as a cloud agent (those run on Cursor VMs and are not this provider).
Also in 3 projects that use this
- +5 more from TomGranot
- +1 more from qwibitai
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 7
- gavrielc/nanoclaw★ 31k12% same
- nanocoai/nanoclaw★ 31k12% same
- qwibitai/nanoclaw★ 31k12% same
- microsoft/amplifier-app-nanoclaw★ 595% same
- TomGranot/groupguard★ 312% same
- prathish-ks/isthmus★ 212% same
- ss2code/nanoclaw-ops★ 112% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository42 other files it gives its agents.
- AGENTS.mdAGENTS.md
- container/AGENTS.mdAGENTS.md
- add-atomic-chat-toolSkill
- add-dashboardSkill
- add-discordSkill
- add-emacsSkill
- add-gcal-toolSkill
- add-gchatSkill
- add-githubSkill
- add-gmail-toolSkill
- add-imessageSkill
- add-karpathy-llm-wikiSkill
- add-linearSkill
- add-macos-statusbarSkill
- add-matrixSkill
- add-ollama-providerSkill
- add-ollama-toolSkill
- add-parallelSkill
- add-resendSkill
- add-signalSkill
- add-slackSkill
- add-teamsSkill
- add-telegramSkill
- add-vercelSkill
- add-webexSkill
- add-wechatSkill
- add-whatsapp-cloudSkill
- add-whatsappSkill
- clawSkill
- convert-to-apple-containerSkill
- customizeSkill
- debugSkill
- get-qodo-rulesSkill
- init-first-agentSkill
- manage-channelsSkill
- manage-mountsSkill
- migrate-clawbridgeSkill
- qodo-pr-resolverSkill
- setupSkill
- update-clawbridgeSkill
- update-skillsSkill
- x-integrationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
54 rules. 1 is common, 17 are distinctive, and 36 are very specific to this project.
1
Common
Most of the 7 edited versions we read keep these.
17
Distinctive
This author's own choices. Worth a look.
36
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Principle: Never silently copy data. Read it, explain it, discuss where it belongs in ClawBridge's architecture, show proposed changes …
- Very specific: line 12
UX:: Use AskUserQuestion for multiple-choice only.
- Very specific: line 16
Create migration-state.md in the project root at the start of Phase 0.
- Very specific: line 18
Before starting any phase, re-read migration-state.md to ensure you have current state.
- Distinctive: line 32
Keep it factual and terse — this is for machine recovery after compaction, not human reading.
- Common: line 36
Run the discovery script to find and summarize the OpenClaw installation:
- Very specific: line 42
If the user specifies a custom path, pass it: --state-dir <path>
- Very specific: line 78
If GROUP_COUNT > 0 or AGENT_COUNT > 1, this is a critical conversation.
- Distinctive: line 96
Before registering groups, confirm the assistant name — it's used for trigger patterns and CLAUDE.md templates.
- Very specific: line 112
Only pass --assistant-name on the first registration (it updates all CLAUDE.md templates globally).
- Very specific: line 124
Before identity/memory, extract settings from openclaw.json that map directly to ClawBridge setup.
- Very specific: line 128
Check agents.defaults.userTimezone in the config.
- Very specific: line 132
Check for Anthropic API keys or tokens in OpenClaw's auth system.
- Very specific: line 156
If found, offer to save to .env.
- Distinctive: line 162
Read the channel configs for access control settings.
- Distinctive: line 187
If OpenClaw had allowlists configured, show the user what was set and offer to create the ClawBridge equivalent.
- Distinctive: line 193
Create the directory and file:
- Very specific: line 202
Check agents.defaults.timeoutSeconds in the config.
- Very specific: line 204
If the OpenClaw value differs significantly from 30 minutes, note it for the user.
- Distinctive: line 219
Use the Read tool to look at each file found.
- Very specific: line 223
Read <STATE_DIR>/workspace/IDENTITY.md if it exists.
- Very specific: line 229
Read <STATE_DIR>/workspace/SOUL.md if it exists.
- Very specific: line 240
Add a reference in the relevant CLAUDE.md: "Your personality and extended behavioral guidelines are in soul.md.
- Very specific: line 246
Read <STATE_DIR>/workspace/USER.md if it exists.
- Very specific: line 248
Create groups/main/user-context.md with the user information.
- Distinctive: line 250
Ask if they want any critical user facts (name, timezone, key preferences) directly in CLAUDE.md for always-on awareness.
- Very specific: line 260
If DAILY_MEMORY_FILES > 0 in the discovery output, OpenClaw accumulated dated memory files (e.g.
- Distinctive: line 265
Create the folder in the appropriate group directory (per Phase 1 decision)
- Very specific: line 267
Add a reference in CLAUDE.md: "Historical daily memory files from your previous system are in daily-memories/.
- Distinctive: line 270
Read each file, extract entries worth keeping (skip transient observations, focus on durable facts about the user, preferences, recurring …
- Distinctive: line 272
Use sub-agents for large volumes (>10 files)
- Very specific: line 278
If SKILL_COUNT > 0 in discovery, OpenClaw had custom skills.
- Very specific: line 288
After all skills are copied, a container rebuild is needed — note this for post-migration: ./container/build.sh.
- Very specific: line 292
If CONFIG_PLUGIN_COUNT > 0 in discovery, OpenClaw had installed plugins/skills with API keys (e.g.
- Distinctive: line 310
If these exist, briefly mention them and explain:
- Very specific: line 322
Run the credential extraction script with --write-env .env so it writes credentials directly to ClawBridge's .env file.
- Very specific: line 334
If HAS_CREDENTIAL=true: Show the masked credential (CREDENTIAL_MASKED).
- Distinctive: line 339
If using the credential:
- Very specific: line 353
Allowlist note: If the channel had allowFrom or group policies, these were already handled in Phase 2 (sender allowlists).
- Very specific: line 359
If there are credentials (tokens, keys) for the unsupported channel, offer to save them to .env with a descriptive variable name (e.g.
- Very specific: line 361
Don't invoke channel skills here — just prepare .env credentials.
- Very specific: line 365
Read <STATE_DIR>/cron/jobs.json with the Read tool.
- Very specific: line 367
If jobs exist, read ${CLAUDE_SKILL_DIR}/MIGRATE_CRONS.md for the full OpenClaw cron format, ClawBridge table schema, field mapping, and SQL …
- Very specific: line 371
Read relevant sections from <STATE_DIR>/openclaw.json directly with the Read tool.
- Very specific: line 375
If MCP_SERVERS was non-empty in discovery, these can be ported.
- Distinctive: line 379
Read its config: command, args, env, url
- Very specific: line 384
After adding all MCP servers, a container rebuild is needed: ./container/build.sh
- Very specific: line 390
If the config has webhook sections (in cron.webhook, cron.failureDestination, or channel-specific webhooks):
- Distinctive: line 400
Human delay: Not applicable in ClawBridge's container model
- Distinctive: line 402
TTS: Not built into ClawBridge
- Distinctive: line 405
Don't belabor these — just mention and move on.
- Very specific: line 443
Config parse error: If openclaw.json fails to parse, it may use JSON5 features the parser doesn't handle.
- Very specific: line 445
Credential not found: If a channel credential resolves to empty, it may use source:"exec" or source:"file" SecretRef.
- Distinctive: line 447
Multi-agent complexity: If the user had many agents with different configs, focus on the primary/default agent first.
“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Migrate from OpenClaw
Guide the user through migrating their OpenClaw installation to ClawBridge. This is a conversation, not a batch job. Read OpenClaw state, discuss it with the user, make judgment calls together about what to bring over and how.
Principle: Never silently copy data. Read it, explain it, discuss where it belongs in ClawBridge's architecture, show proposed changes before applying. Credentials must be masked when displayed (first 4 + ... + last 4 characters). Make judgment calls about what's core vs. reference material.
UX: Use AskUserQuestion for multiple-choice only. Use plain text for free-form input. Don't dump raw data — summarize and explain conversationally.
Migration State File
Create migration-state.md in the project root at the start of Phase 0. Update it after each phase completes. This file is the single source of truth for the migration — if context is compacted or lost, re-read it to recover all decisions and progress.
Before starting any phase, re-read migration-state.md to ensure you have current state.
Sections to maintain (add data as each phase completes):
- Progress — checkbox list of phases (Phase 0–7)
- Discovery — STATE_DIR, IDENTITY_NAME, channels, groups (with JID mappings), workspace files, cron job count, MCP servers
- Decisions — assistant_name, group_model (shared/separate/main-only), main_group (folder + jid)
- Registered Groups — table: folder, jid, channel, is_main
- Settings Migrated — timezone, anthropic_credential (masked), sender_allowlist (created/skipped)
- Identity & Memory — paths of files created, which CLAUDE.md was edited
- Channel Credentials — table: channel, status, env_var
- Scheduled Tasks — table: original_id, name, migrated/deferred
- Deferred / Not Applicable — unsupported channels, discussed customizations, OpenClaw-only features
Keep it factual and terse — this is for machine recovery after compaction, not human reading. Delete the file at the end of Phase 7 (or offer to keep it as a record).
Phase 0: Discovery
Run the discovery script to find and summarize the OpenClaw installation:
pnpm exec tsx ${CLAUDE_SKILL_DIR}/scripts/discover-openclaw.tsIf the user specifies a custom path, pass it: --state-dir <path>
Parse the status block. Key fields: STATUS, STATE_DIR, CHANNELS, WORKSPACE_FILES, DAILY_MEMORY_FILES, SKILL_COUNT, SKILLS, CRON_JOBS, MCP_SERVERS, IDENTITY_NAME, AGENT_COUNT, AGENT_IDS.
Sanity-check the output: The discovery script detects known structures but can silently miss data if OpenClaw's format has changed. Check CONFIG_TOP_KEYS and CONFIG_CHANNEL_KEYS — if you see keys the script didn't report on (e.g. a channel name not in CHANNELS, or a top-level section like integrations or plugins), read that section of the config directly with the Read tool. Also check STATE_DIR_CONTENTS for directories the script doesn't scan (e.g. unexpected folders alongside workspace/, agents/, cron/).
If STATUS=not_found: Tell the user no OpenClaw installation was detected at the standard locations (~/.openclaw, ~/.clawdbot). Ask if they have a custom path. If not, exit.
If STATUS=found: Present a human-readable summary:
- "I found your OpenClaw installation at
<STATE_DIR>." - Identity: name from IDENTITY.md (if found)
- Workspace files: which of SOUL.md, USER.md, MEMORY.md, IDENTITY.md exist
- Channels: list each, note which ClawBridge supports (whatsapp, telegram, slack, discord) and which it doesn't
- Daily memory files: count (if any)
- Skills: count and names (from workspace, shared, personal, project locations)
- Cron jobs: count and names
- MCP servers: count and names
- Agents: count (relevant for Phase 1 groups discussion)
Then explain the key architectural differences. Don't dump a table — paraphrase conversationally:
- Container isolation: ClawBridge runs each agent in an isolated Linux container (Docker or Apple Container). OpenClaw runs everything in one process. This means stronger isolation but also means each group is its own sandbox.
- Group-based memory: In OpenClaw, all groups under one agent share the same SOUL.md, MEMORY.md, and IDENTITY.md. In ClawBridge, each group has its own filesystem and CLAUDE.md. Shared state goes in
groups/global/CLAUDE.md(mounted read-only into all non-main containers). - Channel skills: In OpenClaw, channels are configured in
openclaw.json. In ClawBridge, channels are installed as code via skills (/add-telegram,/add-whatsapp, etc.) and configured through.envvariables. - Simpler config: ClawBridge has no config file — behavior is in the code and
CLAUDE.mdfiles. Credentials live in.envor the OneCLI vault.
AskUserQuestion: "Ready to start migrating? I'll go through each area one at a time."
- Yes, let's go — proceed to Phase 1
- Tell me more — explain more about any area they ask about
- Skip migration — exit
Phase 1: Groups and Architecture
This discussion must happen before identity/memory, because the shared-vs-isolated decision determines where files go.
If GROUP_COUNT > 0 or AGENT_COUNT > 1, this is a critical conversation. Even with just one group, explain the model difference so the user understands what they're getting into.
OpenClaw model: All groups routed to the same agent share one workspace — the same SOUL.md, MEMORY.md, IDENTITY.md, and tools. When you talk to the bot in your family chat or your work chat, it's the same agent with the same personality and memory. Only the session (conversation history) is separate per group.
ClawBridge model: Each group is a completely separate agent running in its own Linux container. Separate filesystem, separate memory, separate CLAUDE.md. The bot in your family chat and your work chat are different agents that don't know about each other — unless you explicitly share state via groups/global/CLAUDE.md, which is mounted read-only into all non-main containers.
Explain this conversationally. If the user only has one group, it's simple — just note the difference and move on. If they have multiple groups, discuss:
AskUserQuestion: "In OpenClaw, your groups shared the same personality and memory. In ClawBridge, each group is a fully separate agent. How would you like to handle this?"
- Shared personality (recommended if your groups had the same bot) — "I'll put the shared personality, identity, and user context in
groups/global/CLAUDE.md. Every group sees it. Each group can add its own customizations on top." - Fully separate — "Each group gets its own independent personality and memory. Complete isolation between groups."
- Just main group for now — "Set up one group now. We can add others later."
Remember this choice — it determines where identity and memory files go in the next phase.
Confirm assistant name
Before registering groups, confirm the assistant name — it's used for trigger patterns and CLAUDE.md templates.
IDENTITY_NAME from discovery gives the OpenClaw name. Ask the user: "Your OpenClaw assistant was named <IDENTITY_NAME>. Want to keep this name in ClawBridge?" If they want a different name, ask what it should be. If IDENTITY_NAME was empty, ask them to choose a name (default: "Andy").
The register step's --assistant-name flag writes ASSISTANT_NAME to .env and updates CLAUDE.md templates automatically — no manual .env write needed.
Registering groups
The discovery script provides detected groups in the GROUPS field (format: channel:id(name)=>clawbridge_jid). These are extracted from OpenClaw's session store and channel config.
For each group the user wants to bring over, pre-register it:
pnpm exec tsx setup/index.ts --step register -- --jid "<clawbridge_jid>" --name "<group_name>" --folder "<channel>_<slug>" --trigger "@<confirmed_name>" --channel <channel> --assistant-name "<confirmed_name>"Only pass --assistant-name on the first registration (it updates all CLAUDE.md templates globally).
Folder naming: <channel>_<name-slug> (e.g. whatsapp_family-chat, telegram_dev-team). Ask the user to confirm each group's name and folder.
For the first/primary group, add --is-main --no-trigger-required. Other groups default to requiring a trigger prefix.
Important: Registration requires the database to exist. If the environment step hasn't been run yet, run it first: pnpm exec tsx setup/index.ts --step environment. Registration also creates the group folder under groups/ and copies the CLAUDE.md template.
Register groups from all channels — including channels ClawBridge doesn't yet support (signal, matrix, etc.). The registration stores the JID and metadata in the database, ready for when that channel is added later. Groups won't receive messages until their channel code is installed, but the registration, group folder, and CLAUDE.md will be ready.
Phase 2: Settings from Config
Before identity/memory, extract settings from openclaw.json that map directly to ClawBridge setup. Read the config file with the Read tool (<STATE_DIR>/openclaw.json or clawdbot.json).
Timezone
Check agents.defaults.userTimezone in the config. If present and it's a valid IANA timezone (e.g. America/New_York, Asia/Jerusalem), write it to .env as TZ=<timezone>. ClawBridge's setup step 2a reads TZ from .env (src/config.ts:84-97) and will skip the autodetection prompt.
Anthropic Credentials
Check for Anthropic API keys or tokens in OpenClaw's auth system. OpenClaw stores credentials in <STATE_DIR>/auth-profiles.json or <STATE_DIR>/agents/main/agent/auth-profiles.json with this structure:
{
"version": 1,
"profiles": {
"anthropic:default": {
"type": "api_key", // or "token" or "oauth"
"provider": "anthropic",
"key": "sk-ant-..." // for api_key type
}
}
}Profile IDs follow provider:identifier format. Look for any profile where provider is "anthropic". The credential field depends on the type:
type: "api_key"→keyfield (orkeyReffor SecretRef)type: "token"→tokenfield (ortokenReffor SecretRef)type: "oauth"→accessfield (OAuth access token, may need refresh)
Also check:
<STATE_DIR>/.env— forANTHROPIC_API_KEYorCLAUDE_CODE_OAUTH_TOKEN- Config
models.providers— for Anthropic provider entries withapiKey
If found, offer to save to .env. This pre-fills the ClawBridge setup credential step (step 4) so the user doesn't need to re-enter it. Use the same masking approach — show first 4 + last 4 characters, write the full value directly.
Important: If the credential uses keyRef/tokenRef with source:"exec" or source:"file", explain that it can't be auto-extracted and the user will need to enter it during setup. For type: "oauth" credentials with an expiry in the past, warn the user the token may need to be refreshed during setup.
Sender Allowlists
Read the channel configs for access control settings. OpenClaw stores these per-channel:
channels.<channel>.allowFrom— array of allowed sender IDs (E.164 for WhatsApp, numeric IDs for Telegram)channels.<channel>.dmPolicy—"open","allowlist","disabled"channels.<channel>.groupPolicy—"open","allowlist","disabled"channels.<channel>.groupAllowFrom— array of allowed group member IDs
ClawBridge uses ~/.config/clawbridge/sender-allowlist.json with this format:
{
"default": { "allow": "*", "mode": "trigger" },
"chats": {
"<chat-jid>": {
"allow": ["sender-id-1", "sender-id-2"],
"mode": "trigger"
}
},
"logDenied": true
}Fields:
allow:"*"(all senders) orstring[](specific sender IDs)mode:"trigger"(messages stored but trigger blocked for non-allowed senders) or"drop"(messages silently discarded before storage)logDenied: optional boolean (defaulttrue), logs denied messages
If OpenClaw had allowlists configured, show the user what was set and offer to create the ClawBridge equivalent. Map:
dmPolicy:"allowlist"+allowFrom→ per-chat entry with"allow"array,"mode": "trigger"groupPolicy:"allowlist"+groupAllowFrom→ per-group entry with"allow"array,"mode": "trigger"dmPolicy:"open"→"allow": "*"dmPolicy:"disabled"→ per-chat entry with"allow": [],"mode": "drop"(or don't register that chat)
Create the directory and file:
mkdir -p ~/.config/clawbridgeThen write the JSON file. If no allowlists were configured, skip this.
Container Timeout
Check agents.defaults.timeoutSeconds in the config. This is maximum total agent runtime (wall-clock). ClawBridge's equivalent is CONTAINER_TIMEOUT (env var, default 30 min), also configurable per-group via containerConfig.timeout. Note: ClawBridge also has a separate IDLE_TIMEOUT (max time without output) which resets on activity — OpenClaw has no equivalent.
If the OpenClaw value differs significantly from 30 minutes, note it for the user. They can set CONTAINER_TIMEOUT=<ms> in .env after setup.
Phase 3: Identity and Memory
This phase is fully conversational — read files directly and discuss with the user. No script needed.
Where files go depends on the Phase 1 (groups) decision:
- Shared personality: Core identity goes in
groups/global/CLAUDE.md(seen by all groups). Group-specific customizations go in each group's own CLAUDE.md. - Fully separate: Everything goes in
groups/main/(or each group's own folder). - Just main group: Everything goes in
groups/main/.
Find workspace files
The STATE_DIR from discovery tells you where OpenClaw lives. Look for workspace files at <STATE_DIR>/workspace/. If AGENT_COUNT > 1, also check <STATE_DIR>/agents/*/workspace/ and ask which agent to migrate.
Use the Read tool to look at each file found.
IDENTITY.md
Read <STATE_DIR>/workspace/IDENTITY.md if it exists. It uses a key:value format (name, emoji, creature, vibe, etc.).
The assistant name was already confirmed and written to .env in Phase 1. Here, focus on the rest of the identity — create an identity.md file with the full identity details (emoji, creature, vibe, personality traits, etc.). If shared personality was chosen in Phase 1, put it alongside groups/global/CLAUDE.md. Otherwise, put it in groups/main/.
SOUL.md
Read <STATE_DIR>/workspace/SOUL.md if it exists. Then read groups/main/CLAUDE.md.
CLAUDE.md is always loaded into the agent's context — it's the agent's continuous instructions. Not everything from SOUL.md needs to be there. Discuss with the user what belongs where:
- In CLAUDE.md (always loaded): Core personality traits, communication style, key behavioral rules. Weave these into the existing CLAUDE.md structure — adjust the opening description under the
# <Name>heading, modify the tone in the Communication section. - In a separate soul file: Detailed personality backstory, extended guidelines, creative writing style, philosophical grounding — things the agent can reference when relevant but don't need to consume context tokens on every turn.
File placement depends on Phase 1 choice:
- Shared personality → edit
groups/global/CLAUDE.mdfor the core traits, creategroups/global/soul.mdfor the extended content. All groups will see both. - Separate / main only → edit
groups/main/CLAUDE.md, creategroups/main/soul.md.
Add a reference in the relevant CLAUDE.md: "Your personality and extended behavioral guidelines are in soul.md. Refer to it for identity questions or when crafting responses that need your full character."
Show proposed edits to the user before applying. This is a thoughtful merge, not a copy-paste.
USER.md
Read <STATE_DIR>/workspace/USER.md if it exists.
Create groups/main/user-context.md with the user information. Add a reference in CLAUDE.md: "Information about your user is in user-context.md. Read it when you need context about who you're talking to."
Ask if they want any critical user facts (name, timezone, key preferences) directly in CLAUDE.md for always-on awareness.
MEMORY.md
Read <STATE_DIR>/workspace/MEMORY.md if it exists.
Show the contents and discuss what's worth keeping. Some memory entries may be stale or OpenClaw-specific. Create groups/main/memories.md for relevant items. Add a reference in CLAUDE.md.
Daily memory files (workspace/memory/*.md)
If DAILY_MEMORY_FILES > 0 in the discovery output, OpenClaw accumulated dated memory files (e.g. 2024-01-01.md). These contain observations, facts, and context gathered over time.
AskUserQuestion: "You have N daily memory files from OpenClaw. How would you like to handle them?"
- Copy as-is (recommended for many files) — "I'll create a
daily-memories/folder in your group directory and copy them over. Your agent can reference them when needed."- Create the folder in the appropriate group directory (per Phase 1 decision)
- Copy all
.mdfiles:cp -r <workspace>/memory/*.md <group_dir>/daily-memories/ - Add a reference in CLAUDE.md: "Historical daily memory files from your previous system are in
daily-memories/. Refer to them when you need context about past events or observations."
- Consolidate into memories — "I'll read through them, extract the durable facts, and add them to your memories file. This reduces clutter but takes longer."
- Read each file, extract entries worth keeping (skip transient observations, focus on durable facts about the user, preferences, recurring topics)
- Consolidate into
memories.md - Use sub-agents for large volumes (>10 files)
- Skip — "Don't bring daily memories over."
OpenClaw Skills
If SKILL_COUNT > 0 in discovery, OpenClaw had custom skills. The SKILL.md format is a shared standard — skills are directly portable.
The discovery reports skill names and source locations. For each skill, read just the YAML front matter (name + description at the top of SKILL.md) and present a list to the user: skill name, description, source location. Let the user select which ones to bring over.
For confirmed skills, copy the entire skill directory as-is:
cp -r <skill_source_dir> container/skills/<skill_name>After all skills are copied, a container rebuild is needed — note this for post-migration: ./container/build.sh.
Config-registered plugins and skills
If CONFIG_PLUGIN_COUNT > 0 in discovery, OpenClaw had installed plugins/skills with API keys (e.g. plugins.entries.brave, skills.entries.openai-whisper-api). These are functional tools the agent had access to.
For each detected plugin, present the name to the user and discuss whether to set it up in ClawBridge. Read the OpenClaw config section to understand what it is, then:
- If ClawBridge has a matching skill — check the available ClawBridge skills list for an equivalent (e.g.
/add-voice-transcriptionfor whisper). If found, save the API key to.envand invoke that skill. - If the OpenClaw plugin was an MCP server — read its config to find the exact package name and command. Install the same MCP server (e.g.
pnpm dlx <exact-package-from-config>). Don't search for or guess at MCP packages — only install what was explicitly configured. - If the OpenClaw plugin was a CLI tool — read the config to identify the exact tool. If it's an npm package, add it to the container's Dockerfile. Add a note to the group's CLAUDE.md that the tool is available and how to invoke it.
- If the plugin wraps an API — discuss with the user what it did and offer to implement the equivalent: save the API key to
.env, write a container skill with instructions for using the API, or wire it into the message flow if it's something automatic (e.g. voice transcription). - If unclear — discuss with the user what the plugin did and decide together. Don't install unknown packages or search for replacements — that's a supply chain risk.
For API keys, read the config value directly (don't display raw keys) and write to .env. The discovery script reports which plugins have keys but never extracts them.
Other files (TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md, AGENTS.md)
If these exist, briefly mention them and explain:
- TOOLS.md: ClawBridge agents have their own tool discovery; this doesn't transfer
- HEARTBEAT.md: ClawBridge uses scheduled tasks instead
- BOOTSTRAP.md: ClawBridge uses CLAUDE.md and container skills instead
- AGENTS.md: Already covered in the Phase 1 groups discussion
Phase 4: Channel Credentials
For each channel found in the discovery results, handle it based on ClawBridge support:
Supported channels (whatsapp, telegram, slack, discord)
Run the credential extraction script with --write-env .env so it writes credentials directly to ClawBridge's .env file. The script never emits raw credential values to stdout — only masked versions.
First, run without --write-env to preview:
pnpm exec tsx ${CLAUDE_SKILL_DIR}/scripts/extract-channel-credentials.ts --state-dir <STATE_DIR> --channel <name>Parse the status block. Key fields: HAS_CREDENTIAL, CREDENTIAL_MASKED, CLAWBRIDGE_ENV_VAR.
If HAS_CREDENTIAL=false but the user expects a credential: The extraction script may not recognize the config structure. Fall back to reading the channel section of openclaw.json directly with the Read tool and look for any field that contains a token or key value. Ask the user to confirm.
If HAS_CREDENTIAL=true: Show the masked credential (CREDENTIAL_MASKED). AskUserQuestion:
- Use this credential — run again with
--write-env .envto save it - Enter a new one — ask in plain text, write to
.envmanually - Skip this channel — don't configure
If using the credential:
pnpm exec tsx ${CLAUDE_SKILL_DIR}/scripts/extract-channel-credentials.ts --state-dir <STATE_DIR> --channel <name> --write-env .envThe script writes the credential directly to .env using the correct ClawBridge variable name (e.g. TELEGRAM_BOT_TOKEN). Check the status block for WRITTEN_TO and WRITTEN_COUNT to confirm.
Credential destination note: Credentials are saved to .env for now. During /setup, the credential step will either keep them in .env (Apple Container) or migrate them to the OneCLI vault (Docker). The user doesn't need to worry about this now.
For Slack: there are two credentials (bot token + app token). The script handles both in one run — check HAS_CREDENTIAL_2 and CLAWBRIDGE_ENV_VAR_2 in the status block.
WhatsApp special case: WhatsApp uses QR/pairing-code authentication, not a token. Do not copy auth state from OpenClaw — encryption sessions become stale after copying and messages fail to decrypt. Authentication will be handled during /setup via the /add-whatsapp skill (takes about 60 seconds with a pairing code). Just note that WhatsApp was configured and move on.
Allowlist note: If the channel had allowFrom or group policies, these were already handled in Phase 2 (sender allowlists). Mention that the allowlist file was created earlier.
Unsupported channels (signal, matrix, irc, msteams, feishu, etc.)
Explain briefly: "ClawBridge doesn't have a <channel> integration yet, but channels are added over time via skills. Any groups from this channel were already registered in Phase 1 — they'll activate when the channel is added."
If there are credentials (tokens, keys) for the unsupported channel, offer to save them to .env with a descriptive variable name (e.g. SIGNAL_ACCOUNT, MATRIX_ACCESS_TOKEN) so they're available when the channel is eventually supported.
Don't invoke channel skills here — just prepare .env credentials. Channel code is installed during /setup.
Phase 5: Scheduled Tasks
Read <STATE_DIR>/cron/jobs.json with the Read tool. If the file doesn't exist or has no jobs, skip this phase.
If jobs exist, read ${CLAUDE_SKILL_DIR}/MIGRATE_CRONS.md for the full OpenClaw cron format, ClawBridge table schema, field mapping, and SQL insert template. Follow those instructions for each job.
Phase 6: Webhooks, MCP, and Other Config
Read relevant sections from <STATE_DIR>/openclaw.json directly with the Read tool. This phase is fully conversational.
MCP Servers
If MCP_SERVERS was non-empty in discovery, these can be ported. Claude Code supports MCP servers natively. Read the OpenClaw config's mcp.servers section to get each server's details (command, args, env, url).
MCP servers in ClawBridge are registered in the agent-runner source code. Before editing, grep for mcpServers in container/agent-runner/src/ to find the current location — it's expected to be in index.ts in the query() options, but may have moved. For each OpenClaw MCP server the user wants to bring over:
- Read its config: command, args, env, url
- stdio servers (have
command): Add an entry to themcpServersobject incontainer/agent-runner/src/index.ts. The command runs inside the container, so it needs to be available there (Node.js/npx-based servers work; custom binaries would need to be added to the Dockerfile). - HTTP/SSE servers (have
url): These work if the URL is accessible from inside the container. Add them the same way. - Environment variables: Any
envvalues that reference secrets should be added to.envand passed through viaprocess.env.*in the mcpServers entry.
After adding all MCP servers, a container rebuild is needed: ./container/build.sh
Show the user each server and ask which to bring over. For servers that need custom binaries not available in the container, note them for manual setup.
Webhooks and Endpoints
If the config has webhook sections (in cron.webhook, cron.failureDestination, or channel-specific webhooks):
- Explain what they were used for
- These don't map directly but ClawBridge can be customized to support them
- Discuss the use case with the user and propose a solution if it's important to them
- For simple webhook notifications: a task script with
curloften suffices
Other Config
Scan the config for notable sections and briefly mention anything that doesn't carry over:
- Exec approvals / command allowlist: ClawBridge uses container isolation instead — the agent runs with
--dangerously-skip-permissionsinside a sandboxed container - Human delay: Not applicable in ClawBridge's container model
- Compaction: Handled by Claude Code SDK automatically
- TTS: Not built into ClawBridge
- Model configuration: ClawBridge uses whatever Anthropic model the credential provides access to
Don't belabor these — just mention and move on.
Phase 7: Summary
Summary
Print a comprehensive summary:
Migrated:
- Assistant name →
.envASSISTANT_NAME + CLAUDE.md templates updated - Groups → registered in database, folders created with CLAUDE.md templates
- Timezone →
.envTZ - Anthropic credential →
.env(for setup to pick up) - Sender allowlists →
~/.config/clawbridge/sender-allowlist.json - Personality → CLAUDE.md (core) +
soul.md(extended), placed per Phase 1 decision (global or per-group) - User context →
user-context.md - Memories →
memories.md+ daily memory files (copied todaily-memories/or consolidated) - OpenClaw skills → copied to
container/skills/ - Channel credentials →
.env(list which channels) - Scheduled tasks → inserted into database or noted for post-setup
- MCP servers → registered in agent-runner
Noted for later:
- Channel code installation (happens during
/setup) - Task creation (if deferred due to no registered group yet)
- Container rebuild needed (if skills or MCP servers were added):
./container/build.sh
Not applicable:
- Unsupported channels (list them — groups registered for future)
- OpenClaw-specific features (exec approvals, human delay, TTS, model config, session reset policies, etc.)
Discussed and deferred:
- List any customizations agreed on but not yet implemented
Remind: "Run /setup next to complete your ClawBridge installation. Channel credentials are already prepared in .env. When setup asks which channels to enable, select the ones we configured."
Troubleshooting
Config parse error: If openclaw.json fails to parse, it may use JSON5 features the parser doesn't handle. Ask the user to check the file for unusual syntax. As a fallback, the agent can read the file directly and work with it manually.
Credential not found: If a channel credential resolves to empty, it may use source:"exec" or source:"file" SecretRef. These can't be auto-extracted. Ask the user to provide the value directly.
Multi-agent complexity: If the user had many agents with different configs, focus on the primary/default agent first. Additional agents can be set up as separate ClawBridge groups later.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

