12.1. OpenClaw / NanoClaw Migration Guide¶

This guide is for users migrating from OpenClaw or NanoClaw to Backend.AI GO Squad. It covers concept mapping, configuration migration, behavioral differences, step-by-step migration instructions, and frequently asked questions.

Concept Mapping¶

Backend.AI GO Squad redesigns the NanoClaw group-agent model with a modern multi-agent workspace. The table below maps every NanoClaw concept to its Squad equivalent.

Role Mapping¶

NanoClaw used free-form role strings. Backend.AI GO Squad provides structured roles with specialized defaults.

Configuration Migration¶

Environment Settings¶

NanoClaw group configuration stored in .env or group-config.json maps to Backend.AI GO settings.

NanoClaw .env or config file:

NANOCLAW_GROUP_NAME=my-dev-team
NANOCLAW_MODEL=claude-3-5-sonnet
NANOCLAW_MAX_ITERATIONS=20
NANOCLAW_TIMEOUT_MS=120000
NANOCLAW_CONTAINER_IMAGE=nanoclaw-runner:latest
NANOCLAW_ALLOW_NETWORK=false

Backend.AI GO Squad equivalent:

1. Open Squad in the sidebar and click New Squad.
2. Set the squad name in Step 1: Basic Info.
3. Choose the model in each agent's configuration panel — or use an Agent Profile with modelPreference set.
4. Max iterations and timeout are set in Settings > Agent (global defaults) or per-agent via an Agent Profile with settingsOverrides.
5. Container image is set per-agent in the squad editor under Execution Mode > Container > Image.

Settings > Agent (global defaults):

Max Iterations: 20       ← NANOCLAW_MAX_ITERATIONS
Timeout: 120000 ms       ← NANOCLAW_TIMEOUT_MS

Group Folders¶

NanoClaw group folders stored shared files and agent memory. In Backend.AI GO Squad, the equivalent is the Squad Workspace.

NanoClaw group folder layout:

~/nanoclaw-groups/my-dev-team/
├── CLAUDE.md            ← group-level instructions
├── memory/
│   ├── agent-alice.md
│   └── agent-bob.md
├── workspace/
│   └── ...project files...
└── tasks/
    └── task-001.json

Backend.AI GO Squad workspace layout:

~/my-squads/my-dev-team/        ← Squad Workspace directory
├── .squad-config.json          ← squad manifest (auto-generated)
├── plans/                      ← task plans
├── tasks/                      ← task state files
├── agents/
│   ├── alice/
│   │   └── memory.md           ← per-agent memory
│   └── bob/
│       └── memory.md
├── ipc/                        ← host-container IPC (container mode only)
│   ├── input/
│   ├── messages/
│   └── tasks/
└── ...project files...

To migrate, copy your existing project files into the new workspace directory. Memory files can be copied to agents/{agent-name}/memory.md.

CLAUDE.md Migration¶

NanoClaw used CLAUDE.md files for agent instructions at both the group level and the folder level.

Group-level CLAUDE.md → Squad Agent System Prompt

Copy the content of your group-level CLAUDE.md into each agent's System Prompt field in the Squad editor. If different agents had different instruction files, paste each one into the corresponding agent.

Folder-level CLAUDE.md → Cowork Folder Instructions

If you used folder-level CLAUDE.md for directory-specific context (for example, explaining what a folder contains), use Cowork Folder Instructions instead:

1. Open Cowork in the sidebar.
2. Go to Folder Instructions.
3. Add the folder path and paste the content.

Folder instructions are automatically injected into the agent's context whenever it accesses that directory.

Channel Configuration¶

Channel setup is identical between NanoClaw and Backend.AI GO. Your existing channel credentials transfer directly.

To migrate channels:

1. Open Settings > Channels in Backend.AI GO.
2. Select the channel type (Telegram, Slack, Discord, or WhatsApp).
3. Enter the same credentials you used in NanoClaw.
4. Click Connect and verify the status shows Connected.

Sender Allowlist Migration¶

NanoClaw's allowlist.json maps directly to the Sender Allowlist in Backend.AI GO.

NanoClaw allowlist.json:

{
  "telegram": ["123456789", "987654321"],
  "slack": ["U01234ABCD"]
}

Backend.AI GO:

1. Open Settings > Channels > [Channel Name].
2. Click Sender Allowlist.
3. Enter each sender ID or username from your NanoClaw allowlist.

Channel-Squad Mapping¶

In NanoClaw, channels triggered a group by name. In Backend.AI GO, you map channels to specific squads.

1. Open Settings > Channels and select a connected channel.
2. Under Squad Mapping, choose the squad that should handle messages from this channel.
3. Optionally set a default agent within the squad to receive the initial message.

See the Channel-Squad Mapping guide for advanced routing rules.

Behavioral Differences¶

Container Image¶

NanoClaw used nanoclaw-runner as the container base image. Backend.AI GO uses aigo-agent-runner.

To build the Backend.AI GO agent runner image, follow the Container Execution Guide.

IPC Protocol¶

NanoClaw agents used stdio-based IPC for host-container communication. Backend.AI GO uses file-based IPC through the workspace IPC directory.

If you have custom tooling that reads NanoClaw's stdio IPC, update it to use the file-based IPC format. See src-tauri/src/container/ipc.rs for the IPC directory structure.

Planning and Execution¶

NanoClaw relied on agents deciding their own steps implicitly. Backend.AI GO Squad introduces an explicit Planner Agent that generates a structured task graph.

Additional Features¶

Backend.AI GO Squad includes capabilities not present in NanoClaw.

Step-by-Step Migration Tutorial¶

This section walks through migrating a sample NanoClaw group called my-dev-team to a Backend.AI GO Squad.

