OpenClaw 完整安装与配置指南：从零开始搭建你的私人 AI 助手

OpenClaw 是一个运行在你自己电脑或服务器上的个人 AI 助手平台，支持接入 Claude、GPT、Qwen 等主流大模型，并可以通过 Telegram、Discord、Slack 等消息渠道随时与 AI 对话。这篇文章会手把手带你完成从安装到正常使用的全部步骤，包括我在实际操作中踩过的坑和解决方法。

安装前的准备

在开始之前，你需要确认一件事：Node.js 版本必须是 22 或更高。

node -v

如果输出的是 v22.x.x 或更高，说明环境没问题。如果版本过低，先去 Node.js 官网下载最新 LTS 版本，或者用 nvm 来管理版本。

安装 OpenClaw

用 npm 全局安装，-g 参数的意思是”全局安装”，安装后在任意目录都可以直接运行 openclaw 命令：

npm install -g openclaw@latest

安装完成后，运行初始配置向导：

openclaw onboard

向导会引导你选择消息平台和 AI 模型，跟着提示一步步操作即可。

网关配置与启动

这是很多人卡住的地方。OpenClaw 的核心是一个本地网关服务，Web 控制台、消息平台通信都依赖它运行。

为什么访问不了 http://127.0.0.1:18789/？

安装完成后，OpenClaw 会提示你访问 http://127.0.0.1:18789/，但很多情况下直接访问会出现”连接被拒绝”。原因是网关服务没有启动，或者缺少必要的配置项。

第一步：设置网关模式

这是最常被忽略的步骤。如果跳过这一步，网关会直接拒绝启动：

openclaw config set gateway.mode local

第二步：安装并启动网关服务

⚠️ 以下命令需要以管理员身份运行 PowerShell，否则会提示”拒绝访问”。

右键点击 PowerShell，选择”以管理员身份运行”，然后执行：

openclaw gateway install

安装成功后会显示：

Installed Scheduled Task: OpenClaw Gateway

接着手动触发网关启动：

schtasks /Run /TN "OpenClaw Gateway"

第三步：验证是否成功

等几秒钟，然后检查网关是否可达：

openclaw gateway probe

如果看到 Reachable: yes，说明网关正常运行，浏览器访问 http://127.0.0.1:18789/ 就能打开控制台了。

第四步：处理 Token 验证

首次访问控制台可能提示”unauthorized: gateway token missing”。这是正常的安全机制，获取 Token 的方法：

openclaw config get gateway.auth.token

把输出的 Token 值粘贴到浏览器弹出的验证框里即可。

配置第三方大模型

OpenClaw 内置支持 Anthropic、OpenAI、Google Gemini、OpenRouter 等多个主流提供商。如果你使用的是第三方中转服务（即通过别的平台访问 Claude 或 GPT），需要手动配置自定义提供商。

配置文件位置

所有配置都存放在：

C:\Users\你的用户名\.openclaw\openclaw.json

用记事本打开：

notepad "C:\Users\你的用户名\.openclaw\openclaw.json"

自定义提供商配置模板

以下是一个完整的配置示例，适用于支持 OpenAI 格式接口（/v1/chat/completions）的第三方服务：

{
  "models": {
    "mode": "merge",
    "providers": {
      "my-provider": {
        "baseUrl": "https://你的服务商域名/v1",
        "apiKey": "你的-API-Key",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-5",
            "name": "Claude Opus 4.5",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8096,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
          },
          {
            "id": "claude-sonnet-4-5",
            "name": "Claude Sonnet 4.5",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8096,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
          },
          {
            "id": "claude-haiku-4-5",
            "name": "Claude Haiku 4.5",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8096,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "my-provider/claude-opus-4-5",
        "fallbacks": ["my-provider/claude-sonnet-4-5"]
      },
      "models": {
        "my-provider/claude-opus-4-5": { "alias": "opus" },
        "my-provider/claude-sonnet-4-5": { "alias": "sonnet" },
        "my-provider/claude-haiku-4-5": { "alias": "haiku" }
      }
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "token": "auto"
    }
  }
}

几个容易出错的细节

