OpenClaw從0到1安裝搭建的保姆級教程

發(fā)布時間：2026-06-17 16:24:59 作者：小嗎嘍233

OpenClaw 的安裝命令并不復(fù)雜，真正容易卡住的是初始化之后的模型 provider、鑒權(quán) profile、workspace 路徑和 Gateway 驗證,這篇文章按原始文檔把 OpenClaw 從 Node.js 準(zhǔn)備、安裝初始化、主配置文件修改、API Key 填寫到最終啟動驗證完整梳理一遍

前言

OpenClaw 的安裝命令并不復(fù)雜，真正容易卡住的是初始化之后的模型 provider、鑒權(quán) profile、workspace 路徑和 Gateway 驗證。尤其是同時接入 Claude、GPT、Gemini、DeepSeek 這類多模型時，一個字段寫錯就可能導(dǎo)致后面無法調(diào)用。

這篇文章按原始文檔把 OpenClaw 從 Node.js 準(zhǔn)備、安裝初始化、主配置文件修改、API Key 填寫到最終啟動驗證完整梳理一遍。直接跟著操作就好。

正文

1. 安裝 Node.js

開始之前，先確認(rèn)本地已經(jīng)安裝 Node.js 18 以上版本。原文檔建議使用 LTS 版本，例如 20.x LTS。

如果還沒有安裝，可以訪問 Node.js 官網(wǎng)下載 LTS 安裝包，按默認(rèn)流程安裝即可。

安裝完成后，在終端中驗證：

node -v
# 輸出示例：v20.11.0
npm -v
# 輸出示例：10.2.4

只要能正常輸出版本號，就可以繼續(xù)安裝 OpenClaw。

2. 安裝 OpenClaw 并初始化

第一步：安裝 OpenClaw

確保 Node.js 已經(jīng)準(zhǔn)備好，然后執(zhí)行全局安裝：

npm install -g openclaw@latest

接著執(zhí)行引導(dǎo)初始化：

openclaw onboard

完成后，終端會輸出版本號和初始化成功提示。

如果出現(xiàn) command not found，優(yōu)先檢查：

Node.js 是否正確安裝
npm 全局路徑是否已經(jīng)加入 PATH

初始化完成后，OpenClaw 的基礎(chǔ)骨架就搭好了，下一步開始配置模型。

3. 修改主配置文件openclaw.json

找到 OpenClaw 主配置文件：

Windows：C:\Users\你的用戶名\.openclaw\openclaw.json
Mac / Linux：~/.openclaw/openclaw.json

