最新OpenClaw安装搭建保姆级教程：从零开始一步步手把手超级完整版

2026-06-18阅读 0热度 0

OpenClaw

为什么必须先搞明白这些配置

坦白讲，OpenClaw 的安装命令本身毫无难点，真正令人抓狂的是初始化后那一系列配置细节：模型 provider 如何正确映射、鉴权 profile 该怎么写、workspace 路径设在哪里、Gateway 能否正常启动。尤其是当你需要同时接入 Claude、GPT、Gemini 和 DeepSeek 四个模型时，一个字段填错，后面就只能看着调用失败干瞪眼。

本文直接按官方文档顺序，将 Node.js 环境准备、安装初始化、主配置文件修改、API Key 填写、启动验证的完整流程逐一拆解，跟着操作就好，不用纠结。

详细配置步骤

1. 准备 Node.js 环境

开始前务必确认本地已安装 Node.js，版本不低于 18。官方文档明确推荐使用 LTS 版本，例如 20.x LTS，稳定性最高。

若未安装，前往 Node.js 官网下载 LTS 安装包，一路默认即可。

安装完成后在终端验证：

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

显示版本号说明环境就绪，可以继续下一步。

2. 安装 OpenClaw 并初始化

第一步：安装 OpenClaw

Node.js 就绪后，执行全局安装：

npm install -g openclaw@latest

然后运行引导初始化：

openclaw onboard

顺利完成后终端会输出版本号和初始化成功提示。

若遇到 command not found，先排查两点：Node.js 是否正确安装；npm 全局路径是否已加入 PATH。

初始化完成后 OpenClaw 的基础框架就已搭建完毕，接下来配置模型部分。

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

找到 OpenClaw 的主配置文件：

Windows：C:Users你的用户名.openclawopenclaw.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
          }
        ]
      }
    }
  }
}

官方文档强调两个易错点：

"primary" 决定默认模型，若想默认使用 GPT-5.2，改为 "primary": "api-proxy-gpt/gpt-5.2"
Mac 用户须将 workspace 改为自己的工作目录，例如 "/Users/你的用户名/clawd"

4. 配置鉴权文件 auth-profiles.json

4.1 获取 API Key

需要 API 密钥，可通过 API 中转服务获取。以下为某中转平台的具体操作：

注册登录后，点击侧边栏的 “API 令牌”

点击"添加令牌"

创建令牌，名称任意，直接提交

获取 API Key，务必妥善保管，禁止公开或分享。

点击"知道了"，在令牌列表中点"复制"按钮获取 API Key

4.2 定位鉴权文件

文件路径如下：

Windows：C:Users你的用户名.openclawagentsmainagentauth-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 服务

执行：

openclaw gateway --port 18789

若终端输出类似以下信息，说明服务已正常启动：

Gateway running on http://127.0.0.1:18789

5.2 打开控制台

浏览器访问：

http://127.0.0.1:18789/

正常情况下即可看到 OpenClaw 的 Web 界面。

5.3 测试连通性

在对话框中随便问一句，例如：

你是谁

若 AI 正常回复，说明 Claude 已通过此 API 配置成功接入。

5.4 常见错误排查

若返回：

401 Unauthorized

优先检查 auth-profiles.json 中的 Key 是否填写正确。