OpenClaw新手搭建指南｜一步API打通全大模型，告别连接失败（附避坑清单）

一步API
0 阅读5分钟

最近被OpenClaw圈粉了——一款能让AI24小时接管电脑的开源工具，不用复杂编程，像聊天一样发指令，就能让它帮你操作文件、运行脚本、写代码、查邮件，堪称开发者和打工人的效率神器。

很多朋友私信问我，OpenClaw怎么安装？一步API怎么配置？为什么自己装完总是连接失败？

今天就整理一篇超详细的新手教程，全程手把手拆解，从前置准备到安装配置，再到常见问题排查，帮大家零门槛搞定OpenClaw搭建，少走弯路。

一、先搞懂：OpenClaw到底是什么？

简单说，OpenClaw就是你的“AI贾维斯”，核心优势有两个：

  • 「聊天式操控」：通过Telegram、飞书等聊天工具发指令，AI就能接管电脑，不用打开复杂软件；

  • 「全模型适配」：借助一步API，不用单独申请各个大模型的密钥，就能对接GPT、Claude、Gemini等国内外模型。

补充两个新手容易混淆的点：

  1. OpenClaw的名称演变：从Clawdbot（因和Claude重名被迫更名）→ Moltbot（辨识度低）→ 最终定名OpenClaw；

  2. 核心概念区分：OpenClaw是核心框架（类似手机），Skill是功能插件（类似APP），Prompt是你的指令（类似操作命令）。

官方资源（建议收藏）：

yibu2222.png

二、前置准备（必做，否则安装必失败）

这一步是基础，新手一定要仔细核对，避免白忙活。

1. 系统要求

  • 推荐：macOS、Linux（Ubuntu/CentOS），兼容性最好；

  • Windows用户：必须用WSL2（Windows子系统），直接在Windows原生环境安装会报错（附WSL2安装链接：微软官方教程，简单几步就能装）。

2. 环境要求

Node.js版本≥22.0.0（低于这个版本会导致安装失败），检查版本命令：node -v。

如果版本过低，用nvm升级（Linux/macOS直接执行，Windows在WSL2中执行）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

3. 核心准备：一步API Key

OpenClaw本身不提供大模型服务，需要通过一步API对接，步骤很简单：

  1. 登录一步API官网，注册并完成实名认证（免费额度足够新手使用）；

  2. 进入“API密钥”页面，创建并复制密钥（格式为sk-xxxxxx），保存好，后续会用到。

三、全程实操：OpenClaw安装+一步API配置（新手可直接复制指令）

所有操作都在终端完成，指令直接复制粘贴即可，不用手动输入，避免输错。

步骤1：安装OpenClaw核心程序

npm install -g openclaw@latest

安装完成后，执行openclaw -v，能显示版本号就是安装成功。如果提示权限不足，前面加sudo（Linux/macOS）。

步骤2：运行初始化向导（关键步骤）

openclaw onboard --install-daemon

执行后进入交互式界面，按以下指引操作，不要选默认：

  1. 选择模型提供商：根据你对接的大模型选择（如OpenAI、智谱），别直接回车；

  2. 输入一步API Key：粘贴之前保存的sk-xxxxxx，回车即可；

  3. Skill管理器安装：输入“Skip for now”（后续再装，避免出错）；

  4. 聊天平台连接：输入“Skip for now”（新手先用水印版，更简单）。

步骤3：修改配置文件（解决连接失败问题）

这是新手最容易卡壳的地方，也是确保AI能正常调用的关键，两步搞定：

1. 修改主配置文件（openclaw.json）

路径：Linux/macOS（/.openclaw/openclaw.json）、Windows WSL2（/.openclaw/openclaw.json）。

先记住文件中“workspace”的值，再将文件中的agents、auth、models节点，替换为以下内容（适配一步API）：

{
  "agents": {
    "defaults": {
      "workspace": "~/clawd", // 替换成你本地的workspace路径
      "models": {
        "api-proxy-gpt/gpt-4o": { "alias": "GPT-4o" },
        "api-proxy-claude/claude-sonnet-4-5-20250929": { "alias": "Claude Sonnet 4.5" },
        "api-proxy-google/gemini-3-pro-preview": { "alias": "Gemini 3 Pro" }
      },
      "model": {
        "primary": "api-proxy-claude/claude-sonnet-4-5-20250929"
      }
    }
  },
  "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" }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "api-proxy-gpt": {
        "baseUrl": "https://yibuapi.com/v1",
        "api": "openai-completions",
        "models": [{"id": "gpt-4o", "name": "GPT-4o", "contextWindow": 128000, "maxTokens": 8192}]
      },
      "api-proxy-claude": {
        "baseUrl": "https://yibuapi.com",
        "api": "anthropic-messages",
        "models": [{"id": "claude-sonnet-4-5-20250929", "name": "Claude Sonnet 4.5", "contextWindow": 200000, "maxTokens": 8192}]
      },
      "api-proxy-google": {
        "baseUrl": "https://yibuapi.com/v1beta",
        "api": "google-generative-ai",
        "models": [{"id": "gemini-3-pro-preview", "name": "Gemini 3 Pro", "contextWindow": 2000000, "maxTokens": 8192}]
      }
    }
  }
}

2. 配置鉴权文件（auth-profiles.json）

路径：~/.openclaw/agents/main/agent/auth-profiles.json

替换为以下内容，同时把sk-xxx替换成你的一步API Key：

{
  "version": 1,
  "profiles": {
    "api-proxy-gpt:default": {"type": "api_key", "provider": "api-proxy-gpt", "key": "你的GPT密钥"},
    "api-proxy-claude:default": {"type": "api_key", "provider": "api-proxy-claude", "key": "你的Claude密钥"},
    "api-proxy-google:default": {"type": "api_key", "provider": "api-proxy-google", "key": "你的Gemini密钥"}
  },
  "lastGood": {
    "api-proxy-gpt": "api-proxy-gpt:default",
    "api-proxy-claude": "api-proxy-claude:default",
    "api-proxy-google": "api-proxy-google:default"
  }
}

步骤4：启动服务并测试

  1. 检查配置：openclaw doctor，显示“All checks passed”即为正常；

  2. 启动服务：openclaw gateway；

  3. 测试：复制终端生成的Web地址，在浏览器打开，发送指令（如“新建一个文本文档”），能正常执行就是成功。

四、新手必看：常见问题排查（避坑重点）

  1. Node.js版本过低：升级到22.x，重新安装；

  2. AI连接失败：大概率是API Key填错，或配置文件没保存，重新核对并重启服务；

  3. Windows安装失败：没装WSL2，先装WSL2再操作；

  4. 配置文件修改后无效果：重启Gateway服务（Ctrl+C停止，再重新启动）。

五、总结

OpenClaw的核心优势的是“简单易上手+全模型适配”，搭配一步API，新手也能快速搭建专属AI助手，不管是日常办公还是开发，都能大幅提升效率。

其实安装过程不难，只要跟着教程一步步来，重点注意Node.js版本、配置文件修改这两个点，基本不会踩坑。

如果在安装过程中遇到其他问题，欢迎在评论区留言，我会一一回复解答～

最后求个赞，整理不易，帮助更多新手少走弯路！

avatar
文章
阅读
粉丝