按照原文檔，把 models 和 auth 部分替換為下面這份配置：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "api-proxy-claude/claude-sonnet-4-5-20250929"
      },
      "models": {
        "api-proxy-gpt/gpt-5.2": {
          "alias": "GPT-5.2"
        },
        "api-proxy-claude/claude-sonnet-4-5-20250929": {
          "alias": "Claude Sonnet 4.5"
        },
        "api-proxy-google/gemini-3-pro-preview": {
          "alias": "Gemini 3 Pro"
        },
        "api-proxy-deepseek/deepseek-v3.2": {
          "alias": "Deepseek v3.2"
        }
      },
      "workspace": "C:\\Users\\admin\\clawd",
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "auth": {
    "profiles": {
      "api-proxy-gpt:default": {
        "provider": "api-proxy-gpt",
        "mode": "api_key"
      },
      "api-proxy-claude:default": {
        "provider": "api-proxy-claude",
        "mode": "api_key"
      },
      "api-proxy-google:default": {
        "provider": "api-proxy-google",
        "mode": "api_key"
      },
      "api-proxy-deepseek:default": {
        "provider": "api-proxy-deepseek",
        "mode": "api_key"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "api-proxy-gpt": {
        "baseUrl": "你的 88API Base URL/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5.2",
            "name": "GPT-5.2",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      },
      "api-proxy-claude": {
        "baseUrl": "你的 88API Base URL",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      },
      "api-proxy-google": {
        "baseUrl": "你的 88API Base URL/v1",
        "api": "google-generative-ai",
        "models": [
          {
            "id": "gemini-3-pro-preview",
            "name": "Gemini 3 Pro",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 2000000,
            "maxTokens": 8192
          }
        ]
      },
      "api-proxy-deepseek": {
        "baseUrl": "你的 88API Base URL/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-v3.2",
            "name": "Deepseek v3.2",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 2000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

這里有兩個原文檔中特別提醒的點(diǎn)：

"primary" 決定默認(rèn)模型，如果想默認(rèn)用 GPT-5.2，可以改成 "primary": "api-proxy-gpt/gpt-5.2"
Mac 用戶需要把 workspace 改成自己的工作目錄，例如 "/Users/你的用戶名/clawd"

4. 配置鑒權(quán)文件auth-profiles.json

4.1 獲取 API Key

需要API密鑰，本次實操使用88api中轉(zhuǎn)服務(wù)（官網(wǎng)：https://api.88api.shop），推薦大家可以試試，或者大家也可以用自己的。

具體步驟：

注冊登錄以后，點(diǎn)擊側(cè)邊欄的 “API 令牌”

4.1 獲取 API Key

點(diǎn)擊"添加令牌"

4.1 獲取 API Key_圖2

創(chuàng)建令牌，名稱隨意，直接提交

4.1 獲取 API Key_圖3

獲取 API Key，注意妥善保管，不要公開或分享。

4.1 獲取 API Key_圖4

點(diǎn)擊"知道了"，在令牌列表中可以點(diǎn)擊"復(fù)制"按鈕獲取 API Key

4.1 獲取 API Key_圖5

4.2 找到鑒權(quán)文件

文件路徑如下：

Windows：C:\Users\你的用戶名\.openclaw\agents\main\agent\auth-profiles.json
Mac / Linux：~/.openclaw/agents/main/agent/auth-profiles.json

填入 API 令牌：

{
  "version": 1,
  "profiles": {
    "api-proxy-gpt:default": {
      "type": "api_key",
      "provider": "api-proxy-gpt",
      "key": "sk-your-unique-gpt-key-here"
    },
    "api-proxy-claude:default": {
      "type": "api_key",
      "provider": "api-proxy-claude",
      "key": "sk-your-unique-claude-key-here"
    },
    "api-proxy-google:default": {
      "type": "api_key",
      "provider": "api-proxy-google",
      "key": "sk-your-unique-google-key-here"
    },
    "api-proxy-deepseek:default": {
      "type": "api_key",
      "provider": "api-proxy-deepseek",
      "key": "sk-your-unique-deepseek-key-here"
    }
  }
}

如果你只使用 Claude，只填 api-proxy-claude:default 這一項也可以，其他項可以先留空。

5. 啟動并驗證

5.1 啟動 Gateway 服務(wù)

執(zhí)行：

openclaw gateway --port 18789

如果終端輸出類似下面的信息，說明服務(wù)已經(jīng)起來：

Gateway running on http://127.0.0.1:18789

5.2 打開控制臺

瀏覽器訪問：

http://127.0.0.1:18789/

正常情況下可以看到 OpenClaw 的 Web 界面。

5.3 測試連通性

在對話框里隨便問一句，比如：

你是誰

如果 AI 正常回復(fù)，說明 Claude 已經(jīng)通過這套 API 配置接入成功。

5.4 常見錯誤

如果返回：

401 Unauthorized

優(yōu)先檢查 auth-profiles.json 里的 Key 是否正確。

如果返回：

Connection refused

檢查 Gateway 服務(wù)是否還在運(yùn)行，端口是否仍然是 18789。

總結(jié)

OpenClaw 的配置重點(diǎn)不在安裝命令，而在 openclaw.json 和 auth-profiles.json 兩個文件。前者決定 provider、模型和默認(rèn)模型，后者決定每個 provider 使用哪一組 API Key。

按本文流程走完后，你應(yīng)該能完成 OpenClaw 初始化、多模型 provider 配置、鑒權(quán)文件填寫和 Gateway 驗證。后續(xù)如果切換默認(rèn)模型，優(yōu)先改 "primary"；如果調(diào)用失敗，優(yōu)先檢查 Key、Base URL 占位和 Gateway 服務(wù)狀態(tài)。

以上就是OpenClaw從0到1安裝搭建的保姆級教程的詳細(xì)內(nèi)容，更多關(guān)于OpenClaw安裝搭建教程的資料請關(guān)注腳本之家其它相關(guān)文章！