配置项	注意事项
`baseUrl`	末尾不要加 `/`，通常需要带 `/v1`，例如 `https://api.example.com/v1`
`models[].id`	必须填服务商实际支持的模型名，不能乱写
`agents.defaults.models`	这是白名单，只有列在这里的模型才能被使用
`gateway.mode`	必须设置为 `local`，否则网关启动会被拦截

验证服务商接口是否可用

配置好之后，先测试一下 API 是否真的能通：

Invoke-WebRequest -Method POST `
  -Uri "https://你的服务商域名/v1/chat/completions" `
  -Headers @{
    "Authorization" = "Bearer 你的-API-Key"
    "Content-Type" = "application/json"
  } `
  -Body '{"model":"claude-opus-4-5","messages":[{"role":"user","content":"hi"}],"max_tokens":100}' |
  Select-Object -ExpandProperty Content

返回包含 choices 字段的 JSON 说明接口正常；如果返回 401 是 Key 问题，返回 404 通常是 baseUrl 路径不对。

配置后重启网关

每次修改配置文件都需要重启网关才能生效：

schtasks /Run /TN "OpenClaw Gateway"

API Key 安全配置

把 API Key 直接写在配置文件里不够安全，推荐用环境变量引用的方式：

第一步：创建或编辑 ~/.openclaw/.env 文件：

ANTHROPIC_API_KEY=你的密钥
GATEWAY_TOKEN=自定义一个安全密码

第二步：在 openclaw.json 里用 ${变量名} 引用：

{
  "models": {
    "providers": {
      "my-provider": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

同时，建议修复配置文件的权限，防止其他用户读取你的 Key（以管理员身份运行）：

icacls "C:\Users\你的用户名\.openclaw\openclaw.json" /inheritance:r /grant:r "你的用户名:F" /grant:r "SYSTEM:F"

常见问题排查

问题一：网关启动后立刻闪退

直接在命令行运行网关脚本，查看具体报错：

cmd /c "C:\Users\你的用户名\.openclaw\gateway.cmd"

最常见的报错是：

Gateway start blocked: set gateway.mode=local (current: unset)

解决方法：

openclaw config set gateway.mode local

问题二：端口被占用

netstat -ano | findstr 18789

找到占用进程的 PID，在任务管理器里结束它，或者换一个端口：

openclaw config set gateway.port 18790

问题三：对话没有任何回应

这个问题比较隐蔽，OpenClaw 不会直接显示错误，AI 消息就好像消失了一样。排查步骤：

查看实时日志，打开新的 PowerShell 窗口：

openclaw logs --follow

然后发一条消息，观察日志。如果整个请求从发出到结束只用了 1 秒左右（正常 Claude API 调用至少需要 3-5 秒），说明请求根本没有发出去，通常原因是：

baseUrl 路径不对（缺少 /v1）
API Key 无效
模型 id 填写有误

直接测试 API 接口是最快的排查方式，参考上方”验证服务商接口是否可用”部分。

问题四：gateway.mode 被重置

手动编辑 openclaw.json 时，如果覆盖了整个文件内容，之前通过命令行设置的 gateway.mode 会丢失。确保配置文件里始终包含：

"gateway": {
  "mode": "local"
}

常见问题速查表

现象	可能原因	解决方法
`Connection refused`	网关未运行	运行 `schtasks /Run /TN "OpenClaw Gateway"`
网关立刻闪退	`gateway.mode` 未设置	`openclaw config set gateway.mode local`
安装计划任务失败	权限不足	以管理员身份运行 PowerShell
AI 无回应	API 接口问题	直接测试 API，检查 Key 和 baseUrl
Token 验证失败	auth.token 丢失	`openclaw config get gateway.auth.token`
配置修改不生效	网关未重启	重新运行计划任务

开机自动启动

默认情况下，每次开机都需要手动启动网关。设置自动启动只需一条命令（管理员 PowerShell）：

schtasks /Change /TN "OpenClaw Gateway" /SC ONLOGON /ENABLE

验证是否设置成功：

schtasks /Query /TN "OpenClaw Gateway" /FO LIST

看到触发器显示”登录时”或”At logon”说明设置成功，以后开机登录后网关会自动启动。

版本更新方法

查看当前版本：

openclaw --version

升级到最新版（以管理员身份运行）：

npm i -g openclaw@latest

升级完成后重启网关：

openclaw gateway restart

注意：如果 openclaw update 命令提示 not-git-install，说明你是通过 npm 安装的，必须用 npm i -g openclaw@latest 来更新，不能用内置更新命令。

如何使用 OpenClaw

OpenClaw 主要有三种使用方式：

方式一：Web 控制台（推荐）

浏览器访问 http://127.0.0.1:18789/，功能最完整，支持多轮对话、文件上传、技能管理，适合日常使用。

方式二：终端 UI

openclaw tui

在命令行中打开一个交互界面，适合不想开浏览器的场景。

方式三：消息平台

配置 Telegram 或 Discord 机器人后，可以在手机上直接与 AI 对话，随时随地使用。

对话中的常用命令

在聊天窗口中输入斜杠命令可以快速切换设置：

命令	作用
`/model opus`	切换到 Claude Opus（使用配置的别名）
`/model sonnet`	切换到 Claude Sonnet
`/model list`	查看所有可用模型
`/new`	开始新会话
`/stop`	中止当前运行
`/status`	查看 token 用量和会话状态
`/think`	开启推理模式
`/compact`	压缩上下文，释放窗口空间

FAQ 常见问答

Q：每次开机都需要手动执行哪些命令吗？

A：不需要。gateway.mode local 是永久写入配置文件的，只需要按照”开机自动启动”章节设置一次计划任务，之后登录系统网关会自动启动。

Q：openclaw.json 文件损坏了怎么办？

A：配置文件在每次修改时会自动备份为 openclaw.json.bak，可以直接复制备份文件恢复。

Q：第三方服务商的模型 id 应该填什么？

A：通过以下方式查询服务商支持的模型列表：

Invoke-WebRequest -Uri "https://你的服务商域名/v1/models" `
  -Headers @{"Authorization" = "Bearer 你的-API-Key"} |
  Select-Object -ExpandProperty Content

