OpenClaw 安装与 OmniProxy 配置

OpenClaw 是装在自己电脑上的 AI 助手。你可以直接在 Telegram、Discord、WhatsApp 或飞书里跟它说话，不必一直开着另一个聊天窗口；对话和记录会留在这台电脑上，它也能在本机接着完成后续步骤。

安装前准备

OpenClaw 需要 Node 24.16 或更高版本，也可以使用 Node 26.1 或更高版本，建议使用 Node 26。Node 是 OpenClaw 运行时需要的基础环境。

macOS、Linux 和 Windows 都可以安装。电脑里没有合适的 Node 时，安装脚本会自行准备：macOS 上准备 Node 26，Linux 上准备 Node 24 LTS。只有从源码构建 OpenClaw 时，才需要 pnpm。

电脑里已经装了较旧的 Node，也不必急着卸载。2026-10-09 测试时，这台电脑的系统 Node 是 24.2.0，低于要求的 24.16，非交互安装脚本自行准备了 Node 24.21.0。

想要窗口

桌面伴侣

Windows 下 Hub 安装包
macOS 下 GitHub 的 DMG
首次可装本地 Gateway

官方推荐

安装脚本

macOS Linux WSL2
Windows 用 PowerShell
可加 --no-onboard

已经有 Node

包管理器

npm pnpm 或 bun
再运行 onboard
Node 版本见安装页

想要窗口就下载桌面伴侣。只在终端里用，就运行官方安装脚本。

安装并首次启动

你可以安装带窗口的桌面伴侣，也可以直接通过终端安装。Gateway 是负责接收消息、调用模型并把结果送回来的本地服务，第一次打开桌面伴侣时可以顺手准备。

想要窗口

Windows：下载并运行 OpenClawCompanion-Setup-x64.exe 或 OpenClawCompanion-Setup-arm64.exe。安装包带签名，里面有设置、托盘状态、聊天和 node 模式。
macOS：从 OpenClaw 的 GitHub releases 下载 OpenClaw 的 .dmg。优先用 dmg，也可以用 .zip。装好后打开 OpenClaw.app。这个版本如果没有 macOS 文件，按 macOS 应用页处理。

第一次打开时，可以让 OpenClaw 在这台电脑上准备 Gateway，也可以连接已经存在的远程 Gateway。

用终端安装

macOS、Linux 和 WSL2 使用：

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

Windows PowerShell 使用：

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

脚本会识别当前系统，在需要时安装 Node，再安装 OpenClaw 并进入初始引导。引导会带你完成第一次设置。

如果暂时不想进入引导，macOS、Linux 和 WSL2 改用：

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

Windows 使用官方的 -NoOnboard：

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

已经自行管理 Node 时，也可以使用 npm、pnpm 或 bun。npm 12 以及 npm 11.16 及以上运行：

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

npm 11.15 及更早版本需要去掉 --allow-scripts=openclaw。使用 pnpm 时要加 --allow-build=openclaw。具体差别以安装页为准。

安装完成后，依次运行下面三条命令：

openclaw --version
openclaw doctor
openclaw gateway status

openclaw --version 用来查看版本，openclaw doctor 用来检查常见环境问题，openclaw gateway status 用来查看 Gateway 是否正在运行。三条命令都有正常输出，才表示基础安装已经完成。

如果终端提示找不到 openclaw，通常是 npm 的全局 bin 目录没有加入 PATH。PATH 是终端查找程序的位置列表。可以用 node -v、npm prefix -g 和 echo "$PATH" 对照检查，把对应的 bin 目录加入 PATH，然后重新打开终端。

如果 ~/.openclaw 里已经有一份正在使用的配置，默认安装脚本会使用这份目录。想另外安装一份、避免改动原来的配置，可以运行非交互脚本并指定新目录：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/openclaw-omniproxy" --no-onboard

--no-onboard 是这个脚本的默认行为。2026-10-09 使用这条命令安装到 OpenClaw 2026.9.9。安装完成后，需要运行该目录 bin 里的 openclaw。

从 OmniProxy 取得连接参数

先确认 OmniProxy 正在运行，再打开它的模型列表，准备好以下三项：

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: 从 OmniProxy 当前模型列表整段复制

baseUrl 是 OpenClaw 发送模型请求的地址，要写到 /v1 结束。接入 OmniProxy 时，api 使用 openai-completions。只有这个模型确实通过 /v1/responses 工作时，才改成 openai-responses。

Model ID 是模型在列表中的完整标识。请按列表原样复制，如果里面有斜杠，斜杠也要保留。下面两个名字只是 2026-10-09 供应商文档里的对照，列表中没有就不要使用：claude-sonnet-5-5、gpt-6-luna。

即使网关不检查密钥，apiKey 仍然要填写内容，可以使用一串只在这台电脑上使用的占位字符。真实密钥不要提交进仓库。

