OpenClaw 完整配置教程（含第三方兼容接入）

广告：如果你想直接把 OpenClaw 接到一个稳定、统一、兼容 OpenAI 的模型入口上，可以直接使用 api.clawsocket.com。一套 Key 就能统一接入 GPT、Claude、Gemini、Grok 等常见模型，适合拿来做 OpenClaw、Codex、Claude Code 这类工具的长期配置。

如果你准备开始用 OpenClaw，真正卡住大多数人的往往不是“装不上”，而是后面这几步：

openclaw onboard 到底怎么选
openclaw.json 在哪里
第三方兼容接入 API 怎么接
控制台为什么能打开，但模型不返回

这篇 OpenClaw 安装教程就按一条最稳的路线来讲：先装 OpenClaw，再跑官方初始化向导，最后把 api.clawsocket.com 接进 openclaw.json。

OpenClaw 官网与产品定位示意图

配图说明：本文中的 OpenClaw 界面图基于 CSDN 文章《OpenClaw 配置教程（含接入第三方兼容接入配置方法）》所附配图使用。原文标注为 CC BY-SA 4.0，本文仅做文件名整理与版式适配，原文链接见文末。

快速结论

OpenClaw 官方推荐安装方式是安装脚本，自己管理 Node 的话也可以直接 npm install -g openclaw@latest
初始化最好先跑一遍 openclaw onboard，把工作区、网关端口和 token 先生成出来
OpenClaw 的主配置文件是 ~/.openclaw/openclaw.json
接第三方兼容接入的核心就是在 models.providers 里配置 baseUrl、apiKey、api
如果你用的是 api.clawsocket.com，最省事的接法就是走 OpenAI 兼容入口：https://api.clawsocket.com/v1

这篇文章适合谁

这篇教程主要写给下面这几类用户：

第一次安装 OpenClaw 的新手
已经装好了 OpenClaw，但还没把模型跑起来
想让 OpenClaw 走面向开发者的统一 API 网关
想把 OpenClaw、Codex、Claude Code 放进同一套 API 管理方式里

如果你的目标不是折腾本地配置，而是尽快把 OpenClaw 跑起来，这篇 OpenClaw 安装教程会更适合你。

OpenClaw 是什么

OpenClaw 可以理解成一个偏“个人 AI 助手 / 本地 Agent 控制台”的运行框架。它的核心能力不是单纯聊天，而是把模型调用、网关服务、控制台和工具能力组织到一起。

比较实用的点包括：

有自己的 gateway 和 dashboard
支持 workspace、skills、hooks
可以通过配置文件管理模型入口
适合做本地助手、频道机器人、自动化代理和实验型 Agent

也正因为它不是单纯的聊天客户端，所以配置模型入口时，最好一开始就把结构理清楚。

一、安装与配置

这部分 OpenClaw 安装教程的目标很明确：先把 OpenClaw 从“没有安装”推进到“本机可以正常启动和打开 dashboard”。

第 1 步：安装 OpenClaw

根据 OpenClaw 官方文档，最快的安装方式是官方安装脚本。

macOS / Linux / WSL2：

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

Windows PowerShell：

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

如果你已经自己装好了 Node，也可以直接用 npm：

npm install -g openclaw@latest
openclaw onboard --install-daemon

官方当前要求是 Node 24 推荐，至少 Node 22.16+。

装完以后，先确认 CLI 是否可用：

openclaw --version

如果这里都跑不通，就先不要继续往下配统一网关，先把基础安装修好。

第 2 步：运行 `openclaw onboard`

OpenClaw 官方推荐新用户先跑初始化向导：

openclaw onboard

这一步主要会帮你做几件事：

检查已有配置
生成或保留 ~/.openclaw/openclaw.json
设置默认 workspace
设置网关端口、绑定地址和认证方式
引导你选模型、认证方式、聊天渠道和一些附加组件

如果你现在就是想先把第三方兼容接入接起来，我建议在向导里采用“先最小化完成初始化，再手动接 relay”的思路。

比较稳的做法是：

先保留默认 workspace，例如 ~/.openclaw/workspace
网关保持默认本地地址和端口
认证方式保留 token
模型和上游认证先跳过，后面统一在配置文件里改

这样做的好处是，你先把 OpenClaw 的基础骨架跑起来，再去改模型入口，排错更简单。

第 3 步：保存好 dashboard token