返回结果里的 id 字段就是要填的值。

Q：OpenClaw 会把我的 API Key 上传到服务器吗？

A：不会。OpenClaw 是完全本地运行的，API Key 只保存在你的电脑上，所有 AI 请求都是从你的机器直接发出的，不经过 OpenClaw 的服务器。

Q：配置文件编辑后没有生效怎么办？

A：每次修改配置文件后都需要重启网关：

schtasks /Run /TN "OpenClaw Gateway"

Q：如何查看 OpenClaw 的实时运行日志？

A：

openclaw logs --follow

这个命令会持续输出日志，对排查问题非常有帮助。

Q：openclaw chat 命令为什么不存在？

A：OpenClaw 没有 chat 子命令，命令行交互主要通过 openclaw tui 进入终端界面，或者直接访问 Web 控制台。

Q：出现乱码错误信息怎么办？

A：Windows 系统中某些命令的错误提示可能以乱码显示，但错误含义通常是”拒绝访问”，以管理员身份重新运行对应命令即可解决。

配置文件完整示例

为了方便参考，这里给出一份包含所有关键配置项的完整 openclaw.json 模板：

{
  "models": {
    "mode": "merge",
    "providers": {
      "my-provider": {
        "baseUrl": "https://你的服务商域名/v1",
        "apiKey": "${MY_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-5",
            "name": "Claude Opus 4.5",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8096,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "my-provider/claude-opus-4-5",
        "fallbacks": []
      },
      "models": {
        "my-provider/claude-opus-4-5": { "alias": "opus" }
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true
  },
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "token": "auto"
    }
  }
}

整个配置流程下来，最容易出问题的三个地方是：gateway.mode 没设置、baseUrl 缺少 /v1、以及安装计划任务时没有用管理员权限。按照本文的步骤操作，基本上都能顺利跑起来。如果遇到其他问题，优先用 openclaw logs --follow 查看日志，再结合 openclaw doctor 自动诊断，大多数问题都能快速定位。

保姆级OpenClaw安装教程 | 手把手教会你在Windows搭建专属AI助手（破解7大常见错误）