跳至內容

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 自己診斷並修復即可。

參見