稚一我先把话放前面：这篇不是官方文档的复读，是我自己在 Windows、macOS、Linux 三台机器上反复装 OpenClaw、接中转 API、连微信和飞书，踩了无数坑之后整理出来的实操记录。OpenClaw 这类本地部署的智能助手框架，最大的价值在于它能帮你把大模型、消息平台、任务脚本串成一条自动化链路，但每一次安装和接入，都可能被环境问题、模型鉴权、输出截断这类事情卡住。这篇教程会把三平台安装和第三方中转 API 站点的接入拆开讲清楚，该给参数给参数，该给步骤给步骤，适合正在研究本地部署 AI、想用 OpenClaw 做个人助理或团队机器人的开发者和运维朋友。
1. 项目概述：OpenClaw 到底是什么，为什么值得折腾
1.1 一句话讲清 OpenClaw 的定位
OpenClaw 本质上是一个自带工具调用能力的 AI 智能体运行框架，它解决的核心问题是“让大模型不仅能聊天，还能干活”。你可以把大模型接进来，同时把微信、飞书这类消息平台当作它的“入口”，然后在消息里直接给指令，OpenClaw 会调用内部配置好的工具链去完成翻译、查资料、生成文案、跑脚本这些任务，再把结果通过消息平台返回来。
它和单纯在终端里跑一个大模型完全不同。终端里的模型只能和你一对一对话，OpenClaw 却能变成一个独立后台服务，常驻运行，多个平台的多个用户都能同时触达它。我在部署完成的第三天，飞书群里同事就开始拿它当“值班助理”用了，这才真正体现它的价值。
1.2 为什么有人要在三个平台上分别安装
很多刚接触 OpenClaw 的朋友会问：我有一台服务器不就够了吗？问题的关键在于“入口”和“调试”环境往往是分开的。
服务器负责 7×24 小时运行，Windows 笔记本负责日常调试和看日志，macOS 工作机负责写 prompt 和改配置，Linux 小主机则适合放在公司内网做隔离部署。三平台安装的过程里，其实每一次环境准备、依赖安装、网络配置都会遇到不同的坑，提前搞清楚各平台的最佳安装路径，以后换机器或迁移部署时能节省大量时间。
1.3 为什么要接第三方中转 API 站点
大模型的官方 API 申请和额度管理对个人用户不太友好，所以很多人在本地部署时选择接入第三方中转 API 站点。这些站点本质上是一个大模型聚合网关，上游对接多家模型供应商，下游以统一 OpenAI 风格接口给开发者使用。
对 OpenClaw 来说，接中转 API 能带来三个直观好处：一是可以只维护一个 API Key 就能切换不同模型；二是中转站往往提供更细粒度的用量统计；三是在网络稳定性上通常比直连官方端点更好。接入后你只需要修改 OpenClaw 的模型配置指向中转站的 Base URL，其余逻辑完全不通。
1.4 本教程适合哪些人读
这篇教程以“能跑通”为第一目标。你已经有一点命令行基础但没独立部署过完整项目的人，可以照着步骤一步步来；有经验的开发者也建议看第 4 章和第 6 章的配置细节和避坑清单，不少坑是我实际跑生产环境才踩出来的。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 部署前准备：硬件、软件与 API 资源
2.1 硬件与系统要求
OpenClaw 本体是个消息路由加工具调度进程，对硬件要求不高。真正吃资源的是模型推理部分。如果你打算完全调用中转 API 或官方 API，那么一台 2 核 4GB 内存的机器就能稳定运行。如果计划接入本地 Ollama 跑 7B~14B 参数模型，建议至少 16GB 内存，有独立显卡更好。
我实测的几台机器配置如下，供参考：
| 机器用途 | 系统 | CPU/内存 | 部署方式 | 是否接本地模型 |
|---|---|---|---|---|
| 主力服务器 | Linux | 4核/8GB | Docker 容器 | 否，只接中转 API |
| 日常调试机 | Windows 11 | i5/16GB | WSL2 + Docker | 是，Ollama 跑 7B 模型 |
| 办公便携机 | macOS | M2/16GB | Homebrew + Docker | 否，接中转 API |
2.2 三平台的软件依赖对比
OpenClaw 官方提供 Docker 镜像，所以最省心的方式就是“系统只装 Docker，其余全部交给容器”。但 Windows 上跑 Docker 必须依赖 WSL2，macOS 虽然可以直接装 Docker Desktop，也经常遇到资源配置问题。Linux 则最干净，只要内核支持，直接安装即可。
| 平台 | 核心依赖 | 推荐版本 | 备注 |
|---|---|---|---|
| Windows | WSL2、Docker Desktop、Windows Terminal | WSL 内核 5.10+ | WSL2 校验失败是高频问题 |
| macOS | Homebrew、Docker Desktop（或 colima） | macOS 12+ | 注意内存分配至少 4GB |
| Linux | Docker Engine、docker-compose-plugin | Docker 24+ | 需要配置国内镜像源加速 |
2.3 大模型 API 的三种获取方式
OpenClaw 支持 OpenAI 协议和 Anthropic 协议两种模型接入方式。实际部署中，我见过三类取数方式，分别适合不同场景：
第一种是直接用官方 API Key，稳定可靠，但申请门槛和充值流程可能比较折磨。第二种是第三方中转 API 站点，只需要拿到中转站的 Base URL、自己的 API Key 和模型名，就能以统一接口调用多个模型。第三种是本地推理服务，比如 Ollama 和 vLLM，适合数据不出内网、追求零 API 成本的环境。
我个人的建议是：日常跑业务优先用中转 API，落地快，模型切换灵活；跑实验和调 prompt 时用本地模型，省着算力也别烧 token。
2.4 中转 API 站点的信息收集清单
接入中转 API 前，一定要把以下信息对照着确认清楚，否则后面容易反复返工：
- Base URL：中转站提供的接口根地址，通常是
https://relay.example.com/v1这样，注意是否带/v1。 - API Key：你在中转站创建的密钥，以
sk-开头居多。 - 可用模型名：中转站一般会用
deepseek-v3、gpt-4o、claude-sonnet这类别名，务必以站点文档为准。 - 协议兼容性：重点确认是否兼容 OpenAI 接口。OpenClaw 对 OpenAI 协议的适配最完整。
- 并发限制和余额查询方式：很多中转站有限流，建议先把并发配低再逐步调大。
拿到这些信息后，我习惯先在中转站自己的测试页里发一个请求，确认通顺了再去改 OpenClaw 的配置，这样能避免“模型坏了还是 OpenClaw 坏了”这种两头猜的问题。
3. 三平台安装实操：从零到跑通
3.1 Windows 安装：推荐 WSL2 + Docker
Windows 上安装 OpenClaw，最顺畅的路径是 WSL2 加 Docker Desktop，但这条路也是坑最多的。很多人执行安装脚本时都会碰到 could not safely verify the wsl2 environment 的报错，本质上就是 OpenClaw 在检查 WSL2 内核和 Docker 环境时没有通过。
解决思路分两步。
第一步，确认 WSL2 本身安装正确。在 PowerShell 管理员模式下执行：
bash复制wsl --install
wsl --set-default-version 2
装完后重启，再用 wsl --status 查看默认版本，输出里必须明确写 Default Version: 2。如果还是版本 1，需要把已安装的发行版转换一下：
bash复制wsl --set-version Ubuntu-22.04 2
第二步，确认 Docker Desktop 使用 WSL2 后端。打开 Docker Desktop 的 Settings -> General，勾选 Use the WSL 2 based engine。然后在 WSL 终端里执行 docker info，能看到 Operating System: Docker Desktop 和 Kernel Version 里的 WSL2 字样才算通过。
这两步完成后，OpenClaw 的 WSL2 校验基本就能通过。进入 Ubuntu 子系统，拉取镜像并启动：
bash复制docker pull openclaw/openclaw:latest
docker run -d --name openclaw -p 8080:8080 \
-v /opt/openclaw:/data \
--restart unless-stopped \
openclaw/openclaw:latest
Windows 下的安装要点是：不要跳过 WSL2 相关检查，也不要直接在 PowerShell 里跑 Linux 容器命令。老老实实进 WSL 环境操作，问题少一半。
3.2 macOS 安装：Homebrew 加 Docker Desktop
macOS 的安装路径相对平滑，主要注意两个地方：Docker Desktop 的内存配额和镜像加速。
先用 Homebrew 把基础环境补齐：
bash复制brew install --cask docker
brew install colima
如果你不习惯 Docker Desktop，Colima 是更轻量的替代方案，它会在 macOS 上创建一个 Linux 虚拟机来跑 Docker。启动命令如下：
bash复制colima start --cpu 2 --memory 4
docker context use colima
然后启动 OpenClaw 容器，命令和 Windows 下几乎一致，只是数据目录换成 mac 路径：
bash复制docker pull openclaw/openclaw:latest
docker run -d --name openclaw -p 8080:8080 \
-v ~/openclaw/data:/data \
--restart unless-stopped \
openclaw/openclaw:latest
macOS 上最容易犯的错是 Docker 虚拟机内存给得太小。默认 2GB 跑个大模型服务直接 OOM，容器会反复重启，日志看起来像极了应用层报错。建议 Colima 直接给 4GB 起步，Docker Desktop 的话在 Settings -> Resources 里把 Memory 调到 4GB。
3.3 Linux 安装：纯 Docker 一行命令完成
Linux 服务器是三类平台里最省心的，只要把 Docker Engine 装好，OpenClaw 基本不会遇到平台层面的问题。
以 Ubuntu 22.04 为例，装依赖、加仓库、装 Docker：
bash复制sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install -y docker-ce docker-compose-plugin
国内服务器拉镜像如果很慢，记得配置镜像加速，改 /etc/docker/daemon.json，填入镜像源地址后重启 Docker：
bash复制sudo systemctl restart docker
启动容器时我加了 --restart unless-stopped，这样服务器重启后 OpenClaw 会自动拉起，省去手动干预：
bash复制docker pull openclaw/openclaw:latest
docker run -d --name openclaw -p 8080:8080 \
-v /opt/openclaw:/data \
--restart unless-stopped \
openclaw/openclaw:latest
验证是否跑起来，浏览器访问 http://服务器IP:8080，能看到 OpenClaw 的初始化页面就说明成功。
3.4 安装后的初始化验证
不管哪个平台，容器起来后建议先做三件事：第一件，确认健康检查通过：
bash复制docker ps --filter name=openclaw
docker logs openclaw --tail 50
第二件，打开 Web 管理界面，完成管理员账号初始化，这个账号后续用来配置模型和消息渠道。第三件，创建或导入配置文件，把 API Key、模型参数写进去后再保存。进程只是壳，配置才是灵魂。
4. 中转 API 站点接入与模型配置
4.1 中转 API 的接入原理
中转 API 站点做的事情可以简单理解为“一个钥匙开很多扇门”。它内部帮你对接了多家模型供应商，对外统一暴露一个 OpenAI 兼容的 REST 接口。OpenClaw 不需要知道模型真正托管在哪里，它只把请求发出到中转站给的 Base URL，由中转站去完成上游调用和结果返回。
这种模式最明显的好处是“解耦”。你在 OpenClaw 里换模型时不需要改代码，只需要改配置里的 model 字段。哪天上游模型涨价或不可用，中转站会默默切换备用通道，对下游完全透明。
4.2 OpenClaw 连接中转 API 的配置方法
OpenClaw 使用环境变量或配置文件来管理模型接入。打开 Web 管理界面的 Settings -> Model Provider，选择 OpenAI Compatible，然后填入三段信息：
| 配置项 | 示例值 | 说明 |
|---|---|---|
| Base URL | https://relay.example.com/v1 |
中转站提供，注意保留 /v1 |
| API Key | sk-openclaw-xxxx |
中转站生成的个人密钥 |
| Model | deepseek-v3 |
必须是中转站支持的模型别名 |
用 docker run 启动时，也可以直接通过环境变量注入，适合脚本化部署：
bash复制docker run -d --name openclaw -p 8080:8080 \
-e OPENCLAW_BASE_URL="https://relay.example.com/v1" \
-e OPENCLAW_API_KEY="sk-openclaw-xxxx" \
-e OPENCLAW_MODEL="deepseek-v3" \
-v /opt/openclaw:/data \
--restart unless-stopped \
openclaw/openclaw:latest
配置完成后，在管理界面发一条测试消息，如果能在几秒内收到完整回复，说明链路已经通了。我通常会用“请用一句话介绍你自己”来测试，这句话短小且容易暴露长度适配问题。
4.3 多模型配置与切换
生产环境里我建议至少配置两个模型：一个“主力模型”负责正式任务，一个“轻量模型”用于日常闲聊。OpenClaw 支持在消息里通过特定指令临时切换模型，也可以在管理面板里手动指定默认模型。
比如主力用 DeepSeek 应对长文本和工具调用，轻量模型用快速模型处理常见问答。这个组合既能保证复杂任务的完成质量，又能控制整体 API 开销。多轮测试后，我一般会把轻量模型的并发上限调小，避免它抢占主力模型的任务请求。
4.4 本地模型（Ollama）的接入
如果你有一台还能跑的机器，把 Ollama 也接上，就能做到“不烧 API 也有一套可以随时调用的模型”。Ollama 本身就是 OpenAI 兼容服务，暴露在 http://localhost:11434/v1。在 OpenClaw 里新增一个 Provider，填上这个地址，模型名写你拉取的模型标签，比如 qwen2.5:7b。
需要注意，Ollama 默认只监听本机，如果 OpenClaw 跑在容器里，要用 host.docker.internal 访问宿主机服务：
bash复制OPENCLAW_BASE_URL="http://host.docker.internal:11434/v1"
最后在管理界面把本地模型和 API 模型分成两个 Provider，按消息来源或关键词路由，灵活性非常高。
5. 消息渠道对接：微信与飞书的实战记录
5.1 微信通道接入与常见问题
OpenClaw 接入个人微信通常采用第三方协议库，部署前先确认微信版本要匹配补丁版本，否则会出现无法扫码或收不到消息的情况。
配置项集中在 channels.wechat 下，核心参数包括：开启开关、是否需要扫码登录、回复超时时间。我建议把回复超时设置在 20 秒以上，因为复杂任务从消息接收、模型推理到工具调用，十几秒是常有的事，超时太短会把消息回复的状态误判为失败。
高频问题就是热搜词里的那个：OpenClaw 能发消息给微信，但微信发消息没回复。这个问题的核心排查思路是看“上行链路是否连通”。能发出去说明 bot 账户有消息发送权限；收不到回复则可能是消息监听端口没生效，或者回调地址被微信侧阻断。先看容器日志里有没有收到微信消息记录，再检查协议库的监听端口是否正常。
5.2 飞书通道接入与输出截断处理
飞书通道整体比微信稳定，但容易遇到长文本输出截断。OpenClaw 在飞书里输出容易被截断，原因是飞书消息接口对单条消息长度有限制，超过后会被静默截断或直接报错。
解决办法有几个。第一个是开启“分片发送”模式，OpenClaw 会把超过长度限制的内容拆成多条消息顺序发送。第二个是调整消息格式，飞书富文本和 text 类型的长度上限不同，全用 text 类型往往更稳。第三个是在系统提示词里要求模型输出精简，控制摘要长度。
我在实际使用中会把分片开关打开，同时给飞书应用设置一个足够大的卡片大小上限，两者配合后基本不会再出现“一条长报告只显示前半段”的情况。
5.3 消息不回复的通用排查流程
不管是微信还是飞书，遇到不回复时，先别急着改配置，按下面流程走一遍：
| 排查步骤 | 操作 | 判断标准 |
|---|---|---|
| 1. 容器状态 | docker ps 确认容器未重启 |
状态为 Up |
| 2. 渠道日志 | 查看 OpenClaw 日志中是否有消息接收记录 | 有收到但不回，则是模型或工具环节问题 |
| 3. 模型连通性 | 从管理面板直接发测试消息 | 直连可以但渠道不行，则是渠道配置问题 |
| 4. Key 配额 | 检查中转站剩余额度和并发 | 余额为 0 会表现为“不回复” |
这四步能定位九成问题。更深层的坑在于消息上下文过长，导致模型超时报错，OpenClaw 会静默丢弃异常，表现为“没回复”。遇到这种情况，给配置里的 max_tokens 和 context_window 设一个合理值就好。
6. 避坑清单与长期运维建议
6.1 WSL2 环境校验失败的处理
前面提过 could not safely verify the wsl2 environment 是 Windows 安装的第一大坑。这里再补两个容易被忽略的点。
第一，Windows 11 的 WSL 可能装了两个发行版，OpenClaw 的校验脚本只认默认发行版。必须用 wsl --set-default Ubuntu-22.04 把目标发行版设为默认。第二，Docker Desktop 的 “Use the WSL 2 based engine” 选项虽然勾了，但实际后端可能还是 Hyper-V，需要在 Settings -> Resources -> WSL Integration 里，把要和 Docker 联动的发行版开关打开。
6.2 日志查看与定位技巧
OpenClaw 的日志分三层：容器日志、应用运行日志、渠道调试日志。容器日志用 docker logs openclaw -f 查看，能看到启动信息和崩溃现场。应用运行日志通常在数据目录的 logs 文件夹下，按天滚动。渠道调试日志则在管理界面的 Debug 面板里临时开启，能看到每条消息的收发状态。
我最常用的技巧是“三层对照法”：当一条消息在中转站测试正常但在微信里失败时，同时打开容器日志和渠道调试日志，如果容器日志里能看到微信消息记录，那问题就在模型调用环节；如果连记录都没有，那就是微信通道没有监听到消息。
6.3 部署后的日常维护建议
最后聊聊装了 OpenClaw 之后怎么养好这套系统。
备份永远是第一位的。容器数据目录里存了配置、密钥和消息记录，我每天凌晨用 cron 做一次压缩备份，保留最近 7 天版本。恢复时只要挂载回同一个目录，配置和渠道登录状态都在。
模型成本控制也要提前想好。中转 API 按 token 计费，如果群里人多，容易被不限聊天的场景打爆额度。建议在 OpenClaw 里设置单用户单日消息上限，同时把“闲聊”话题路由到本地模型，把“干活”任务路由到 API 模型。
升级时别直接删旧容器。先拉取新镜像，用新容器名起一个实例，确认没问题后再切换端口或重命名旧容器。这样即使新版有不可预知的问题，也能在 30 秒内回滚到旧版本。
我个人在实际使用中感受最深的一点是：OpenClaw 这类框架的上手门槛，其实 90% 都不在 OpenClaw 本身，而在环境准备和周边服务的联通上。先把 Docker、WSL2、中转 API 三样东西理顺，后面所有操作都会非常顺畅。希望这篇记录能帮你少走几趟弯路。