openclaw onboard 结束后，一般会把 dashboard 地址、带 token 的访问链接和 gateway 信息打印出来。这个 token 非常重要，别手滑关掉以后又不知道去哪找。

下面这种输出就是典型示意：

OpenClaw onboard 结束后的 Dashboard Ready 提示

建议你记住这 3 个点：

默认控制台通常是 http://127.0.0.1:18789/
最稳的打开方式是直接执行 openclaw dashboard
如果页面提示 token_missing 或认证失败，优先检查是不是用了不带 token 的地址

二、接入第三方兼容接入 API

这一段是整篇 OpenClaw 安装教程里最关键的部分，因为大多数人真正卡住的就是模型入口和 API Key。

第 4 步：先在 `api.clawsocket.com` 生成令牌

在改 OpenClaw 配置之前，先去 api.clawsocket.com 准备自己的 API Key。

你现在这套服务本身就是基于 New API 面板，所以流程可以直接按下面这条最短路径走：

登录 api.clawsocket.com
进入 令牌管理
点击 添加令牌
分组选择 default
生成并复制你的 Key

拿到 Key 以后，建议不要直接硬编码进配置文件，而是先放进环境变量。

macOS / Linux：

export CLAWSOCKET_API_KEY="你的 API Key"

如果你想长期生效，可以写进 ~/.zshrc：

echo 'export CLAWSOCKET_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell 可以先用当前会话方式测试：

$env:CLAWSOCKET_API_KEY="你的 API Key"

这样做的好处很直接：

Key 不会散落在多个项目里
换机器或换环境时更好迁移
后面接 Codex、Claude Code 也可以沿用同一套思路

第 5 步：找到 `openclaw.json`

OpenClaw 这类工具最怕“配置其实写对了，但你改错文件”。

默认配置文件位置是：

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

如果你不确定当前实际使用的是哪个文件，可以直接运行：

openclaw config file

第 6 步：修改 `openclaw.json` 接入 `api.clawsocket.com`

这是整篇最关键的一步。

OpenClaw 官方配置参考里明确写了，~/.openclaw/openclaw.json 支持通过 models.providers.* 来声明自定义 provider，其中最关键的字段就是：

baseUrl
apiKey
api
models

如果你想用 api.clawsocket.com 作为统一 API 入口，最省事的方式是直接按 OpenAI 兼容接口来配。

你可以把 openclaw.json 改成下面这种结构：

{
  gateway: {
    port: 18789,
    mode: "local",
    bind: "loopback",
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },

  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "clawsocket/gpt-5.4",
        fallbacks: [
          "clawsocket/claude-sonnet-4-5",
          "clawsocket/gemini-2.5-pro",
        ],
      },
      models: {
        "clawsocket/gpt-5.4": {},
        "clawsocket/gpt-5.3-codex": {},
        "clawsocket/claude-sonnet-4-5": {},
        "clawsocket/gemini-2.5-pro": {},
      },
    },
  },

  models: {
    mode: "merge",
    providers: {
      clawsocket: {
        baseUrl: "https://api.clawsocket.com/v1",
        apiKey: "${CLAWSOCKET_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.4", name: "GPT-5.4" },
          { id: "gpt-5.3-codex", name: "GPT-5.3 Codex" },
          { id: "claude-sonnet-4-5", name: "Claude Sonnet 4.5" },
          { id: "gemini-2.5-pro", name: "Gemini 2.5 Pro" },
        ],
      },
    },
  },
}

如果你只想最小化改动，也可以先保留一个默认模型，等确认通了以后再继续往 fallbacks 里加 Claude 和 Gemini。

这份配置怎么理解

上面这份配置，真正需要你理解的只有 5 个点：

1. `models.providers.clawsocket`

这里的 clawsocket 只是 provider id，你也可以改成别的名字，但建议和服务名保持一致，后面排错更直观。

2. `baseUrl`

这里写的是第三方统一网关实际 API 入口：

https://api.clawsocket.com/v1

如果你将来换成别的 relay，这里就是第一处要改的地方。

3. `apiKey`

这里用的是环境变量：

${CLAWSOCKET_API_KEY}

OpenClaw 官方配置文档支持这种环境变量替换写法，所以不需要把 Key 明文塞进文件里。

4. `api`

这里写的是：

openai-completions

原因不是 OpenClaw 只能接 OpenAI，而是对大多数第三方兼容接入平台来说，OpenAI 兼容接口通常是最容易落地、最容易排错、兼容面也最广的一条路。

