OpenClaw从0到1安装搭建的保姆级教程
小吗喽233
前言
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 安装包，按默认流程安装即可。
安装完成后，在终端中验证：
node -v # 输出示例：v20.11.0 npm -v # 输出示例：10.2.4
只要能正常输出版本号，就可以继续安装 OpenClaw。
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\你的用户名\.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
}
]
}
}
}
}这里有两个原文档中特别提醒的点：
"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 令牌：
{
"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 是否正确。
如果返回：
Connection refused
检查 Gateway 服务是否还在运行，端口是否仍然是 18789。
总结
OpenClaw 的配置重点不在安装命令，而在 openclaw.json 和 auth-profiles.json 两个文件。前者决定 provider、模型和默认模型，后者决定每个 provider 使用哪一组 API Key。
按本文流程走完后，你应该能完成 OpenClaw 初始化、多模型 provider 配置、鉴权文件填写和 Gateway 验证。后续如果切换默认模型，优先改 "primary"；如果调用失败，优先检查 Key、Base URL 占位和 Gateway 服务状态。
以上就是OpenClaw从0到1安装搭建的保姆级教程的详细内容，更多关于OpenClaw安装搭建教程的资料请关注脚本之家其它相关文章！