填写工具配置

Provider 可以理解为 OpenClaw 用来找到模型服务的一组连接设置。这里把 Provider 命名为 omniproxy。

在终端执行下面的命令，并把地址、密钥和两个模型 ID 换成你自己的内容：

openclaw config set models.providers.omniproxy '{"baseUrl":"https://your-omniproxy-origin.example/v1","apiKey":"<YOUR_OMNIPROXY_API_KEY>","api":"openai-completions","models":[{"id":"claude-sonnet-5-5","name":"Claude Sonnet 5.5"},{"id":"gpt-6-luna","name":"GPT-6 Luna"}]}' --strict-json --merge

这条命令会把 Provider 和模型列表写入配置。命令成功后，不必重启 Gateway。

接着指定默认模型。模型引用由 omniproxy/ 和模型 ID 组成，ID 中原有的斜杠全部保留。如果模型列表里的 ID 比下面的短名字更长，就使用列表中的完整内容：

openclaw config set agents.defaults.model.primary '"omniproxy/claude-sonnet-5-5"' --strict-json

reasoning、input、cost、contextWindow、maxTokens 都可以不写。不填写时，文本模型会按默认方式处理。

同一套设置也可以直接写入配置文件。主配置中的 Provider 位于 models.providers。每个 agent 还可以有自己的 models.json；agent 是实际接收任务并调用模型的助手实例。文件位置是 ~/.openclaw/agents/ 下面、对应 agent 目录中的 agent/models.json。

如果这份 models.json 写了非空的 baseUrl，它会覆盖主配置中的地址。

检查安装

三条命令

openclaw --version
openclaw doctor
gateway status

配置

models.providers

baseUrl 以 /v1 结束
api 用 completions
模型至少写 id

选用

provider/模型

primary 用这条引用
密钥优先用环境变量
列表以网关为准

先确认命令找得到，再写入地址和模型。模型引用要带上 Provider 名字。

验证一个真实任务

进入一个普通项目目录，发送一条很短的消息。把命令中的模型引用换成你的完整 Model ID：

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "用一个词回复。"

--local 表示在本机运行这次 agent 任务，--model 指定本次使用的模型，--timeout 300 表示最多等待 300 秒。

终端里需要真正出现模型回复。2026-10-09，OpenClaw 2026.9.9 使用这条命令收到了回复。第一次调用可能需要一两分钟。

如果出现原文报错 Request timed out before a response was generated，先把 --timeout 调大，再发送一次。这通常表示等待时间不够，不代表地址一定写错。

短回复成功后，再让它读取一个你指定的本地文件。随后打开 OmniProxy 的调用记录，确认记录中的来源和模型 ID。只有版本号或 doctor 有输出，还不能说明模型连接已经配置完成。

安装

命令有回应

版本号能打出来
doctor 没有阻断
Gateway 状态可读

任务

它做了一件小事

例如读一个本地文件
回复不是报错
模型引用写对了

记录

网关看得到

来源是 OpenClaw
模型 ID 一致
密钥没有进仓库

版本命令有输出之后，还要收到一次真实回复。

常见错误

找不到 openclaw：把 npm 全局 bin 加进 PATH，然后重新打开终端。使用指定目录安装时，运行该目录 bin 里的程序。
node -v 低于 24.16：不必先卸载旧版本。检查安装脚本准备的 Node，或按安装页使用 24.16+、26.1+。建议使用 Node 26。
模型不出现：模型必须写在 models.providers 的 models 数组里，并且至少要有相同的 id。只写 agents.defaults.models 不会单独注册一个新模型。
返回 400，并提到 developer 角色：地址的主机不是 api.openai.com 时，保持默认，不要把 supportsDeveloperRole 设成 true。设成 true 仍会被覆盖。
很快超时：把 --timeout 加大到 300 秒以上，先不要改地址。
选了 gpt-6-luna 但工具调用失败：它支持 Chat Completions；函数调用在 Chat Completions 里只在 reasoning_effort 为 none 时支持。列表里的 ID 与此不同时，以列表为准。
地址连不上：确认 OmniProxy 正在运行，baseUrl 以 /v1 结束，并确认写入配置的地址可以访问。其他私网地址需要单独放行。
配好了仍然走到别的地址：检查该 agent 的 models.json 是否填写了另一个 baseUrl。

官方参考

安装步骤见 OpenClaw install。自定义 Provider 的设置方式见 Custom providers 和配置字段。示例中使用的模型 ID 可对照 Claude 模型总览和 GPT-6 Luna。

用你自己的 OmniProxy 配置替换每个占位符。不要发布真实密钥。

保存成功或 HTTP 200 不单独等同完整 Agent 兼容。请在 OmniProxy 调用记录中确认来源和模型。

官方来源 · OpenClaw ↗