5. `agents.defaults.model.primary`

这个字段决定默认跑哪个模型。格式是：

provider/model

所以这里写成：

clawsocket/gpt-5.4

如果你后面想默认换成 Claude 或 Gemini，只要 relay 端支持对应模型 id，这里直接改就行。

第 7 步：验证配置文件没写坏

OpenClaw 的配置校验比较严格。官方文档明确说明，未知字段、类型错误、无效值都可能导致 Gateway 直接拒绝启动。

所以你改完以后，先跑一遍：

openclaw config validate

如果验证失败，再继续运行：

openclaw doctor

这一步能帮你快速定位到底是 JSON5 语法问题、字段层级写错，还是环境变量没生效。

三、启动与日常使用

如果你前面的 OpenClaw 安装教程步骤都做完了，到了这里就应该进入验证和日常使用阶段。

第 8 步：启动 Gateway

配置通过以后，就可以启动 OpenClaw 网关。

先用前台方式测试最稳：

openclaw gateway

如果你想让它后台运行，再考虑：

openclaw gateway start

对大多数第一次配置的人来说，我建议先用前台模式。因为一旦报错，你能第一时间在终端里看到，而不是去猜是不是守护进程没起来。

第 9 步：打开 Dashboard 进行测试

网关起来以后，最省事的方式是直接执行：

openclaw dashboard

它会自动帮你打开 dashboard 页面。正常情况下你会看到类似下面这种控制台界面：

OpenClaw Gateway Dashboard 控制台界面示意

这时候你可以直接做最简单的验证：

问一个当前时间问题
让它查看当前用户名
发一个简单的总结请求

如果能正常返回，就说明你的 gateway、token、provider 和模型链路基本已经通了。

怎么判断 OpenClaw 已经走了统一网关

最实用的判断方式有 4 个：

openclaw config validate 能通过
CLAWSOCKET_API_KEY 已经正确注入到当前 shell / 服务环境
openclaw.json 里的 baseUrl 已经是 https://api.clawsocket.com/v1
控制台实际发起对话时，模型能正常返回，不再报上游认证错误

如果你前 3 项都对，但第 4 项还不对，优先检查的通常不是 OpenClaw 本身，而是：

relay 的模型名是否写对
Key 是否有效
Gateway 是否读到了最新环境变量

四、OpenClaw 能做什么

OpenClaw 真正有意思的地方，不是“把一个聊天框跑起来”，而是它可以在统一控制面板里接管一批更像助手和 Agent 的能力。

常见用法包括：

作为本地 AI 助手，处理一般问答和工作信息
接频道和群聊，做 Slack / Telegram / Discord 机器人
配技能和 hooks，让它做网页抓取、自动回复、命令执行
结合 workspace 和 session 能力做多任务实验
当作你自己的本地模型调度面板，统一调用 GPT、Claude、Gemini

如果你本来就打算把 OpenClaw 当成“个人代理层”，那么把模型入口提前统一到 api.clawsocket.com，后面管理起来会比一个工具配一套 Key 轻松很多。

五、常用命令速查

很多人看 OpenClaw 安装教程时最怕命令太散，所以这里单独整理成一张速查表。

下面这些命令基本够你完成安装、排错和日常使用：

命令	作用
`openclaw --version`	查看 OpenClaw 版本
`openclaw onboard`	重新运行初始化向导
`openclaw config file`	查看当前配置文件路径
`openclaw config validate`	校验配置文件是否有效
`openclaw doctor`	诊断安装、环境和配置问题
`openclaw gateway`	前台启动 gateway
`openclaw gateway start`	启动后台 gateway
`openclaw gateway stop`	停止后台 gateway
`openclaw dashboard`	打开带 token 的 dashboard 页面

如果你是第一次接 relay，我建议按这个顺序排错：

openclaw config validate
echo $CLAWSOCKET_API_KEY
openclaw gateway
openclaw dashboard

这样基本能把 80% 的问题定位出来。

六、快速上手路线图

如果你只想按最短路径照着做，可以直接把这一段当成 OpenClaw 安装教程的执行清单。

如果你不想看太多细节，直接按下面这条路线走就够了：

安装 OpenClaw
运行 openclaw onboard
保存 dashboard token
去 api.clawsocket.com 的 令牌管理 里添加令牌，分组选 default
把 CLAWSOCKET_API_KEY 写进环境变量
在 openclaw.json 里把 baseUrl 改成 https://api.clawsocket.com/v1
跑 openclaw config validate
启动 openclaw gateway
打开 openclaw dashboard 验证

