OpenClaw

This article or section needs language, wiki syntax or style improvements. See Help:Style for reference.

Reason: Structure does not follow Help:Style#Layout, headings have links/templates. (Discuss in Talk:OpenClaw)

OpenClaw is an open-source AI agent developed by Peter Steinberger, an Austrian programmer. Users can connect with it through instant messaging tools and remotely control their computers to automate tasks such as email processing, document reading, coding, and posting social media content.

Installation

Install the openclaw^AUR package.

Configuration

After installing OpenClaw, run the beginner's guide using the following command:

$ openclaw onboard --install-daemon

For detailed configuration methods, please refer to the official document.

In order to use OpenClaw, you need to prepare a large model API Key, an AI search engine API Key, and an instant messaging software in advance, and you may need to make appropriate deposits for the large model provider. OpenClaw compatible large models, AI search engines, and instant messaging software will all be listed in the beginner's guide. If you have not prepared in advance, you can also choose and register one during the beginner's guide process.

After the configuration, run

$ openclaw dashboard

to open the control UI in your browser. You can also bookmark the page in your browser and access it directly through the browser.

Migration

If you reinstall Arch Linux, migrate from other distributions to Arch Linux, migrate from Arch Linux to other distributions, change installation methods, or change computers, then you will need to perform migration work.

First, before the migration, run in the terminal of the old system:

$ openclaw gateway stop

Stop the OpenClaw gateway from running to prevent data changes during the migration process. Then, backup the .openclaw directory in the home directory. Afterwards, install OpenClaw on the new system. If it is the same system, only changing the installation method requires deleting old software packages to avoid conflicts. Afterwards, copy the .openclaw directory to the home directory of the new system. There is no need to run a beginner's guide, but simply run:

$ openclaw doctor --fix

The program will automatically repair the configuration file, and the original data will be retained without the need for reconfiguration. Then, run in the terminal of the new system:

$ openclaw gateway restart

Then you can use OpenClaw on the new system.

Note

Data Safety

OpenClaw requires system level permissions to perform tasks, and improper use can lead to various risks such as data leakage, accidental deletion of important data, and virus infection. Some methods to reduce security risks include:

If you have two or more computers, use one specifically to run OpenClaw while the other computer stores important data. (Physical isolation, safest)
Run OpenClaw in a sandbox. If you installed OpenClaw via openclaw^AUR or openclaw-git^AUR, then bubblewrap sandbox is installed as a dependency.
Install OpenClaw in a Virtual Machine.
Using Arch and Windows dual system, placing important data in Windows, and not to directly mount the partition where Windows is located. You can even use BitLocker to encrypt the partition where Windows is located to prevent Arch Linux from mounting the partition.

Note: It is unsafe to run OpenClaw on Arch Linux installed on WSL. This is because WSL automatically mounts all Windows disks, and programs running on WSL have full read and write access to Windows disks, potentially leading to the leakage or accidental deletion of important data on Windows. If you must run OpenClaw on WSL, consider disabling WSL's automatic mounting.

Updating Notice

The old version of the OpenClaw plugin may be incompatible with the new version of the main program, causing the OpenClaw gateway to fail to start. Run:

$ openclaw plugins update --all

OpenClaw is under frequent development, some updates may modify certain files, causing existing configurations to malfunction. It is recommended to manually run the command after each update:

$ openclaw doctor --fix

Thus, it can automatically resolve some configuration issues.

Version 2026.8.1

Warning Upgrading to 2026.8.1 from an older version can leave the gateway unable to start.[1] The release runs a chain of one-time migrations, and each step can be blocked by leftover files from previous versions. Back up the entire ~/.openclaw directory before upgrading.

Migration chain

If the gateway refuses to start after the upgrade and reports something like "OpenClaw startup migrations did not complete cleanly; refusing to report the gateway ready", run:

$ openclaw doctor --fix

If doctor itself fails or hangs, the following leftover files are known to stall the migration chain. Move them aside instead of deleting them, then run openclaw doctor --fix again:

~/.openclaw/credentials/wecom-default-allowFrom.json — legacy allow-from file for the WeCom channel. The default suffix can only be resolved for built-in channels; for external plugin channels it is always unresolved, so uninstalling the WeCom plugin does not help (the resolver only inspects the file name).
~/.openclaw/agents/main/sessions/sessions.json — legacy session store awaiting migration.
~/.openclaw/exec-approvals.json — a migration guard that can block doctor itself.

Example:

