如果你最近在折腾个人 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 的依赖并不复杂但不同平台装起来姿势不一样。我整理了下面的对照表你可以直接照着准备平台核心依赖安装方式注意事项华为云 LinuxNode.js 20、Git、curlapt或nvm建议手动装 Node别用版本过老的 apt 源MacNode.js、Git、Homebrewbrew install node git首次安装 Homebrew 很慢要有耐心Linux 桌面Node.js、Git发行版对应包管理器某些发行版默认 Node 过老必须升Windows 11Node.js LTS、Git、PowerShell 5.1winget 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. 华为云服务器部署 OpenClawLinux 无头模式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] DescriptionOpenClaw AI Assistant Afternetwork.target [Service] Typesimple Userubuntu WorkingDirectory/home/ubuntu/openclaw EnvironmentFile/home/ubuntu/openclaw/.env ExecStart/home/ubuntu/.nvm/versions/node/v20.x.x/bin/node src/index.js Restartalways RestartSec5 [Install] WantedBymulti-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启动直接报错。解决办法还是用 nvmcurl -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_KEYsk-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 installAPI 返回 401API Key 错、环境变量没加载检查.env路径和变量名API 返回 404模型名写错或接口路径不兼容核对服务商文档中的精确模型 ID请求超时网络差或 timeout 设得太短调大 timeout检查服务器出网云服务器外部访问不了安全组没放行端口控制台添加入方向规则Windows 脚本不能运行PowerShell 执行策略限制管理员执行Set-ExecutionPolicy RemoteSigned中文路径报错Node 模块编译/解析路径失败项目移到纯英文路径内存占用持续增长会话历史太多或日志未清理定期清日志调小 historyLimit7.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 的配置系统足够灵活但每一次改动都可能引入新的变量控制变量的能力比功能多寡更重要。最后送大家一句话多平台部署的真谛不是“到处都装”而是“哪儿都能用”。