OpenClaw Windows 原生安装部署

本页总览

OpenClaw Windows 原生安装部署与4All API聚合中转获取Claude apikey接入配置教程

OpenClaw（前身为 Clawdbot / MoltBot）是一个开源的本地优先 AI Agent 网关，可以将大语言模型连接到你的本地系统和消息平台（Telegram、WhatsApp、Discord、飞书、企业微信等），实现 24/7 全天候的个人 AI 助手。

这篇教程将带你完成从底层环境搭建、大语言模型 API 接入，到最终将其作为自动化机器人部署到飞书工作台的全流程（自定义 Base URL + API Key）获取Claude apikey接入 Claude 模型。

一、安装前准备

1.1 系统要求

Windows 10 / Windows 11
Node.js 22+ LTS
Git
至少 2GB 可用磁盘空间
4All API获取APIKey

1.2 安装 Node.js

访问 [Node.js 官网] https://nodejs.org ，下载 Node.js 22 LTS 的 Windows 安装包（ .msi ）。
运行安装程序，勾选 “Automatically install the necessary tools”。
安装完成后，关闭并重新打开 PowerShell，验证安装：

node --version   # 应显示 v22.x.x
npm --version    # 应显示版本号

提示：如果提示 node 不是可识别的命令，手动将 C:\Program Files\nodejs\ 添加到系统 PATH 环境变量，或者重启电脑。

1.3 安装 Git

在 PowerShell 中运行以下命令：

winget install Git.Git

