OpenClaw 是一款强大的本地 AI 代理框架，能让你在本地对接各类大模型、打造专属 AI 助手。但安装与配置过程中，常遇到模型认证失败、配置格式不兼容、命令语法报错等问题。本文结合最新版（2026.3.13）实操经验，从环境准备、安装步骤、核心配置到高频问题解决，带你一站式搞定本地部署。

一、环境准备：避坑第一步

OpenClaw 对运行环境有明确要求，提前准备可避免 80% 的安装报错。

1. 系统与硬件要求

• 操作系统：Windows 10/11（推荐 WSL2）、macOS 14+、Ubuntu 22.04+
• 内存：最低 4GB，推荐 8GB+（运行多模型时建议 16GB）
• 存储：至少 5GB 可用空间（含依赖、模型缓存）
• 处理器：64 位 CPU（必须，32 位系统不支持）

2. 核心依赖安装（必装）

（1）Node.js（关键！版本 ≥22.x LTS）

OpenClaw 基于 Node.js 开发，低于 22.x 版本会直接无法启动。

• 下载：Node.js 官网，选择 22.x 及以上 LTS 版本（推荐 24.x）
• 安装：Windows 选择 64 位安装包，路径必须纯英文，禁止含中文 / 特殊符号
• 验证：打开终端执行

  bash

  node -v  # 输出 v22.x+ 即成功
  npm -v   # 输出对应版本
  

（2）Git（可选，源码安装时需要）

• 下载：Git 官网，默认安装即可
• 验证：git --version 输出版本号即成功

二、OpenClaw 安装：两种主流方式

方式一：一键脚本安装（推荐，新手首选）

自动检测环境、安装依赖、初始化配置，最省心。

• Windows（PowerShell 管理员权限）

  powershell

  iwr -useb https://openclaw.ai/install.ps1 | iex
  

• macOS/Linux/WSL2

  bash

  curl -fsSL https://openclaw.ai/install.sh | bash
  

• 安装成功后，终端会提示 OpenClaw installed successfully，执行 openclaw version 验证版本（本文基于 2026.3.13 版本）。

方式二：npm 手动安装（适合自定义配置）

已安装 Node.js 时，直接全局安装最新版：

bash

npm install -g openclaw@latest
# 若遇到 sharp 编译报错，执行以下命令强制使用预编译二进制
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

验证：openclaw --help 显示命令列表即成功。

三、核心配置：对接大模型（以阿里云百炼为例）

安装完成后，需配置模型提供商才能正常对话，2026.3.13 版本配置格式有重大变更，直接沿用旧版配置会报错。

1. 配置文件路径

Windows：C:\Users\<你的用户名>\.openclaw\openclaw.jsonmacOS/Linux：~/.openclaw/openclaw.json

2. 合规配置（适配 2026.3.13 版本）

以下配置移除失效模型、适配新版语法、对接阿里云百炼，直接复制替换即可：

json