$ mv ~/.openclaw/credentials/wecom-default-allowFrom.json ~/.openclaw/credentials/wecom-default-allowFrom.json.bak
$ mv ~/.openclaw/exec-approvals.json ~/.openclaw/exec-approvals.json.bak
$ openclaw doctor --fix

Tip For non-interactive use, e.g. in scripts, run openclaw doctor --non-interactive or openclaw doctor --fix --yes to skip interactive confirmation prompts.

Capability consent

2026.8.1 enforces a capability consent check for all plugins, including built-in ones such as deepseek and feishu. The interactive installer (openclaw configure) can appear stuck at the "Linking" step when installing external npm plugins; this is the post-install CLI verification being blocked by the missing consent, not a network problem. Do not uninstall and reinstall — install or enable plugins with consent pre-accepted instead:

$ openclaw plugins install <plugin> --accept-capabilities
$ openclaw plugins enable <plugin> --accept-capabilities

Restart the gateway afterwards to apply the changes:

$ openclaw gateway restart

Since 2026.8.1, the plugin install index is stored in the SQLite state database (config_machine_state table, state key plugins.installedIndex) instead of the legacy ~/.openclaw/plugins/installs.json; the legacy JSON directory may no longer exist after the upgrade.

Stale non-authoritative npm generations

On 2026.8.1, the upgrade may leave a duplicate npm project directory under ~/.openclaw/npm/projects/ for external plugins such as @openclaw/moonshot-provider, e.g.:

openclaw-moonshot-provider-4617b6c201 (the original authoritative project)
openclaw-moonshot-provider-4617b6c201__openclaw-generation__g-<16 hex chars> (a duplicate left by the upgrade)

openclaw doctor --fix reports Managed npm plugin installs have stale non-authoritative generations for this condition. Crucially, the SQLite install index (config_machine_state with state key plugins.installedIndex) is the source of truth: its installPath field, the manifestPath/source/rootDir fields under index.plugins[], and the installRecords.<id>.installPath field must all be consistent with each other.

Check which path the index actually points at before touching anything. To inspect the index:

$ sqlite3 ~/.openclaw/state/openclaw.sqlite \
   "SELECT value_json FROM config_machine_state WHERE state_key='plugins.installedIndex'" \
   | python3 -c 'import json,sys; d=json.loads(sys.stdin.read()); print(d["index"]["installRecords"]["moonshot"]["installPath"])'

Tip This is counterintuitive: the directory ending in __openclaw-generation__g-* is not the stale one — it is the authoritative install the index locks onto. The stale directory is the one without that suffix. Renaming it to .bak is not enough — it must be moved out of the npm/projects/ scan range entirely.

Confirm what the index points at, then move the other directory out of npm/projects/ (do not delete it; keep a backup):

$ mkdir -p ~/.openclaw/npm/stale-backups
$ mv ~/.openclaw/npm/projects/openclaw-moonshot-provider-4617b6c201 ~/.openclaw/npm/stale-backups/

Re-run doctor to confirm the stale warning is gone:

$ openclaw doctor --non-interactive

This was verified on two independent machines running 2026.8.1; the stale non-authoritative generations warning disappears and plugins list continues to show the plugin as enabled.

Warning Do not try to "promote" the generation directory by renaming it to the authoritative name and rewriting the SQLite index. That breaks openclaw configure, which then hangs at "preparing 99%" — a more severe symptom than the one you started with. Restore from the ~/.openclaw/state/openclaw.sqlite.bak-* backup and ~/.openclaw/npm/stale-backups/ snapshot if you already tried this.

Kimi / Moonshot configure loop (no clean workaround yet)

Even after retiring the stale generation as described above, openclaw configure may still enter an install loop: selecting Moonshot shows the "install plugin" prompt, after install it does not advance to the model picker (K3 / K2.7 / K2.6 etc.), and falls back to the provider picker. Picking Moonshot again repeats the loop. This was reproduced on two independent 2026.8.1 installations; the root cause is not in stale generations (those are already gone) and appears to be an upstream bug.

Workaround for the bug: use the model directly without going through configure. 2026.8.1's built-in model catalog already lists moonshot/kimi-k3, moonshot/kimi-k2.7-code, moonshot/kimi-k2.6 etc. Switch with:

$ openclaw models set moonshot/kimi-k3
$ openclaw gateway restart

Then start a fresh conversation and use /model moonshot/kimi-k3 to switch per-session. The plugin, all models, and normal operation continue to work; only the interactive configure wizard is affected.

The Kimi K2 series models and the Moonshot provider itself are working normally — this bug is purely cosmetic in the interactive installer and does not block any model from being used.