如果你最近在折腾个人 AI 助手，大概已经注意到 OpenClaw 这个名字出现在很多讨论里。它本质上是一套开源的本地 AI 助手运行时，把“对话、工具调用、自动化任务”集中在一个进程里托管，再通过配置文件接入各家大模型 API。我这次做的事情比较简单粗暴：把 OpenClaw 分别部署到华为云 Linux 服务器、Mac、Linux 桌面和 Windows 11 上，统一接入同一套大模型 API，并整理出一份可以直接抄的指南。
先说结论：这四个场景没有本质区别，核心都是“准备运行环境 → 拉取项目 → 写 API 配置 → 启动服务”，但每个平台都有各自的小坑。比如华为云安全组默认不放行端口，Windows 上路径反斜杠和中文目录会坑你一次，Mac 上则要注意权限弹窗。这篇文章就是围绕这些真实遇到的问题展开的。
1. 先搞清楚 OpenClaw 解决了什么问题
1.1 为什么需要一个本地 AI 助手运行时
大多数人接大模型 API，第一反应是写个 Python 脚本，调一下接口就完事了。但一旦你真的想把它当成一个常驻用的助手，事情就变复杂了：你要处理多轮对话、要让它调用外部工具、要管理 API Key、要记录日志、要让它开机自启、要在不同电脑上保持同样配置。这些需求堆起来，正好就是 OpenClaw 这类项目的切入点。
你可以把 OpenClaw 理解为“一个带大脑的进程”。它本身不生产回答，回答来自你配置的大模型 API。它负责的是 API 请求、上下文拼接、工具回调、会话持久化，以及把整个服务包装成可以被本地 CLI 或 HTTP 调用的形式。一句话概括：它把你和大模型 API 之间的“脏活累活”都包了，你只需要填好 API 地址和密钥。
1.2 四种部署方式的定位差异
我这次覆盖的四个场景，定位完全不同，不能一概而论。
华为云上的部署属于“服务器无头模式”。没有显示器、没有鼠标键盘，服务跑在云上，你通过 SSH 进去管它，日常通过 HTTP 接口或者其他终端调用。适合做无人值守的任务、定时脚本、或者给团队提供统一入口。
Mac 和 Linux 桌面属于“本地开发模式”。你可以直接命令行启动，看着实时日志，甚至调试配置。它们和服务器部署的唯一区别是带图形环境和用户登录会话，一些权限模型会不一样。
Windows 11 则是最容易出问题的一个场景。不是说 OpenClaw 在 Windows 上跑不起来，而是 Windows 的路径规范、PowerShell 的执行策略、防火墙弹窗、以及中文用户名默认目录，都会让第一次配置的人抓狂。后面我会单独展开讲。
1.3 有没有必要四个平台全装
我的建议是：如果你只是自己用，本地装一个就够了；如果你想要 7x24 小时可用，就把服务放到云服务器上；如果你办公机是 Windows、家里是 Mac，那么两边都装，用同一份配置同步，体验会非常统一。
我在实际使用中的体会是：本地端适合调试和临时查询，云端端适合跑定时任务和长期记录。两者共用同一个 API Key 没有太大问题，但要注意并发上限和费用，建议分别在两个环境配置不同的模型阈值，后面第六节会聊。
2. 部署前的准备：API Key、运行环境与项目拉取
2.1 大模型 API 接入的前置知识
在碰任何代码之前，你要先明确一件事：OpenClaw 不内置大模型，它需要你提供一个 API Key 和接口地址。不管用的哪家服务商，只要是兼容主流格式的 API 就都能接入。所谓“兼容格式”，简单说就是请求体和返回结构符合一套通用约定，以chat/completions和messages为核心字段。
你需要准备好的信息有四个：API 地址、API Key、模型名称、还有上下文长度限制。前三个直接在配置文件里填写，第四个用来调对话窗口，防止一次性塞太多历史消息导致请求超时或者费用飙升。
提示：别把 API Key 写进分享出去的配置里。我见过太多人截图时把 Key 漏出来，一小时内就被刷掉。建议用环境变量或者本地
.env文件保存。
2.2 跨平台环境差异与依赖清单
OpenClaw 的依赖并不复杂，但不同平台装起来姿势不一样。我整理了下面的对照表，你可以直接照着准备：
| 平台 | 核心依赖 | 安装方式 | 注意事项 |
|---|---|---|---|
| 华为云 Linux | Node.js 20+、Git、curl | apt或nvm | 建议手动装 Node，别用版本过老的 apt 源 |
| Mac | Node.js、Git、Homebrew | brew install node git | 首次安装 Homebrew 很慢，要有耐心 |
| Linux 桌面 | Node.js、Git | 发行版对应包管理器 | 某些发行版默认 Node 过老，必须升 |
| Windows 11 | Node.js LTS、Git、PowerShell 5.1+ | winget install或官网包 | 路径不能有中文，PowerShell 执行策略可能要调 |
不管哪个平台，装完 Node.js 后建议顺手验证一下版本。命令行输入node -v，输出v20或更高，再输入npm -v，确认 npm 也能用。版本太低会在启动时直接报语法错误，这个错最无聊。
2.3 项目获取与目录结构
项目获取方式我强烈建议用 Git 拉取，而不是下载压缩包。原因是 OpenClaw 更新很频繁，Git 仓库可以直接git pull升级，压缩包每次都要重新解压覆盖，容易丢配置。
拉取命令统一就是：
git clone https://example.com/openclaw/openclaw.git cd openclaw npm install这里不会贴真实的仓库地址，因为项目迁移过好几次，你只要去项目官方仓库页面复制 HTTPS 地址即可。安装依赖这一步，四个平台都差不多，本质就是npm install。如果安装过程中有编译型依赖失败，优先检查 Node 版本和网络连通性。
3. 华为云服务器部署 OpenClaw（Linux 无头模式）
3.1 创建云服务器实例的注意点
服务器部署是这次最推荐长期运行的方案。创建实例的时候，有几个地方别省：
第一，区域选离你近的，延迟低一些，管理也方便。第二，操作系统我选的是 Ubuntu 22.04 LTS，它对 Node.js 的兼容性最省心，CentOS 系也能跑但没必要给自己增加额外工作。第三，实例规格最低 2 核 4G，再低的话运行大模型 API 请求本身没问题，但日志多了以后内存容易吃紧。第四，带宽建议按量付费，因为 OpenClaw 只传文本数据量不大，长期用包月反而亏。
创建后先做的第一件事不是拉代码，而是更新系统：
sudo apt update && sudo apt upgrade -y sudo apt install -y git curl3.2 安装 Node.js 运行时
Ubuntu 自带的 Node.js 版本通常很老，直接用apt install nodejs装出来的版本大概率不满足要求。我推荐用 nvm 安装，这样以后切版本也方便：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" nvm install 20 node -v安装过程如果卡住，多半是网络问题。可以多试几次，或者检查服务器防火墙是否限制了出方向访问。这里要特别注意：不要改动系统默认 DNS，否则某些依赖源会解析失败，报错信息看起来像“找不到某个包”，实际就是解析不通。
3.3 启动服务的两种方式
依赖装好之后，先在前台启动一次验证配置：
node src/index.js看到日志里出现类似“listening on 3000”的字样，说明服务起来了。这个时候不要急着关，另外开一个 SSH 窗口测试接口是否响应。通过后，把进程切到后台长期运行。
最简单的后台运行方式是用nohup，但我不推荐。我更建议用 systemd 托管，这样服务器重启后会自动拉起，日志也有统一管理。创建一个服务文件：
sudo vim /etc/systemd/system/openclaw.service内容如下：
[Unit] Description=OpenClaw AI Assistant After=network.target [Service] Type=simple User=ubuntu WorkingDirectory=/home/ubuntu/openclaw EnvironmentFile=/home/ubuntu/openclaw/.env ExecStart=/home/ubuntu/.nvm/versions/node/v20.x.x/bin/node src/index.js Restart=always RestartSec=5 [Install] WantedBy=multi-user.target注意ExecStart里的 Node 路径一定要写绝对路径，可以用which node查看。填好之后执行：
sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw3.4 安全组与访问配置
华为云服务器有一个特别容易踩的坑：安全组默认只放行 22 端口，你的 3000 端口外面根本访问不到。所以启动服务后要先到云控制台的安全组规则里，添加入方向规则，放行 TCP 3000 端口。
如果你只是想自己用，不建议把接口完全公开。可以把安全组源地址设置为“我的 IP”，只让自己家或公司的 IP 能访问。服务端再配一个访问令牌，防止接口裸奔。
到这里，华为云部署就算结束了。后面所有平台共用同一套 API 配置，所以我建议把.env文件单独存一份备份，换平台时直接复制。
4. Mac 本地安装与调试
4.1 本机安装依赖
Mac 上最方便的方式是先装 Homebrew，然后一条命令搞定依赖：
brew install node git装好后同样验证版本。Mac 上有个小细节：如果之前装过旧版 Node，建议先彻底清掉再装新版，否则npm install时可能会因为权限问题报一堆EACCES错误。清理方式就是卸载旧包，再把/usr/local/lib/node_modules等残留目录删掉。
4.2 命令行启动与托盘模式
Mac 本地启动和服务器端几乎一样，差别在于你可以直接前台跑：
cd openclaw npm install node src/index.js如果你希望它像一个普通的桌面应用一样常驻在菜单栏，OpenClaw 支持在配置里开启桌面集成。启动后会多出一个菜单栏小图标，能直接查看当前会话状态和快速切换模型。这个功能在 Mac 上体验最好，Windows 上还略显粗糙，所以 Mac 我推荐开这个模式。
菜单栏模式启动的配置项大概是：
{ "desktop": { "enabled": true, "tray": true } }4.3 launchd 开机自启
Mac 没有 systemd，对应的托管机制是 launchd。如果你想让 OpenClaw 开机自动跑，可以写一个 LaunchAgent 配置文件：
vim ~/Library/LaunchAgents/com.openclaw.agent.plist核心配置就是指定程序路径和工作目录，然后launchctl load。但我实际用下来感觉，本地电脑不需要常驻，需要的时候手动启动反而更省心，因为 Mac 的休眠唤醒机制会让长期后台服务频繁重连。如果你不是重度使用，我个人建议本地就保持手动启动。
5. Linux 桌面端与 Windows 11 安装实录
5.1 Linux 桌面端：与服务器端有区别的几个细节
Linux 桌面端和云服务器最大的区别是图形环境和桌面会话。大部分发行版上，命令几乎一样，但有几个细节要注意。
第一个是 Wayland 与 X11 的影响。OpenClaw 如果启用桌面集成，在 Wayland 下某些全局快捷键可能不生效，得改用 X11 或者关闭快捷键功能。第二个是音频通知，如果你想让助手在任务完成时提醒你，需要确保系统有通知守护进程，比如notify-send。这个和 OpenClaw 本身无关，但缺失时你会以为它卡住了。
第三个是包管理器的 Node 版本太老。我试过在 Debian 系的稳定仓库直接装 nodejs，结果版本只有 16，启动直接报错。解决办法还是用 nvm：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 205.2 Windows 11 安装流程
Windows 11 是这次唯一让我多花半小时的平台，坑集中在三个地方。
第一，PowerShell 默认执行策略会拦脚本。你用官方安装命令时可能会遇到“无法加载文件，因为在此系统上禁止运行脚本”的报错。解决办法是以管理员身份打开 PowerShell，执行：
Set-ExecutionPolicy RemoteSigned第二，路径问题。默认用户名带中文，或者项目放在Program Files下，都会导致一些 Node 原生模块编译失败。强烈建议把项目放在纯英文无空格路径下，例如C:\Workspace\openclaw。
第三，Git 安装时的换行符选项。如果不小心选了“转换换行符为 CRLF”，拉下来的脚本可能在执行时出奇怪问题。建议保持默认或者选择 checkout 原样、commit 转 CRLF。
Windows 上安装依赖用：
cd C:\Workspace\openclaw npm install node src/index.js如果启动后 Windows 防火墙弹窗询问是否允许，记得点允许，否则局域网内其他设备调用不上。
5.3 跨平台配置文件同步
既然你在四个平台上都跑，最烦的就是每个平台各配一份。我的做法是：把.env文件放在私有仓库里，用 Git 同步，不写进共享的公开配置。
同时，把主配置openclaw.config.json做成平台无关的通用版本，只放 API 地址、模型名、超时时间这些共同项。平台差异项用环境变量覆盖，比如 Windows 上用OPENCLAW_DATA_DIR指向本地数据目录，Linux 上则用默认路径。
这样换机器时只需要拷两份文件，五分钟就能恢复一个完整环境。
6. 大模型 API 对接与参数调优
6.1 在配置文件中填入 API 信息
不管哪个平台，接入大模型 API 的核心动作都是填写同一个配置块。一个典型的配置大概长这样：
{ "api": { "baseUrl": "https://api.example.com/v1", "apiKeyEnv": "OPENCLAW_API_KEY", "model": "your-model-name", "temperature": 0.7, "maxTokens": 4096, "timeout": 60000 }, "session": { "historyLimit": 20, "maxContextChars": 12000 } }这里的apiKeyEnv意思是 API Key 从环境变量里读取，而不是硬编码在 JSON 里。你需要在.env文件里写一行：
OPENCLAW_API_KEY=sk-your-key-here我没有把 Key 直接写在主配置里，原因前面说过：你迟早会把配置截图发到群里，Key 一旦泄露就是钱的问题。
6.2 模型选择与关键参数
模型名称是你当前大模型 API 服务商提供的标识符，这个一定要填对，填错直接 404 或 400。不同服务商的命名风格差别很大，有的带版本后缀，有的按日期命名，建议先去服务商控制台确认准确字符串。
参数里我特别想提temperature。它控制回答的随机性，0 是最严谨，1 是很有创造性。如果你是拿 OpenClaw 做笔记整理、自动脚本，建议调到 0.3 以下；如果做头脑风暴类任务，0.8 更合适。我个人配置文件里没有用固定值，而是按不同会话设置了不同值，这个 OpenClaw 支持在会话级覆盖。
timeout设 60 秒是比较稳妥的起点。太短的话，遇到复杂任务或者 API 服务端排队，你会看到一堆超时错；太长的话，前端交互会出现长时间无响应。
6.3 流式输出与工具调用
OpenClaw 默认开启流式输出，也就是 API 返回一个 token 就推一个 token，而不是等全部生成完再一次性给。效果就是对话时字是一个一个蹦出来的，体验接近聊天软件。
但流式输出有一个副作用：如果你把输出重定向到日志文件，文件里会堆满半截内容，不利于排查。所以我建议在调试阶段关掉流式，让日志里只记录完整响应：
{ "api": { "stream": false } }工具调用是 OpenClaw 最好用的能力。你可以把本地脚本、定时任务、HTTP 请求注册成工具，让大模型在对话过程中自动触发。比如我注册了一个create_meeting工具，语音说“帮我创建明天下午三点的会议”，OpenClaw 会先解析意图，再调用对应函数，最后回传结果。这个链路需要 API 服务商支持工具调用格式，配置时确认tools字段能正常解析即可。
6.4 多模型切换与成本控制
我建议在配置里提前准备两到三个模型，而不是锁死一个。日常问答用便宜的小模型，复杂任务切到大模型。OpenClaw 支持热切换，运行时发一条指令就能换模型，不用重启。
成本控制的重点在上下文长度。maxContextChars设得太大，API 会把很多历史消息一并计费；设得太小，多轮问答容易丢失前文信息。我实测 12000 字符适合大多数对话场景，超过这个值我就手动开新会话。
7. 常见问题与排查实录
7.1 一套排查方法论
遇到问题先别慌，我的顺序永远是：看日志 → 看配置 → 看网络 → 看权限。OpenClaw 的日志在logs目录下，每次启动都会生成新文件。绝大多数问题，日志第一行就告诉你原因了。
我整理了一张高频问题表，按出现频率排序：
| 问题表现 | 常见原因 | 解决方案 |
|---|---|---|
| 启动报 “Cannot find module” | 依赖没装完整或 Node 版本不对 | 删除node_modules重新npm install |
| API 返回 401 | API Key 错、环境变量没加载 | 检查.env路径和变量名 |
| API 返回 404 | 模型名写错或接口路径不兼容 | 核对服务商文档中的精确模型 ID |
| 请求超时 | 网络差或 timeout 设得太短 | 调大 timeout，检查服务器出网 |
| 云服务器外部访问不了 | 安全组没放行端口 | 控制台添加入方向规则 |
| Windows 脚本不能运行 | PowerShell 执行策略限制 | 管理员执行Set-ExecutionPolicy RemoteSigned |
| 中文路径报错 | Node 模块编译/解析路径失败 | 项目移到纯英文路径 |
| 内存占用持续增长 | 会话历史太多或日志未清理 | 定期清日志，调小 historyLimit |
7.2 三个容易忽略的细节
第一个是时区。服务器默认时区可能是 UTC，定时任务会按 UTC 触发，导致你以为没运行。统一用timedatectl set-timezone Asia/Shanghai把服务器时区改成本地时区。
第二个是系统防火墙。很多 Linux 发行版自带的 ufw 默认关闭，但有的云镜像会自带防火墙规则，60% 的“外部访问不了”问题其实不是安全组，而是系统内防火墙。排查时先ufw status，再检查安全组。
第三个是.env编码格式。Windows 记事本保存的 UTF-8 文件默认带 BOM，会导致第一行配置项的名字前多一个隐藏字符，解析时报“unknown variable”。解决方式是用 VS Code 保存为“UTF-8 without BOM”，或者直接在终端里用命令行创建文件。
8. 实操总结与一些个人心得
8.1 我最后采用的目录与配置方案
折腾完这套环境，我现在的配置方式是所有平台共用一套结构：
openclaw/ ├── .env ├── openclaw.config.json ├── tools/ │ ├── capture.js │ └── notify.py ├── logs/ └── sessions/.env不管哪个平台都保持同一个文件名，里面只放密钥和本地数据路径。openclaw.config.json保持平台无关。tools/目录放自定义工具脚本，用相对路径互相引用。日志和会话数据默认在各自平台的数据目录里，互不干扰。
8.2 踩过几次坑之后的建议
如果你也想在多个平台跑这套，我强烈建议先把华为云服务器这套搭通，原因很简单：云端环境没有桌面干扰，日志纯净，最适合学习配置逻辑。服务器通了之后，Mac 和 Linux 桌面基本是照搬，Windows 才需要单独处理权限和路径。
关于 API Key 管理，我个人的习惯是给每个环境单独生成一个 Key，严格控制各自的额度。这样即使某个环境的 Key 泄露，也只损失一个环境，不至于全盘皆输。
关于日志，不要只在出问题时才想起来看。我每周会看一次服务器端的日志文件大小，顺手清理超过七天且没有 error 标记的日志。日志一直不清理，最终吃亏的是磁盘空间和排查效率。
8.3 还可以这样扩展
这套基础环境跑通之后，往下的玩法就多了。可以把华为云端的 OpenClaw 暴露成一个内部 HTTP 接口，配合定时触发器做晨报推送、代码评审、文档整理；也可以把它接进你的编辑器和终端，让它成为本地开发助手的后端；更进阶的是通过工具注册机制，把家里的智能设备也接进来，变成一个真正能“动手”的家庭助理。
我的经验是：不要一上来就追求复杂功能，先把“日常问答 + 简单工具调用”跑顺，再逐步加模块。OpenClaw 的配置系统足够灵活，但每一次改动都可能引入新的变量，控制变量的能力比功能多寡更重要。最后送大家一句话：多平台部署的真谛不是“到处都装”，而是“哪儿都能用”。