{
  "models": {
    "providers": {
      "alibaba-cloud": {
        "apiKey": "你的阿里云百炼 API Key",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "models": ["qwen3.5-turbo"]
      }
    },
    "agentDefaults": {
      "provider": "alibaba-cloud",
      "model": "qwen3.5-turbo"
    }
  },
  "channels": {
    "telegram": {
      "groupPolicy": "open",
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  },
  "gateway": {
    "bindMode": "loopback",
    "port": 18789
  },
  "agentDefaults": {
    "memorySearch": {
      "enabled": false
    }
  }
}

• 关键修改：
  1. 用 bindMode: "loopback" 替代旧版 gateway.bind: "127.0.0.1"（新版废弃 IP 绑定格式）
  2. 用 models.agentDefaults 替代旧版 models.default（键名规范调整）
  3. 补充 telegram.allowFrom: ["*"]（dmPolicy=open 必须配置）

3. 启动服务

配置保存后，执行以下命令启动核心服务：

bash

# 自动修复配置兼容性问题（必执行！）
openclaw doctor --fix
# 启动网关服务
openclaw gateway run
# 启动默认代理
openclaw agents start main
# 打开 Web 仪表盘（浏览器访问）
openclaw dashboard

启动成功后，终端显示 Gateway running on ws://127.0.0.1:18789 (loopback)，即可在仪表盘正常对话。

四、高频问题解决：从报错到修复（实操案例）

问题 1：模型全部调用失败（All models failed）

报错信息：

plaintext

Agent failed before reply: All models failed (3): qwen-portal/coder-model: OAuth token refresh failed... openai-codex/gpt-5.1: No API key found...

原因：

1. Qwen 模型 OAuth 令牌过期 / 无效
2. OpenAI 模型未配置 API Key
3. 配置文件保留了失效模型提供商

解决方案：

1. 重新认证 Qwen 模型（若需使用）：

   bash

   openclaw models auth login --provider qwen-portal
   

2. 彻底移除失效模型：直接编辑 openclaw.json，删除 qwen-portal 和 openai-codex 相关配置，仅保留可用模型（如阿里云百炼）
3. 重启服务：openclaw gateway restart、openclaw agents restart main

问题 2：配置文件格式不兼容（gateway.bind 废弃）

报错信息：

plaintext

gateway.bind: gateway.bind host aliases are legacy; use bind modes (lan/loopback/custom/tailnet/auto) instead

原因：2026.3.13 版本废弃 gateway.bind IP 格式，改用 bindMode 模式。

解决方案：

1. 打开 openclaw.json，将 gateway.bind: "127.0.0.1" 替换为 gateway.bindMode: "loopback"
2. 执行 openclaw doctor --fix 自动修复剩余兼容性问题
3. 重启网关：openclaw gateway run

问题 3：命令语法报错（too many arguments）

报错信息：

plaintext

error: too many arguments for 'agents'. Expected 0 arguments but got 2.

原因：新版 OpenClaw 简化了 agents 命令语法，旧版 agents restart main 格式无效。

解决方案：

• 新版正确命令：

  bash

  # 启动代理
  openclaw agents start
  # 重启代理
  openclaw agents restart
  # 停止代理
  openclaw agents stop
  

• 避免使用 agents restart main 等带参数的旧版语法。

问题 4：配置文件存在未知键（Unknown config keys）

报错信息：

plaintext

Unknown config keys: models.default, agents.main, agentsDefaults

原因：新版配置键名规范调整，旧版键名不被识别。

解决方案：

1. 替换 models.default 为 models.agentDefaults
2. 删除 agents.main 单独配置，改用全局 agentDefaults
3. 将 agentsDefaults 改为 agentDefaults（去掉多余的 s）
4. 执行 openclaw doctor --fix 自动清理无效键

问题 5：openclaw 命令找不到（command not found）

原因：

1. 安装后未重新打开终端（PATH 未生效）
2. Node.js 全局路径未添加到系统环境变量

解决方案：

1. 关闭当前终端，重新打开 PowerShell/Terminal
2. 手动加载环境变量（macOS/Linux）：

   bash

   source ~/.zshrc  # zsh 用户
   source ~/.bashrc # bash 用户
   

3. 检查 Node.js 全局路径：npm prefix -g，将输出路径添加到系统 PATH 中

五、总结与验证

1. 部署成功验证

• 执行 openclaw doctor，无红色报错，显示 Config valid
• 执行 openclaw gateway run，网关正常启动，无配置错误
• 打开 Web 仪表盘，发送对话，模型正常响应，无 All models failed 报错

2. 核心避坑要点

1. Node.js 版本必须 ≥22.x，低于此版本直接无法运行
2. 新版配置用 bindMode 替代 IP 绑定，切勿沿用旧版格式
3. 模型配置优先保留可用提供商，及时清理失效配置
4. 遇到报错优先执行 openclaw doctor --fix，自动修复兼容性问题

OpenClaw 本地部署的核心是适配新版配置语法 + 正确对接模型，按照本文步骤操作，可快速解决 90% 以上的安装与运行问题。若遇到特殊报错，可通过 openclaw logs --follow 查看详细日志，定位具体问题根源。