跳转到内容

OpenClaw

来自 Arch Linux 中文维基

相关文章

OpenClaw是奥地利程序员彼得·斯坦伯格开发的开源AI智能体，用户可以通过即时通讯工具与其对接，远程操控电脑实现自动化处理邮件、阅读文档、编写代码、发布社交媒体内容等工作。

安装

安装 openclawAUR 软件包。

配置

安装好 OpenClaw 之后，通过以下命令运行新手引导：

$ openclaw onboard --install-daemon

详细的配置方法详见官方文档。

为了使用 OpenClaw，你需要提前准备一个大模型的 API Key，一个 AI 搜索引擎的 API Key，以及一个即时通讯软件，并且你可能需要为大模型提供商进行适当充值。OpenClaw 兼容的大模型、AI搜索引擎和即时通讯软件会在新手引导中全部列出，如果你没有提前准备，在新手引导过程中选择并注册一个也是可以的。

配置完成后，运行

$ openclaw dashboard

即可在浏览器中打开控制 UI 。你也可以把该页面加入浏览器的书签，之后可以通过浏览器直接进入。

迁移

如果你重新安装了 Arch Linux，从其他发行版迁移到了 Arch Linux，从 Arch Linux 迁移到了其他发行版，更换了安装方式，或者更换了电脑，那么你都需要进行迁移工作。

首先，在迁移之前，在旧系统的终端运行：

$ openclaw gateway stop

停止 OpenClaw 网关运行，以防止迁移过程中数据发生改变。然后，备份家目录下的 .openclaw 目录。之后，在新系统上安装 OpenClaw。如果是同一系统，仅变更安装方式，需要删除旧的软件包以避免冲突。之后，将 .openclaw 目录复制到新系统的家目录。不必运行新手引导，而是直接运行：

$ openclaw doctor --fix

程序会自动修复配置文件，原来的数据都会保留，不需要重新配置。之后，在新系统的终端运行：

$ openclaw gateway restart

即可在新系统上使用 OpenClaw。

注意事项

数据安全

OpenClaw 需要系统级权限来执行任务，不当使用会造成数据泄露、误删除重要数据、感染病毒等多种风险。一些降低安全风险的方法包括：

  • 如果你有两台以上的电脑，专门用一台运行 OpenClaw，其他电脑存放重要数据。（物理隔离，最安全）
  • 使用沙盒运行 OpenClaw。如果你通过 openclawAUR 或 openclaw-gitAUR 安装了OpenClaw，则 bubblewrap 沙盒一般已作为依赖安装。
  • 在虚拟机中安装 OpenClaw。
  • 使用 Arch + Windows 双系统，将重要数据放在 Windows 一侧，并尽量不要直接挂载 Windows 所在分区。你甚至可以用 BitLocker 加密 Windows 所在分区以阻止 Arch Linux 挂载 Windows 所在分区。

注意：使用在 WSL 上安装的 Arch Linux 运行 OpenClaw 是不安全的。这是因为 WSL 会自动挂载 Windows 的所有磁盘，并且 WSL 上运行的程序对 Windows 的磁盘是完全可读可写的，有可能造成 Windows 上的重要数据被泄露或误删除。如果必须在 WSL 上运行 OpenClaw，可以考虑关闭 WSL 自动挂载。

更新须知

OpenClaw 正处在频繁的开发中，某些版本会修改一些文件导致旧版本配置不能正常使用。建议每次更新后都手动运行一次下列命令，以自动修复一些配置问题。

$ openclaw doctor --fix

旧版本的 OpenClaw 插件有可能和新版本的主程序不兼容，造成 OpenClaw 网关无法启动。运行：

$ openclaw plugins update --all

2026.8.1 版本须知

警告：从旧版本升级到 2026.8.1 后，网关可能无法启动。[1]该版本会执行一串一次性迁移，每一步都可能被旧版本遗留的文件卡住。升级前请完整备份 ~/.openclaw 目录。
迁移链条

如果升级后网关拒绝启动，并报出类似 "OpenClaw startup migrations did not complete cleanly; refusing to report the gateway ready" 的错误，请运行：

$ openclaw doctor --fix

