外掛安裝覆寫

外掛安裝覆寫可讓維護者在設定期間，將外掛安裝指向 特定的 npm 套件或本機 npm-pack tarball，而非目錄、 內建或預設的 npm 來源。此功能僅供 E2E 與套件驗證使用； 一般使用者請透過 openclaw plugins install 安裝外掛。

覆寫會執行你所提供來源中的外掛程式碼。請僅在隔離的 狀態目錄或可拋棄的測試機器中使用。

​

環境

除非同時設定以下兩個變數，否則覆寫功能會停用：

export OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1
export OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{
  "codex": "npm-pack:/tmp/openclaw-codex-2026.5.8.tgz",
  "openclaw-web-search": "npm:@openclaw/web-search@2026.5.8"
}'

覆寫對應表是以外掛 ID 為鍵的 JSON。值支援：

前綴	來源
npm:<registry-spec>	登錄檔套件、確切版本或標籤
npm-pack:<path.tgz>	由 npm pack 產生的本機 tarball；相對路徑會從目前工作目錄解析

​

行為

當設定期間的流程安裝其 ID 出現在對應表中的外掛時，OpenClaw 會使用覆寫來源，而非目錄、內建或預設的 npm 來源。這適用於新手引導，以及使用共用設定期間外掛安裝程式的任何其他流程。

• 覆寫仍會強制要求預期的外掛 ID：對應至 codex 的 tarball 必須安裝資訊清單 ID 為 codex 的外掛。
• 覆寫不會繼承官方可信任來源的狀態。即使 目錄項目通常代表 OpenClaw 擁有的套件，覆寫仍會 視為由操作者提供的測試輸入。
• 工作區的 .env 檔案無法啟用安裝覆寫；這兩個環境變數均列於 工作區 dotenv 封鎖清單中。請在啟動 OpenClaw 的可信任 shell、CI 工作或 遠端測試命令中設定它們。

​

套件 E2E

使用隔離的狀態目錄，以免套件安裝與安裝記錄 影響你一般使用的 OpenClaw 狀態：

npm pack extensions/codex --pack-destination /tmp

OPENCLAW_STATE_DIR="$(mktemp -d)" \
OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1 \
OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{"codex":"npm-pack:/tmp/openclaw-codex-2026.5.8.tgz"}' \
pnpm openclaw onboard --mode local

驗證狀態目錄下已安裝的套件：

find "$OPENCLAW_STATE_DIR/npm/projects" -path '*/node_modules/@openclaw/codex/package.json' -print
grep -R '"@openclaw/codex"' "$OPENCLAW_STATE_DIR/npm/projects"/*/package-lock.json

若要進行即時供應商 E2E，請先從可信任的 shell 或 CI 密鑰載入真正的 API 金鑰，再啟動測試命令。請勿列印金鑰；僅回報 來源以及金鑰是否存在。