OpenClaw 的安装命令并不复杂，真正容易卡住的是初始化之后的模型 provider、鉴权 profile、workspace 路径和 Gateway 验证。尤其是同时接入 Claude、GPT、Gemini、DeepSeek 这类多模型时，一个字段写错就可能导致后面无法调用。
这篇文章按原始文档把 OpenClaw 从 Node.js 准备、安装初始化、主配置文件修改、API Key 填写到最终启动验证完整梳理一遍。直接跟着操作就好。
正文
1. 安装 Node.js
开始之前，先确认本地已经安装 Node.js 18 以上版本。原文档建议使用 LTS 版本，例如 20.x LTS。
如果还没有安装，可以访问 Node.js 官网下载 LTS 安装包，按默认流程安装即可。
安装完成后，在终端中验证：
|
1 2 3 4 |
node -v # 输出示例：v20.11.0 npm -v # 输出示例：10.2.4 |
只要能正常输出版本号，就可以继续安装 OpenClaw。
2. 安装 OpenClaw 并初始化
第一步：安装 OpenClaw
确保 Node.js 已经准备好，然后执行全局安装：
|
1 |
npm install -g openclaw@latest |
接着执行引导初始化：
|
1 |
openclaw onboard |
完成后，终端会输出版本号和初始化成功提示。
如果出现 command not found，优先检查：
- Node.js 是否正确安装
- npm 全局路径是否已经加入 PATH
初始化完成后，OpenClaw 的基础骨架就搭好了，下一步开始配置模型。
3. 修改主配置文件openclaw.json
找到 OpenClaw 主配置文件：
- Windows：C:\Users\你的用户名\.openclaw\openclaw.json
- Mac / Linux：~/.openclaw/openclaw.json
按照原文档，把 models 和 auth 部分替换为下面这份配置：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 |
{ "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密钥，本次实操使用88api中转服务（官网：https://api.88api.shop），推荐大家可以试试，或者大家也可以用自己的。
具体步骤：
- 注册登录以后，点击侧边栏的 “API 令牌”
- 点击"添加令牌"
- 创建令牌，名称随意，直接提交
- 获取 API Key，注意妥善保管，不要公开或分享。
- 点击"知道了"，在令牌列表中可以点击"复制"按钮获取 API Key
4.2 找到鉴权文件
文件路径如下：
- Windows：C:\Users\你的用户名\.openclaw\agents\main\agent\auth-profiles.json
- Mac / Linux：~/.openclaw/agents/main/agent/auth-profiles.json
填入 API 令牌：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
{ "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 服务
执行：
|
1 |
openclaw gateway --port 18789 |
如果终端输出类似下面的信息，说明服务已经起来：
|
1 |
Gateway running on http://127.0.0.1:18789 |
5.2 打开控制台
浏览器访问：
|
1 |
http://127.0.0.1:18789/ |
正常情况下可以看到 OpenClaw 的 Web 界面。
5.3 测试连通性
在对话框里随便问一句，比如：
|
1 |
你是谁 |
如果 AI 正常回复，说明 Claude 已经通过这套 API 配置接入成功。
5.4 常见错误
如果返回：
|
1 |
401 Unauthorized |
优先检查 auth-profiles.json 里的 Key 是否正确。
如果返回：
|
1 |
Connection refused |
检查 Gateway 服务是否还在运行，端口是否仍然是 18789。
总结
OpenClaw 的配置重点不在安装命令，而在 openclaw.json 和 auth-profiles.json 两个文件。前者决定 provider、模型和默认模型，后者决定每个 provider 使用哪一组 API Key。
按本文流程走完后，你应该能完成 OpenClaw 初始化、多模型 provider 配置、鉴权文件填写和 Gateway 验证。后续如果切换默认模型，优先改 "primary"；如果调用失败，优先检查 Key、Base URL 占位和 Gateway 服务状态。
