OpenClaw从0到1安装搭建的保姆级教程

发布时间：2026-06-17 16:24:59 作者：小吗喽233

OpenClaw 的安装命令并不复杂，真正容易卡住的是初始化之后的模型 provider、鉴权 profile、workspace 路径和 Gateway 验证,这篇文章按原始文档把 OpenClaw 从 Node.js 准备、安装初始化、主配置文件修改、API Key 填写到最终启动验证完整梳理一遍

前言

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 令牌”

4.1 获取 API Key

点击"添加令牌"

4.1 获取 API Key_图2

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

4.1 获取 API Key_图3

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

4.1 获取 API Key_图4

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

4.1 获取 API Key_图5

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安装搭建教程的资料请关注脚本之家其它相关文章！

Tag：OpenClaw 安装搭建

OpenClaw龙虾安装部署全流程:手把手教你搭建自己的AI助手
OpenClaw 是一个自托管的 AI 网关，它可以把你常用的聊天软件（微信、Telegram、Discord、iMessage…）和一个 AI 助手连接起来,下面小编就和大家详细讲讲如何正确安装部署O
2026-03-16
OpenClaw Skills 进阶实战指南(前端开发者的AI技能库搭建)
本文详细介绍了如何配置和使用OpenClaw的技能插件,特别是针对前端开发场景,它提供了按需构建技能的选择策略、多种安装技能的方法,以及2026年最受欢迎的OpenClaw技能推荐,此
2026-03-11
Ubuntu系统上快速部署OpenClaw的完整教程
OpenClaw（社区俗称“小龙虾”）是一款本地优先、开源、跨平台的 AI 智能体执行框架，由奥地利开发者 Peter Steinberger 于 2025 年发布，采用 MIT 开源协议，下面小编就和
2026-06-14
OpenClaw安装openclaw-dashboard监控面板
本文介绍了OpenClaw Dashboard的安装和使用方法,通过conda激活环境后，可通过一行命令快速安装,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习
2026-06-10
Windows 11操作系统安装OpenClaw的完整教程
OpenClaw是一款开源AI执行框架,支持多渠道通信、文件管理、任务自动化等功能,本文详细介绍了其安装步骤,包括环境准备、安装方式及常见问题解决方法,并附带安装验证与测试方
2026-05-27
Windows下OpenClaw安装对接ollama的GLM-4.7-Flash模型
本文介绍了在GPU平台上自动化部署ollama中GLM-4.7-Flash镜像，实现高效AI自动化办公,该轻量级模型特别适合Windows用户处理本地文件整理、数据收集等重复性任务，具有一定的
2026-05-25
OpenClaw安装与配置指南之如何使用自定义模型提供商
OpenClaw 是 2026 年初爆火的开源本地 AI 智能体框架，这篇文章主要为大家详细介绍了OpenClaw安装与配置指南，以及如何使用自定义模型提供商，有需要的小伙伴可以参考一下
2026-05-22
OpenClaw Skills 安装与配置指南
本文介绍了OpenClawSkills的概念、获取途径、安装方式、推荐Skills及配置方法,通过ClawHub官网、GitHub仓库等获取Skills,使用ClawHubCLI或OpenClawCLI安装,文章还提供了安
2026-05-18
OpenClaw实操指南之6个最值得优先安装的基础元技能Skill
本文介绍了OpenClaw系统中6个最值得优先安装的基础元技能，这些技能专注于管理和扩展OpenClaw本身的功能,包括find-skills，skill-creator，mcp-builder，skill-vetter，web
2026-05-14
openclaw安装memos-local-openclaw-plugin详细步骤及常见问题
memos-local-openclaw-plugin是给OpenClaw AI框架用的本地持久记忆插件,简单说让你的AI助手长期记住聊天内容,数据全存在你电脑本地,不上云,这篇文章主要介绍了openclaw安装
2026-05-14