(或从 [Git 官网] https://git-scm.com 下载安装，操作：在官网根据电脑架构（如 Windows x64）下载安装包，普通用户无需纠结高级设置，保持默认选项完成安装。安装时选择 “Use Git from the command line and also from 3rd-party software”。)

安装后关闭并重新打开 PowerShell，验证：

git --version

二、Windows 原生 PowerShell 安装 OpenClaw

2.1 配置 PowerShell 环境

以管理员身份打开 PowerShell（右键开始菜单 → Windows PowerShell (管理员)），依次执行以下命令：

# 允许脚本执行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 修改 npm 全局安装目录（避免权限冲突）
npm config set prefix "C:\npm"
npm config set cache "C:\npm-cache"

# 将新目录添加到用户 PATH
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\npm", "User")

执行完成后，关闭 PowerShell 并重新打开一个新窗口（让 PATH 生效）。

2.2 安装 OpenClaw

有两种方式，推荐先试方式一：

方式一：一键安装脚本

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

方式二：手动 npm 安装（如果一键脚本报错）

npm install -g openclaw

常见报错处理：

node.exe 应用程序错误：临时关闭 Windows Defender 实时保护，再重试。
spawn git ENOENT ：Git 未安装或 PowerShell 未重启，先装 Git 再重开窗口。
权限错误：以管理员身份运行 PowerShell。

2.3 运行引导向导

引导向导会依次询问你以下内容：

安全确认：用方向键选择 “Yes”（确认你理解 OpenClaw 有系统访问权限）。
安装模式：选择 “QuickStart” 快速完成基础配置。
选择 LLM 提供商：这里先随便选一个或跳过，也可以先选No先跳过。我们后面手动配置4All API的apikey服务。
配置消息平台（可选）：Telegram / WhatsApp / Discord / 钉钉 / 飞书 / 企业微信，QQ 等可以之后再配。
Shell 补全（可选）：建议选 Yes，加速命令输入。
包管理器：选择 npm。
后续选项一路选 “No/Default” 即可。

提示：如果引导过程中就想配置 API，可以暂时跳过 LLM 选择，等安装完成后手动编辑配置文件（见下一章），这样更灵活。

2.4 验证安装

在浏览器中访问 http://127.0.0.1:18789/ 。如果显示 “unauthorized”，在命令行运行 openclaw dashboard 命令，会打印一个带 ?token=… 的链接，用那个链接打开即可。

注意：如果 Gateway 安装为后台服务失败（需要管理员权限），可以用前台模式手动启动： openclaw gateway —port 18789

三、配置4All API代理获取Claude APIkey 调用大模型服务

使用4All API代理（API Proxy / Relay）接入 Claude，你需要两样东西：

Base URL ：4All API服务提供的 API 地址
API Key ：4All API服务给你的密钥

3.1 确认你的中转服务信息

信息项	示例值	说明
Base URL	https://sg.4All API.com	代理服务 API 地址
API Key	sk-xxxxxxxxxxxxxxxx	中转服务给你的密钥
支持的模型	claude-sonnet-4-5-20250929，GPT-5、Gemini-3-Pro 等	可在4All API模型广场支持哪些

关键点：4All API聚合服务兼容Anthropic 原生格式（ anthropic-messages ）和 OpenAI 兼容格式（ openai-completions ）。

3.2 编辑 OpenClaw 配置文件

OpenClaw 的配置文件默认位于： C:\Users\你的用户名.openclaw\openclaw.json 。用记事本、VS Code 或任何文本编辑器打开它。

3.3 配置方案 A：4All API服务兼容 Anthropic 原生格式（推荐）

如果支持 Anthropic 原生 API（ /v1/messages 端点），使用 anthropic-messages 格式。这是推荐方案，可使用 Claude 全部高级功能。在 openclaw.json 中添加或修改为以下内容：

清空 openclaw.json ，把下面这段加上了 “name”: “Claude Sonnet 4.5” 的终极完整版代码复制进去：

{
  "models": {
    "providers": {
      "4All API": {
        "api": "anthropic-messages",
        "baseUrl": "https://sg.4All API.com",
        "apiKey": "sk-在这里填入你在4All API生成的真实密钥",
        "headers": {
          "anthropic-version": "2023-06-01",
          "anthropic-beta": ""
        },
        "models": [
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": true
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "4All API/claude-sonnet-4-5-20250929"
      }
    }
  }
}

(再次提醒：别忘了替换你的 sk-… 密钥。)

保存退出，回到 PowerShell 再次运行：

第一步：重新设置本地模式在 PowerShell 里运行下面这行命令：

openclaw config set gateway.mode local

第二步：再次启动网关紧接着运行启动命令：

openclaw gateway --port 18789

保持这个窗口不要关，切换到你的浏览器刷新一下 Dashboard 页面（ http://127.0.0.1:18789 ），去跟 Claude 发第一条消息测试一下吧！

注意事项：

baseUrl 不要在末尾加 /v1 。OpenClaw 使用此格式时会自动拼接 /v1/messages 。如果 URL 已包含 /v1 ，最终会变成 /v1/v1/messages 导致 404 错误。
“api”: “anthropic-messages” 必须设置，否则默认走 OpenAI 兼容模式。
headers 中的 anthropic-version 一般需设置为 “2023-06-01” 。
模型 id 需与中转服务实际支持的模型一致。
如果中转服务在 thinking/reasoning 功能上不兼容，可在 headers 中将 anthropic-beta 设为空字符串来禁用。

3.4 配置方案 B：4All API服务兼容 OpenAI 格式

OpenClaw 2026 最新版，我们就必须严格按照它要求的“套娃”结构来写，同时还要补齐新版必须的 name 字段和路由配置。

下面是为你彻底重构并优化好的 OpenAI 兼容格式终极版，你可以直接复制使用：

{
  "gateway": {
    "mode": "local"
  },
  "models": {
    "providers": {
      "4All API": {
        "api": "openai-completions",
        "baseUrl": "https://sg.4All API.com/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxx",
        "models": [
          {
            "id": "gpt-4.1",
            "name": "GPT-4.1",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "4All API/gpt-4.1"
      }
    }
  }
}

💡 新版 json 代码核心优化点说明：

全面适配最新版架构：将 api 、 baseUrl 和 apiKey 全部收纳进 models.providers.4All API 节点下，彻底消灭 Unrecognized keys 报错。
保留 /v1 后缀：与 Anthropic 原生格式不同，OpenAI 兼容接口的标准路径就是以 /v1 结尾，所以 “baseUrl”: “https://sg.4All API.com/v1” 是完全正确的标准写法。
补充必填字段：增加了 “name”: “GPT-4.1” 。如果没有这个字段，Dashboard 控制面板会因为读不到显示名称而报错 received undefined 。
添加上下文参数：补充了通用的 contextWindow (上下文窗口) 和 maxTokens (最大输出)，让网关能更精准地控制记忆长度。
打通主模型路由：在 agents.defaults 中明确指定了默认调用的模型为 4All API/gpt-4.1 ，确保发消息时有模型接单。

3.5 两种格式对比速查

对比项	anthropic-messages（推荐）	openai-completions
api 字段	”anthropic-messages"	"openai-completions”
baseUrl 末尾	不加 /v1	要加 /v1
Prompt Caching	支持	不支持
Extended Thinking	支持	不支持
Tool Calling 稳定性	更好（原生格式）	可能有兼容问题
适用场景	中转支持 Anthropic 原生 API	中转支持 OpenAI 原生接口

建议：如果同时支持两种格式，优先选 anthropic-messages 。

四、anthropic主备模型自动切换配置文件示例

这是完美适配 2026 最新版 OpenClaw 的完整版 openclaw.json 代码，支持了主备模型自动切换，并且修复了所有的格式验证要求。

你可以直接一键复制，全部覆盖掉文件里的原有内容：

{
  "gateway": {
    "mode": "local"
  },
  "models": {
    "providers": {
      "4All API": {
        "api": "anthropic-messages",
        "baseUrl": "https://sg.4All API.com",
        "apiKey": "sk-请替换为你的4All API真实密钥",
        "headers": {
          "anthropic-version": "2023-06-01",
          "anthropic-beta": ""
        },
        "models": [
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": true
          },
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "contextWindow": 200000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "4All API/claude-sonnet-4-5-20250929",
        "fallbacks": [
          "4All API/claude-opus-4-6"
        ]
      }
    }
  }
}

⚠️ 关键提醒：粘贴完成后，千万别忘了把第 10 行的 sk-请替换为你的4All API真实密钥换成你实际生成的 Key。

五、Claude 和 GPT 组合在一起“双引擎”配置文件示例

把 Claude 和 GPT 组合在一起，正是 4All API 这种聚合中转平台最强大的玩法。这能让你的 AI 助手拥有“双引擎”，不仅能应对各种复杂的任务，还能做到极高的稳定性。

特别注意一个核心逻辑：因为 Claude（Anthropic 协议，不带 /v1 ）和 GPT（OpenAI 协议，带 /v1 ）的底层通信格式是完全不同的。在 OpenClaw 2026 最新版中，我们不能把它们混在一个筐里，必须把它们拆分成两个独立的“供应商（providers）” 。

下面为你精心调校的 “Claude + GPT 双引擎终极版” openclaw.json 配置。你可以直接把它加到你的知乎教程里，作为一个高阶玩法（进阶篇）展示给读者：

{
  "gateway": {
    "mode": "local"
  },
  "models": {
    "providers": {
      "4All API-claude": {
        "api": "anthropic-messages",
        "baseUrl": "https://sg.4All API.com",
        "apiKey": "sk-请替换为你的4All API真实密钥",
        "headers": {
          "anthropic-version": "2023-06-01",
          "anthropic-beta": ""
        },
        "models": [
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": true
          }
        ]
      },
      "4All API-gpt": {
        "api": "openai-completions",
        "baseUrl": "https://sg.4All API.com/v1",
        "apiKey": "sk-请替换为你的4All API真实密钥",
        "models": [
          {
            "id": "gpt-4.1",
            "name": "GPT-4.1",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "4All API-claude/claude-sonnet-4-5-20250929",
        "fallbacks": [
          "4All API-gpt/gpt-4.1"
        ]
      }
    }
  }
}

(再次提醒：别忘了替换你的 sk-… 密钥。)

保存退出，回到 PowerShell 再次运行：

第一步：重新设置本地模式在 PowerShell 里运行下面这行命令：

openclaw config set gateway.mode local

第二步：再次启动网关紧接着运行启动命令：

openclaw gateway --port 18789

保持这个窗口不要关，切换到你的浏览器刷新一下 Dashboard 页面（ http://127.0.0.1:18789 ），去跟 Claude 发第一条消息测试一下吧！

💡双引擎配置的核心亮点

在给读者讲解这段代码时，你可以提炼出以下几个极具吸引力的“硬核卖点”：

协议隔离，互不干扰：我们巧妙地在 providers 下定义了 4All API-claude 和 4All API-gpt 两个独立通道。一个走原生的 Anthropic 协议享受极致性能，另一个走标准的 OpenAI 兼容协议。
共用余额，无缝对接：虽然分了两个通道，但它们都指向 sg.4All API.com 并且使用同一个 apiKey ，消耗同一个账户的额度，管理起来极其省心。
企业级的“容灾备份”策略：在最底部的 agents.defaults 中，我们将公认写代码和逻辑最强的 Claude Sonnet 4.5 设为绝对主力（ primary ）。同时，将 GPT-4.1 放入备用池（ fallbacks ）。万一哪天 Claude 接口出现大面积网络波动，系统会在毫秒级无缝切换到 GPT-4.1 继续为你解答，保证你的飞书机器人 24 小时绝对不宕机！

⚙️ 核心配置字段对照说明

1. 网关基础设置 ( gateway )

“mode”: “local” ：明确告诉 OpenClaw 以“本地模式”运行。这是解决刚安装完时频繁报错 Gateway start blocked （网关启动被拦截）的关键开关。

2. 服务商与网络通道 ( providers.4All API )

这是连接本地网关与 4All API 中转服务的桥梁：

“4All API” ：我们在配置里自定义的服务商名称前缀，后续调用模型时会用到。
“api” : “anthropic-messages” ：指定通信协议格式。采用 Anthropic 原生协议，确保能完整调用 Claude 的提示词缓存（Prompt Caching）等高级特性。
“baseUrl” ：4All API 的服务器接口地址，注意末尾不要加 /v1 ，系统会自动拼接。
“apiKey” ：用于身份验证的专属秘钥（从平台获取）。
“headers” ：请求头参数。其中 “anthropic-beta”: "" 被刻意设置为空字符串，这是一个高级排错技巧，用于屏蔽部分中转服务不支持的测试版功能，防止出现 400 兼容性报错。

3. 模型精细化定义 ( models 数组)

在这个数组里，我们注册了两个具体的模型（Sonnet 和 Opus）：

“id” ：大语言模型在后端的真实请求 ID（如 claude-sonnet-4-5-20250929 ），必须与平台支持的模型库完全一致。
“name” ：（新版必填项）在 Dashboard 控制面板里展示给用户看的“花名”。不填这个会导致 undefined 报错。
“contextWindow” ：模型的上下文窗口大小（Claude 系列通常支持 200,000 tokens）。这能让网关知道什么时候该截断历史记录。
“maxTokens” ：单次回答允许输出的最大 Token 数。
“reasoning”: true ：能力标识，告诉 Agent 这个模型具备高级逻辑推理和思考能力。

4. 自动化调度策略 ( agents.defaults )

让你的 AI 助手永不掉线的核心策略区：

“primary” ：设定默认的主力干活模型（格式为服务商名称/模型ID ）。这里设为了性价比较高的 Sonnet。
“fallbacks” ：备用模型池。当主力模型遇到网络波动、接口限流或不可用时，系统会自动无缝切换到数组里的备用模型（如 Opus）继续作答，保障 24 小时全天候服务的稳定性。

六、进阶配置

5.1 多 Agent 使用不同模型

为不同任务分配不同模型，平衡费用和性能。例如：复杂任务用 Opus，日常聊天用 Sonnet。这通常可以在 Dashboard 界面中针对不同的 Agent 单独指定。

5.2 切换默认模型

如果想在命令行快速切换主力模型，可以使用：

openclaw models set <model_id>

5.3 配置消息平台（可选）

安装完成后可以随时添加消息平台，在终端输入以下命令并按提示操作：

openclaw configure

一、飞书工作台深度接入为例

1. 创建飞书应用：登录飞书开放平台，进入“开发者后台”，点击创建企业自建应用，填写机器人的名称与描述。
1. 开通基础权限：在应用设置中添加机器人能力。进入“权限管理”，搜索栏输入 IM: ，勾选开通所有与消息相关的权限。随后点击“创建版本”并确认发布（版本号可设为 1.0.0）。
1. 唤醒配置终端：回到 PowerShell 终端，输入 openclaw 配置命令重新进入设置界面。选择配置通讯渠道并添加飞书，系统会自动通过 npm 安装飞书插件。
1. 绑定飞书凭证：将飞书开发者后台提供的 App Secret 和 App ID 复制，并依次粘贴到 PowerShell 终端中。
1. 设置通信协议：通信方式选择配置最简单的 WebSocket 模式。根据你的实际需求，设置私聊和群聊的访问权限（例如选择 Open 允许团队所有人使用）。
1. 配置事件回调：返回飞书开发者后台，在“事件与回调”模块中，将订阅方式切换为长链接，并搜索添加接收消息事件。
1. 补充权限并生效：再次进入飞书“权限管理”，补充开通获取机器人基本信息等权限。最后，务必再次发布一个新版本，使所有配置正式生效。

二、测试与能力进阶

1. 最终联调测试：打开飞书 APP 或桌面端，在消息列表中搜索并打开你刚刚创建的机器人应用。尝试私聊发送消息，或将其拉入群聊中 @ 它进行提问，确认回复延迟和逻辑是否正常。
1. 扩展自动化技能：基础对话跑通后，你可以回到 OpenClaw 的配置界面，为它安装更多自动化 Skills （例如 AI 绘图、自动搜集资料等）。强烈建议仅安装官方或来源可靠的技能插件，以保障你的 API 额度与数据安全。

七、常用命令速查

命令	作用
openclaw gateway status	检查网关运行状态
openclaw gateway restart	重启网关
openclaw gateway —port 18789	前台模式启动网关
openclaw dashboard	打开控制面板
openclaw models list	查看所有已配置的模型
openclaw models set	切换默认模型
openclaw doctor	自动诊断和修复问题
openclaw doctor —fix	自动修复发现的问题
openclaw gateway logs	查看网关后台日志
openclaw logs —follow	实时追踪日志（排错必备）
openclaw status —all	查看完整诊断报告
openclaw configure	重新配置频道等选项
openclaw —version	查看当前版本

八、常见问题排查

Q1：修改了配置但没生效最常见的原因是已有会话缓存了旧配置。解决方法：

重启 Gateway： openclaw gateway restart
在新的聊天频道中测试（不要在旧会话中测试）。

Q2：请求返回 404 错误检查 baseUrl 配置：

如果 api 是 anthropic-messages ： baseUrl 不要加 /v1 。
如果 api 是 openai-completions ： baseUrl 要加 /v1 。

Q3：报错 “invalid beta flag” 或 “ValidationException” 某些中转服务不支持 Anthropic 的 beta 功能。请在配置的 headers 中显式禁用它：

"headers": {
  "anthropic-beta": ""
}

Q4：Gateway 无响应或端口占用尝试重启电脑，或者使用 openclaw doctor 检查端口冲突问题。

Q5：PowerShell 安装时 node.exe 报错

右键下载的文件 → 属性 → 勾选”解除锁定” → 应用。
临时关闭 Windows Defender 实时保护。
以管理员身份运行 PowerShell。

Q6：npm 安装报错 “spawn git ENOENT” Git 没有安装。先按 1.3 节安装 Git，然后关闭并重新打开 PowerShell 再重试。

Q7：如何查看具体的 API 请求错误实时查看日志（ openclaw logs —follow ），发送一条消息后观察日志中的错误信息，通常会显示 HTTP 状态码和错误详情。

九、安全注意事项

API Key 安全： openclaw.json 中的 API Key 是明文存储的。注意文件权限，不要分享或提交到 Git 等代码库。
绑定地址：Gateway 绑定到 localhost。确保配置中绑定地址是 127.0.0.1 （默认已是），不要改成 0.0.0.0 暴露到公网。
操作确认：建议在配置中加入 “exec”: { “ask”: “on” } ，让 OpenClaw 执行系统命令前征求您的同意。
运行环境：不要在存有高度敏感数据的主力设备上盲目运行未知指令，建议使用虚拟机或专用设备跑 Agent。
社区 Skills 审查：已有恶意 Skills 的报告，安装社区 Skills 前请务必先审查其代码行为。