How to Migrate OpenClaw from Windows to Ubuntu on Tencent Cloud
Migrating OpenClaw from Windows to an Ubuntu cloud server involves more than installing the same OpenClaw version on a new machine. The important part is preserving the working environment while adapting paths, authentication, plugins, Gateway settings, and server-side configuration to Linux.
This migration moved an OpenClaw installation from Windows to a Tencent Cloud Ubuntu server. Both environments were standardized on OpenClaw 2026.5.28.
The migration covered the OpenClaw Workspace, DeepSeek model configuration, authentication, WeChat account state, Gateway configuration, and selected plugins. Feishu was deliberately left for a separate configuration step because the existing plugin state required additional compatibility work.
The commands and configuration examples below reflect the actual migration process, including the errors and warnings encountered along the way.
Windows and Ubuntu Migration Environment
The Windows installation used the following OpenClaw state directory and Workspace.
Windows OpenClaw state
C:\Users\Administrator\.openclaw
Windows Workspace
D:\WorkSpace
The Ubuntu server used:
Ubuntu OpenClaw state
/home/ubuntu/.openclaw
Final Ubuntu Workspace
/home/ubuntu/WorkSpace
Both environments used:
OpenClaw 2026.5.28
The version match was intentional. The Ubuntu installation had previously been upgraded to a newer OpenClaw release and was subsequently downgraded to 2026.5.28 to match the Windows installation.
This version alignment reduced the risk of configuration and plugin compatibility differences during migration.
Back Up the Existing Ubuntu OpenClaw Environment First
Before changing anything on the Ubuntu server, create a complete backup of the existing OpenClaw state.
cp -a /home/ubuntu/.openclaw \
/home/ubuntu/.openclaw.before-migration
Back up the main configuration separately as well.
cp /home/ubuntu/.openclaw/openclaw.json \
/home/ubuntu/.openclaw/openclaw.json.before-merge
These backups provide a rollback point if configuration merging or plugin restoration causes problems.
This step matters especially on a cloud server because the existing installation may already contain working Gateway, browser, systemd, and other server-specific settings.
Migrate the Windows Workspace Separately
The actual Windows Workspace was:
D:\WorkSpace
It contained the working files used by the OpenClaw agent, including:
.agents
AGENTS.md
all-skills-lite
HEARTBEAT.md
IDENTITY.md
memory
MEMORY.md
.openclaw
personas
plugin-skills
quant-datahub
skills
SOUL.md
strategies
tools
TOOLS.md
USER.md
It also contained:
skills-lock.json
SKILLS_INDEX.md
The Workspace was packaged separately and transferred to Ubuntu.
The archive was initially extracted to:
/home/ubuntu/WorkSpace.new
The final move was:
mv /home/ubuntu/WorkSpace.new /home/ubuntu/WorkSpace
During the migration, an incorrect command was attempted:
mv /home/ubuntu/WorkSpace.new /home/ubuntu/WorkSpace.new/
The shell returned an error indicating that the directory could not be moved into itself.
The error did not damage the files. The correct operation was to move the temporary directory directly to the final Workspace path.
The final Workspace was verified as:
/home/ubuntu/WorkSpace
├── .agents
├── AGENTS.md
├── all-skills-lite
├── HEARTBEAT.md
├── IDENTITY.md
├── memory
├── MEMORY.md
├── .openclaw
├── personas
├── plugin-skills
├── quant-datahub
├── skills
├── SOUL.md
├── strategies
├── tools
├── TOOLS.md
└── USER.md
The Workspace migration was then complete.
Do Not Replace the Entire Ubuntu .openclaw Directory
The Windows OpenClaw state directory contained many different types of data.
agents
completions
credentials
cron
delivery-queue
devices
feishu
flows
identity
logs
media
memory
npm
openclaw-weixin
plugin-skills
plugins
subagents
tasks
It also contained files such as:
openclaw.json
exec-approvals.json
The complete Windows state archive was approximately 316 MB compressed and approximately 1.4 GB after extraction.
Some of the largest directories were:
npm 794M
agents 552M
workspace 48M
These directories contain runtime state, packages, agent data, and machine-specific information.
Copying the entire Windows .openclaw directory over the Ubuntu installation would therefore introduce Windows paths and runtime state into the Linux environment.
The migration used a selective approach instead. The Workspace was migrated separately, while only the required authentication, channel, model, and configuration data was carried into the existing Ubuntu OpenClaw installation.
Migrate the WeChat Account State
The Windows installation contained WeChat state under:
.openclaw/openclaw-weixin
The account data included:
accounts/
├── 9879554571ac-im-bot.json
├── 9879554571ac-im-bot.context-tokens.json
└── 9879554571ac-im-bot.sync.json
accounts.json
These files were copied to:
/home/ubuntu/.openclaw/openclaw-weixin/
The resulting directory contained:
accounts/9879554571ac-im-bot.json
accounts/9879554571ac-im-bot.context-tokens.json
accounts/9879554571ac-im-bot.sync.json
accounts.json
This preserved the existing WeChat account state during the migration.
Migrate Only the Credentials You Have Identified
The Windows credentials directory was:
.openclaw/credentials
The migration identified these files:
feishu-pairing.json
feishu-default-allowFrom.json
They were copied to:
/home/ubuntu/.openclaw/credentials/
A DeepSeek credential file was not found in this directory.
This distinction became important later because the DeepSeek model configuration could be migrated while the actual API key still needed to be authenticated separately on Ubuntu.
Why You Should Merge openclaw.json Instead of Replacing It
The Windows configuration contained the original local environment settings, while the Ubuntu server already had cloud-specific configuration.
The Windows Workspace path was:
D:\WorkSpace
The Ubuntu installation originally used:
/home/ubuntu/.openclaw/workspace
The Gateway configuration on Ubuntu also contained server-specific settings such as:
port = 35395
bind = lan
basePath = /h5sswr
The Ubuntu installation also had Control UI settings and browser configuration that were specific to the cloud server.
The browser configuration included paths under:
/home/ubuntu/.cache/ms-playwright/...
Replacing the entire Ubuntu openclaw.json with the Windows configuration would overwrite these server-specific settings.
The migration therefore used a configuration merge.
First, the Ubuntu configuration was backed up.
cp /home/ubuntu/.openclaw/openclaw.json \
/home/ubuntu/.openclaw/openclaw.json.pre-migration-merge
The Windows configuration was then used as the source for selected sections.
The migrated sections included:
agents.defaults.workspace
agents.defaults.models
agents.defaults.model.primary
models
auth.profiles
plugins.entries
channels
bindings
commands
session
tools
The existing Ubuntu Gateway and browser settings were preserved.
The final Workspace setting became:
/home/ubuntu/WorkSpace
The primary model became:
deepseek/deepseek-v4-flash
The DeepSeek provider was restored.
The authentication profile was restored.
The channel and binding configuration was migrated.
The Ubuntu Gateway remained configured as:
port = 35395
bind = lan
basePath = /h5sswr
This approach preserved the existing cloud-server configuration while restoring the Windows AI environment.
Restore the DeepSeek Model Configuration
The Windows OpenClaw installation used:
deepseek/deepseek-v4-flash
The provider configuration used the DeepSeek API endpoint:
https://api.deepseek.com
with:
api = openai-completions
The default model configuration was:
{
"primary": "deepseek/deepseek-v4-flash"
}
The model alias was:
DeepSeek -> deepseek/deepseek-v4-flash
The Windows configuration also contained these DeepSeek models:
deepseek-v4-flash
deepseek-v4-pro
deepseek-chat
deepseek-reasoner
After the configuration merge, OpenClaw reported:
Default : deepseek/deepseek-v4-flash
Aliases (1) : DeepSeek -> deepseek/deepseek-v4-flash
Configured models (1): deepseek/deepseek-v4-flash
At this stage the model configuration was present.
The API authentication still had to be restored separately.
Configure the DeepSeek API Key on Ubuntu
The first post-migration model check was:
openclaw models status
OpenClaw reported:
Missing auth
- deepseek Run `openclaw models auth login --provider deepseek`,
`openclaw configure`, or set an API key env var.
The existing Windows credentials did not contain a usable DeepSeek API key, so the key was configured through OpenClaw’s authentication command.
Run:
openclaw models auth login --provider deepseek
OpenClaw prompts for:
Enter DeepSeek API key
Enter the API key directly in the Ubuntu terminal.
The API key should not be copied into a blog post, chat message, shell history, or configuration snippet.
After authentication, OpenClaw reported:
Updated config: ~/.openclaw/openclaw.json
Auth profile: deepseek:default (deepseek/api_key)
Default model available: deepseek/deepseek-v4-flash
Run the status check again:
openclaw models status
The important result was:
Auth store : ~/.openclaw/agents/main/agent/auth-profiles.json
Shell env : off
Providers w/ OAuth/tokens (0): -
deepseek effective=profiles:~/.openclaw/agents/main/agent/auth-profiles.json
profiles=1 (oauth=0, token=0, api_key=1)
The key indicator is:
api_key=1
This confirms that OpenClaw has a DeepSeek API key in the Agent authentication store.
Run openclaw doctor After the Migration
Once the DeepSeek authentication was restored, run:
openclaw doctor
The doctor process performed several useful checks.
It installed or updated the user-level Gateway service:
Installed systemd service:
/home/ubuntu/.config/systemd/user/openclaw-gateway.service
The previous unit was backed up:
/home/ubuntu/.config/systemd/user/openclaw-gateway.service.bak
The doctor also detected that the Gateway service had been using a Node version managed through NVM:
/home/ubuntu/.nvm/versions/node/v22.23.2/bin/node
It recommended a system Node 22 LTS or Node 24 installation for a future migration away from version-managed Node.
During this migration, the existing Node environment was left in place because OpenClaw was already functioning and changing the runtime would introduce another variable.
Plugin Version Warnings Do Not Always Require Immediate Fixes
The migration repeatedly produced warnings for several plugins.
discord requires plugin API >=2026.7.1
qqbot requires plugin API >=2026.7.1
slack requires plugin API >=2026.7.1
whatsapp requires plugin API >=2026.7.1
The current OpenClaw version was:
2026.5.28
Those plugins required:
>=2026.7.1
OpenClaw therefore skipped their discovery.
The system also reported that several plugins were not installed.
plugin not installed: qqbot
plugin not installed: discord
plugin not installed: whatsapp
plugin not installed: slack
plugin not installed: feishu
These warnings did not prevent DeepSeek authentication or the Workspace migration.
If those channels are not required immediately, upgrading OpenClaw solely to eliminate the warnings introduces unnecessary compatibility changes.
Feishu Was Left for Separate Configuration
Feishu required special handling during the migration.
The Windows environment used:
openclaw-lark
The migrated configuration also contained the Feishu channel.
However, openclaw doctor reported:
channels.feishu: channel is configured, but plugin "openclaw-lark"
is disabled by plugins.entries.openclaw-lark.enabled=false
It also reported:
plugins.entries.feishu: plugin not installed: feishu
An existing plugin project directory appeared under the Ubuntu OpenClaw npm projects directory:
larksuite-openclaw-lark-b3091cd05
Further inspection did not produce a stable path for that directory, so the migration process avoided guessing about the plugin package or installing a newer Feishu plugin.
The final decision was to leave Feishu outside the core migration and configure it separately later.
The migration therefore focused on:
DeepSeek Restored
Workspace Restored
WeChat Migrated
Feishu Configure separately
Other plugins Handle when required
This avoids introducing a potentially incompatible plugin into an OpenClaw 2026.5.28 environment.
The message Tool Was Disabled by the Coding Profile
The migrated configuration retained:
{
"tools": {
"profile": "coding"
}
}
During the doctor run, OpenClaw reported:
tool policy removed 5 tool(s) via tools.profile (coding):
agents_list, gateway, message, nodes, tts
The message tool is particularly relevant for channel integrations.
The doctor warning explained that the main agent was routed from:
feishu
openclaw-weixin
while the message tool was unavailable.
Some channel operations could therefore fail, including:
sendAttachment
upload-file
thread-reply
reply
This becomes relevant when Feishu or WeChat is brought back into active use.
The messaging tool allowlist should therefore be reviewed when those channels are configured.
Memory Search Was Not Restored Yet
The doctor also reported:
Memory search provider is set to "openai" but no API key was found.
OpenClaw suggested several possible approaches.
Configure the model credentials:
openclaw configure --section model
Set:
OPENAI_API_KEY
Or disable memory search through:
agents.defaults.memorySearch.enabled
The migration left this configuration unchanged.
The reason is that the warning concerns semantic memory search. DeepSeek model authentication was already working independently.
The migrated Workspace still contains:
MEMORY.md
so the underlying memory file itself was preserved.
A Large MEMORY.md Can Be Truncated During Bootstrap Injection
The doctor check found that the migrated MEMORY.md was relatively large.
The report showed:
MEMORY.md: 53,943 raw / 11,999 injected
The total bootstrap injection was:
39,787
characters, representing:
66% of max/total 60,000
This does not mean the original MEMORY.md was damaged.
It means OpenClaw applies an injection limit when loading Workspace bootstrap files into the agent context.
The doctor suggested adjusting:
agents.defaults.bootstrapMaxChars
if a larger amount of the file should be injected during startup.
This can be handled separately from the initial migration.
A Missing Session Transcript Was Detected
The doctor also reported:
1/1 recent sessions are missing transcripts
The main session transcript was missing at:
~/.openclaw/agents/main/sessions/bc8c4f19-c041-470e-8fb2-a23381ef9989.jsonl
As a result, the historical conversation associated with that session may appear to have reset.
OpenClaw provided a dry-run cleanup command:
openclaw sessions cleanup --store \
"/home/ubuntu/.openclaw/agents/main/sessions/sessions.json" \
--dry-run
It also provided a force cleanup command:
openclaw sessions cleanup --store \
"/home/ubuntu/.openclaw/agents/main/sessions/sessions.json" \
--enforce --fix-missing
The migration did not immediately run the force cleanup command.
The first priority was preserving the migrated environment. Session cleanup can be handled after the migration has been verified.
Review Gateway Security After the Migration
The doctor identified two security-related issues.
The first was plaintext secret-bearing configuration in openclaw.json.
The reported paths included:
gateway.auth.token
channels.feishu.appSecret
OpenClaw recommends migrating these values to SecretRefs and using:
openclaw secrets configure
or:
openclaw secrets apply
The resulting configuration can then be checked with:
openclaw secrets audit --check
The second issue concerned the Gateway network binding.
The current configuration uses:
bind = lan
which makes the Gateway network-accessible.
The migration retained this configuration because it was already part of the Ubuntu cloud-server setup:
port = 35395
bind = lan
basePath = /h5sswr
After the migration is stable, review the Gateway exposure, firewall rules, authentication credentials, and remote-access requirements.
Final OpenClaw Migration Status
After completing the migration steps, the core Ubuntu environment reached the following state.
| Component | Status |
|---|---|
| OpenClaw | 2026.5.28 |
| Workspace | /home/ubuntu/WorkSpace |
| Default model | deepseek/deepseek-v4-flash |
| DeepSeek API key | Configured |
| Auth store | ~/.openclaw/agents/main/agent/auth-profiles.json |
| WeChat account state | Migrated |
| Feishu | Deferred for separate configuration |
| Gateway systemd service | Installed |
| Gateway port | 35395 |
| Gateway binding | lan |
| Memory Search | Not restored |
| Newer incompatible plugins | Deferred |
The important part of this migration is the separation between application data and machine-specific configuration.
The Workspace can move from Windows to Linux. Model definitions can be merged. Authentication can be re-established through OpenClaw. Existing cloud Gateway and browser settings can remain on the server. Plugins can be restored according to their compatibility with the OpenClaw version actually running on the server.
OpenClaw Windows-to-Ubuntu Migration Checklist
Use the following sequence for a similar migration.
1. Verify the OpenClaw version
openclaw --version
For this migration:
2026.5.28
2. Back up the Ubuntu OpenClaw state
cp -a /home/ubuntu/.openclaw \
/home/ubuntu/.openclaw.before-migration
3. Migrate the Workspace separately
Windows:
D:\WorkSpace
Ubuntu:
/home/ubuntu/WorkSpace
4. Back up the Ubuntu configuration
cp /home/ubuntu/.openclaw/openclaw.json \
/home/ubuntu/.openclaw/openclaw.json.before-merge
5. Merge only the required configuration
Migrate the relevant sections for:
Workspace
Models
Providers
Authentication profiles
Plugins
Channels
Bindings
Commands
Session
Tools
6. Preserve the Ubuntu Gateway and browser configuration
Keep the existing server-specific:
port
bind
basePath
Control UI
browser
settings unless there is a specific reason to change them.
7. Check the model configuration
openclaw models status
8. Configure the DeepSeek API key
openclaw models auth login --provider deepseek
9. Verify DeepSeek authentication
openclaw models status
Look for:
api_key=1
10. Run the OpenClaw health check
openclaw doctor
11. Check the Gateway
openclaw gateway start
Then:
openclaw gateway status
12. Configure channels separately
The migration order used here was:
DeepSeek Restore first
Workspace Restore first
WeChat Preserve migrated state
Feishu Configure separately
Other plugins Add when actually required
Frequently Asked Questions
Can I copy the entire Windows .openclaw directory to Ubuntu?
A full directory replacement is risky because .openclaw contains Workspace data, agent state, npm projects, authentication data, plugins, and runtime information. Windows and Ubuntu also use different paths and server configurations.
Where should the OpenClaw Workspace be located on Ubuntu?
This migration uses:
/home/ubuntu/WorkSpace
The OpenClaw default Workspace configuration points to that directory.
Why did the DeepSeek API key require separate configuration?
The Windows authentication profile identified the DeepSeek provider and authentication method, while the actual API key was not found in the Windows credentials that were inspected.
The key was therefore entered on Ubuntu with:
openclaw models auth login --provider deepseek
What does api_key=1 mean in openclaw models status?
It indicates that OpenClaw found one API-key authentication profile in the Agent authentication store.
The model definition and API authentication are separate configuration layers.
Do Discord, QQBot, Slack, and WhatsApp plugin warnings need immediate action?
No, provided those channels are not currently required.
The installed OpenClaw version is 2026.5.28, while those plugin versions require a newer Plugin API. OpenClaw skips their discovery under the current version.
Why does Feishu appear in the configuration while the channel does not work?
The Feishu channel configuration and the Feishu plugin are separate components. The configuration was present, while OpenClaw reported that the required plugin was disabled or unavailable.
For this migration, Feishu was left for a separate configuration step.
Does the missing OpenAI API key prevent DeepSeek from working?
No. The warning concerns OpenClaw semantic memory search. The DeepSeek model has its own authentication profile and was successfully authenticated.
Why is MEMORY.md truncated after migration?
The file itself was migrated. OpenClaw limits how much Workspace bootstrap content is injected into the agent context.
The migrated file contained approximately 53,943 raw characters, while the doctor report showed approximately 11,999 characters being injected for that file.
The relevant configuration is:
agents.defaults.bootstrapMaxChars