如果 doctor 本身失败或卡住，以下遗留文件已知会卡住迁移链条。请将它们移走（不要删除），然后重新运行 openclaw doctor --fix：

  • ~/.openclaw/credentials/wecom-default-allowFrom.json — 企业微信通道的旧 allow-from 文件。default 后缀只能在内置通道中解析，外部插件通道永远无法解析，因此卸载企业微信插件也没有用（解析器只看文件名）。
  • ~/.openclaw/agents/main/sessions/sessions.json — 等待迁移的旧会话存储。
  • ~/.openclaw/exec-approvals.json — 一个迁移守卫，连 doctor 自己都会被它挡住。

例如：

$ 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
提示：在非交互场景（例如脚本）中使用时，运行 openclaw doctor --non-interactive 或 openclaw doctor --fix --yes 可跳过交互式确认步骤。
能力同意（capability consent）

2026.8.1 对全部插件强制执行能力同意检查，包括 deepseek、feishu 等内置插件。交互式安装向导（openclaw configure）在安装外部 npm 插件时可能卡在 "Linking" 步骤；这是安装后的 CLI 验证被缺少 consent 挡住，而不是网络问题。不要卸载重装，请改用以下方式在安装/启用时预先接受 consent：

$ openclaw plugins install <插件> --accept-capabilities
$ openclaw plugins enable <插件> --accept-capabilities

之后重启网关使更改生效：

$ openclaw gateway restart

自 2026.8.1 起，插件安装索引存储在 SQLite 状态数据库中（config_machine_state 表，state key 为 plugins.installedIndex），不再使用旧的 ~/.openclaw/plugins/installs.json；升级后旧的 JSON 目录可能已不存在。

stale 非权威 npm generation

在 2026.8.1 上升级后，可能会在 ~/.openclaw/npm/projects/ 下为外部插件（如 @openclaw/moonshot-provider）遗留一个重复的 npm 项目目录，例如：

  • openclaw-moonshot-provider-4617b6c201（原始权威项目）
  • openclaw-moonshot-provider-4617b6c201__openclaw-generation__g-<16 位十六进制>（升级遗留的重复目录）

openclaw doctor --fix 会为此情况报告 Managed npm plugin installs have stale non-authoritative generations。关键是：SQLite 安装索引（config_machine_state 中 state key 为 plugins.installedIndex）才是真相之源——其中的 installPath 字段、index.plugins[] 下的 manifestPath/source/rootDir 字段，以及 installRecords.<id>.installPath 字段，三者必须互相一致。

动任何东西之前，先检查索引实际指向哪里：

$ 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"])'
提示：这点非常反直觉：以 __openclaw-generation__g-* 结尾的目录不是 stale 的——它才是索引锁定的权威安装。stale 的是那个不带该后缀的目录。仅仅改名为 .bak 不够，必须彻底移出 npm/projects/ 扫描范围。

确认索引指向哪里，然后把另一个目录移出 npm/projects/（不要删除，保留备份）：

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

重新运行 doctor 确认 stale 警告消失：

$ openclaw doctor --non-interactive

已在两台独立的 2026.8.1 机器上验证过：stale non-authoritative generations 警告消失，plugins list 仍显示插件为启用状态。

警告：不要尝试通过把 generation 目录重命名为权威名并改写 SQLite 索引来"提升"它。这会破坏 openclaw configure，使其卡在"准备 99%"——比原本的症状更严重。如果你已经试过了，请从 ~/.openclaw/state/openclaw.sqlite.bak-* 备份和 ~/.openclaw/npm/stale-backups/ 快照恢复。

常见问题

openclawAUR 编译太慢了

openclawAUR 编译时使用 npm包，而 npm包 官方服务器在国外，国内访问延迟较大。改为使用国内 NPM 镜像可以大大增加下载速度：

$ npm config set registry https://registry.npmmirror.com #阿里云镜像

或

$ npm config set registry https://mirrors.cloud.tencent.com/npm/ #腾讯云镜像

或

$ npm config set registry https://mirrors.tuna.tsinghua.edu.cn/npm/ #清华大学镜像

Bash 找不到命令

重启系统即可解决。

在即时通讯软件上向 OpenClaw 发送消息没有反应

在控制页面让 OpenClaw 自己诊断并修复即可。

参见