走完这 9 步，你基本就已经把 OpenClaw 从“装好”推进到了“真能用”。

常见问题

OpenClaw 一定要先配官方 API，才能接第三方兼容接入吗

不一定。

按照官方文档，openclaw onboard 可以先完成基础初始化，模型认证可以后配。对想走 relay 的用户来说，先把框架装好，再在 openclaw.json 里接自定义 provider，通常更直接。

`openclaw.json` 是 JSON 还是 JSON5

官方配置文档说明它是 JSON5。这意味着你可以写注释，也可以保留尾逗号，比纯 JSON 更适合手改。

为什么我改了环境变量，OpenClaw 还是报 Key 错误

最常见的原因有 3 个：

你改的是当前 shell，但 Gateway 是从旧会话启动的
你把 Key 写进了 ~/.zshrc，但没有重新 source ~/.zshrc
守护进程启动时没有读到新环境变量

最稳的排查顺序是：

echo $CLAWSOCKET_API_KEY
openclaw config validate
关掉旧 Gateway，再重新启动
再开 dashboard 测试

为什么我照着别人的文章配，结果字段结构不一样

因为 OpenClaw 还在持续演进，网上很多旧文章会把 models.providers 写成旧模板、数组模板，或者直接写成某个站点自己的兼容示例。

这篇 OpenClaw 安装教程优先按 OpenClaw 当前官方配置参考来组织结构，并改成了适合 api.clawsocket.com 的接法，所以更适合作为现在的落地版本。

第三方统一网关一定要走 `openai-completions` 吗

不是。

OpenClaw 官方配置参考支持多种 api 适配器，例如：

openai-completions
openai-responses
anthropic-messages
google-generative-ai

但对大多数第三方 relay 来说，OpenAI 兼容入口通常最容易接，尤其是你希望一套入口兼容多个模型时。

总结

这篇 OpenClaw 安装教程讲到最后，真正需要你做的事情其实就 3 件事：

按官方方式把 OpenClaw 装好
用 openclaw onboard 把 workspace、gateway、token 先生成出来
在 ~/.openclaw/openclaw.json 里把 api.clawsocket.com 这个 provider 配进去

如果你的目标是尽快把 OpenClaw 变成一个能用的本地 AI 助手，而不是在认证和上游接口上来回折腾，那么把它接到 api.clawsocket.com 这种统一入口上，会比每次单独折腾上游更省时间。

接下来你可以继续看：

想接 OpenAI 兼容接口：阅读 OpenAI API Proxy
想马上申请 Key：前往 api.clawsocket.com
想看更多接入文章：继续浏览博客

广告：如果你不想自己维护多家上游 API 和多套 Key，可以直接在 api.clawsocket.com 生成令牌，然后按本文的 baseUrl + apiKey + models.providers 结构接进 OpenClaw。对开发者来说，这样的统一入口通常比逐个模型单独折腾更省时间，也更适合后续继续扩展到 Claude Code、Codex 和其他 Agent 工具。

快速结论#

这篇文章适合谁#

OpenClaw 是什么#

一、安装与配置#

第 1 步：安装 OpenClaw#

第 2 步：运行 openclaw onboard#

第 3 步：保存好 dashboard token#

二、接入第三方兼容接入 API#

第 4 步：先在 api.clawsocket.com 生成令牌#

第 5 步：找到 openclaw.json#

第 6 步：修改 openclaw.json 接入 api.clawsocket.com#

这份配置怎么理解#

1. models.providers.clawsocket#

2. baseUrl#

3. apiKey#

4. api#

5. agents.defaults.model.primary#

第 7 步：验证配置文件没写坏#

三、启动与日常使用#

第 8 步：启动 Gateway#

第 9 步：打开 Dashboard 进行测试#

怎么判断 OpenClaw 已经走了统一网关#

四、OpenClaw 能做什么#

五、常用命令速查#

六、快速上手路线图#

常见问题#

OpenClaw 一定要先配官方 API，才能接第三方兼容接入吗#

openclaw.json 是 JSON 还是 JSON5#

为什么我改了环境变量，OpenClaw 还是报 Key 错误#

为什么我照着别人的文章配，结果字段结构不一样#

第三方统一网关一定要走 openai-completions 吗#

总结#

参考资料#