Step 1: Inventory Your Existing Setup¶

Before migrating, collect the following from your NanoClaw setup:

• Group configuration file (.env, group-config.json, or equivalent)
• List of group members (names, roles, system prompts)
• Group-level CLAUDE.md content
• Channel credentials and allowlists
• The location of the group workspace folder

Step 2: Install Backend.AI GO¶

Download and install the latest Backend.AI GO from go.backend.ai. On first launch, complete the First-Time Setup wizard and verify a model is loaded and running.

Step 3: Set Up Container Runtime (Optional)¶

If your NanoClaw setup used containers, install a container runtime first. Skip this step if you used in-process (non-container) execution.

1. Follow the Container Execution Guide.
2. Build the agent runner image: run make build-agent-runner in the Backend.AI GO source directory, or follow the build script.
3. Verify the image appears in Settings > Container > Available Images.

Step 4: Create the Squad¶

1. Click Squad in the sidebar.
2. Click New Squad and choose Custom (not a template, to match your existing setup).
3. Enter your group name as the squad name. Click Next.
4. In the Workspace step, select your existing NanoClaw group folder, or create a new directory. If you reuse the same folder, Backend.AI GO adds a .squad-config.json manifest alongside existing files. Click Next.
5. In the Agents step, click Add Agent for each group member:
   • Set the agent Name to the group member's name.
   • Select the closest Role (Planner, Developer, Reviewer, Writer, or Custom).
   • Paste the group member's CLAUDE.md content or system prompt into System Prompt.
   • Enable the same tools the agent used in NanoClaw.
   • If the agent had a memory file, enable Memory.
   • If using containers, set Execution Mode to Container and enter aigo-agent-runner:latest as the image.
6. Designate one agent as the Planner (check Designate as Planner). This is usually the group leader.
7. Click Next, review the configuration, and click Create.

Step 5: Migrate Memory Files¶

If your NanoClaw agents had memory files:

1. Open the squad's workspace directory in a file manager.
2. For each agent, copy the NanoClaw memory file to agents/{agent-name}/memory.md.
3. The agent will load this memory automatically on the next run.

Step 6: Configure Channels¶

1. Open Settings > Channels.
2. Add each channel with the same credentials from NanoClaw.
3. Under Squad Mapping, map each channel to the squad you created in Step 4.
4. Add all sender IDs from the NanoClaw allowlist to Sender Allowlist.

Step 7: Set Budget Limits (Optional but Recommended)¶

1. Open the squad and click Edit.
2. Go to the Budget section.
3. Set token limits appropriate for your workload. As a starting point, use the total token usage from your NanoClaw runs as the squad total budget.

Step 8: Run a Test Task¶

1. Open the squad and click Run.
2. Enter a simple test request (for example: "Say hello and confirm your name and role.").
3. Review the generated plan and click Approve.
4. Monitor execution in the Monitoring tab.
5. Check that all agents complete successfully and output appears in the workspace.

Step 9: Verify Channel Integration¶

If you configured channels, send a test message from an allowed sender. The squad should receive the message and respond through the same channel.

FAQ¶

Do I need to rebuild my container images?¶

Yes. NanoClaw used the nanoclaw-runner image, which is incompatible with Backend.AI GO. You need to build aigo-agent-runner using the provided build script. If you added custom dependencies to the NanoClaw image, add them to the Backend.AI GO Dockerfile.agent-runner before building.

Can I reuse my NanoClaw group workspace as-is?¶

Yes. Selecting the existing workspace directory in the Squad setup wizard will add a .squad-config.json manifest to the folder without touching existing files. Your project files and memory files remain in place.

My NanoClaw group had 10+ members. Can Squad handle that?¶

Yes. Backend.AI GO Squad supports up to 20 agents per squad. For very large teams, consider splitting the squad into a primary squad and secondary squads that are triggered by channel routing.

How do I handle NanoClaw's CLAUDE.md hierarchy?¶

• Group-level CLAUDE.md → Agent System Prompt (per agent, in the squad editor)
• Project-level CLAUDE.md files in subdirectories → Folder Instructions (in Cowork settings)

If you need the agent to discover CLAUDE.md files dynamically during execution, add a note in the system prompt: "Look for CLAUDE.md files in directories you visit and follow their instructions."

What happens to NanoClaw stdio IPC tools I wrote?¶

Stdio-based IPC tools are incompatible with Backend.AI GO's file-based IPC. You will need to update your tooling to write and read JSON files from the IPC directory (workspace/ipc/). The file format is documented in the Container Execution Guide.

Is there an import tool to convert NanoClaw config automatically?¶

There is no automated import tool at this time. The manual migration outlined in this guide typically takes 15–30 minutes for a typical NanoClaw group.

Can I run Backend.AI GO and NanoClaw side-by-side?¶

Yes. They use separate data directories and separate container images. You can run both during the transition period to compare outputs before fully switching over.

My channel messages are not reaching the squad. What do I check?¶

1. Verify the channel shows Connected in Settings > Channels.
2. Confirm the sender ID is in the Sender Allowlist.
3. Check that the channel is mapped to the correct squad in Squad Mapping.
4. Review the channel logs in Settings > Channels > [Channel Name] > Logs.

Where is the equivalent of NanoClaw's --headless mode?¶

Use Headless Mode in Backend.AI GO. Start the app with the --headless flag or enable it in Settings > Advanced > Headless Mode. The Management API provides REST endpoints equivalent to NanoClaw's headless API. See the Headless Mode guide.

How do I get help?¶

• In-app: open Settings > Help for links to documentation and the community forum.
• Documentation: go.backend.ai/en/manual/
• Community: Backend.AI GO discussions on GitHub