OpenClaw 这名字最近在技术社区里冒头很快。先花一句话交代背景它是一款开源的、可以完整自托管的 AI 助理网关底层用 Node.js 开发核心定位是让 Slack、Discord、Microsoft Teams、Telegram 这类聊天平台和你的 Linux 服务器本地环境真正打通。你在群里随手发一句指令它能读文件、执行命令、调接口再把结果贴回群里——这跟普通聊天机器人有本质区别。这篇教程围绕 Linux 下的 OpenClaw 安装全流程展开从 Node.js 环境准备、源码拉取、依赖安装到接入 Anthropic 官方模型和本地 Qwen 模型、接入 Teams/Slack最后附上常见报错排查表。适合想在服务器上跑一个 7×24 小时 AI 助理的开发者也适合刚接触自托管服务、想完整走一遍部署流程的新手。1. 动手前先想清楚OpenClaw 到底解决什么问题1.1 它和普通聊天机器人的本质区别很多人第一次看到 OpenClaw 的演示视频第一反应是这不就是个能回消息的 bot 吗。真不是。普通聊天机器人是收到消息 → 调模型 → 回文本整个链路里模型接触不到你的任何真实环境。而 OpenClaw 做的是把对话和行动连起来它接收到一条消息后会先把消息解析成任务组织好上下文交给背后的大模型规划然后通过工具调用机制在本地真实执行——读写/home/user/下的文件、跑一段 shell 命令、请求某个 API全部可以做。这个能动手的特性决定了它适合做什么把 IM 群变成一个 AI 工作台在群里发把今天项目目录里改过的文件列出来它真的会去翻文件系统。做定时任务和信息聚合配合插件可以实现每天定时抓取内容、汇总后发到指定频道。充当个人知识库入口比如和 Obsidian 插件配合直接往你的笔记仓库里写东西。多 Agent 分工可以配置多个不同性格、不同权限的 agent在不同渠道分别跑。1.2 为什么选择自托管而不是直接用网页版OpenClaw 的设计哲学是你自己的助理跑在你自己的机器上。这带来几个实打实的好处第一是数据控制权。聊天记录、文件路径、命令执行日志都存在你自己的服务器上不会经过任何第三方中转平台。第二是成本可控。模型 API 的费用由你自己管理想用哪个 provider 就用哪个甚至可以在本地用小模型跑一些低成本场景。第三是定制空间。整个项目开源你完全可以改源码里的默认行为加自己的插件逻辑。1.3 Linux 部署比其他平台的优势OpenClaw 官方明确支持 Linux而且在 Linux 上部署体验最完整7×24 小时稳定挂机不像桌面系统那样容易受休眠、重启影响。资源占用低树莓派、低配云主机都能跑起来。配合 systemd 可以做成守护进程开机自启、崩溃自动拉起。后续加插件、跑本地模型、做端口转发、配防火墙Linux 的管理工具链最全。所以如果你手里有一台闲置的 Linux 服务器哪怕是 2 核 2G 的入门机型OpenClaw 放在上面跑是性价比最高的选择。2. 环境准备把地基先夯实这一步最容易翻车。很多人兴致勃勃 clone 完代码结果卡在依赖安装上来回报错。我在干净系统上实测过只要把下面的前置环境配好后面基本一路顺畅。2.1 Node.js 版本必须 18 或 20OpenClaw 是基于 Node.js 的项目对版本有硬性要求。官方建议使用 Node.js 18 或 20 及以上的 LTS 版本不建议用太旧的 16.x也不建议用太新的奇数版本比如 21、23因为部分原生依赖可能还没跟上。装之前先看下系统里有没有 Nodenode -v npm -v如果输出command not found或者版本低于 18直接通过 NodeSource 源安装这是我在 Ubuntu/Debian 上用过最稳的方式curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完再验证一次node -v npm -v注意不要用 apt 源里自带的旧 NodeUbuntu 20.04 默认是 10.x完全不够用。也不要图省事用nvm装完就忘了配置 PATH新手最常在这里栽跟头。如果你的发行版是 CentOS / RHEL则把上面第二行换成sudo yum install -y nodejs2.2 Git 安装与基础配置拉源码需要 Git这个一般系统里都有但也确认一下sudo apt-get install -y git git --version装完后做两件小事设置用户名和邮箱方便后续给项目提交插件或配置时不留空白身份git config --global user.name your_name git config --global user.email your_emailexample.com2.3 编译工具链与 Python可选但推荐OpenClaw 在安装依赖时有些 npm 包需要从源码编译原生模块系统里得有make、g和 Python。尤其在低配置机器上提前装好能避免一堆诡异的编译报错sudo apt-get install -y build-essential python3 python3-pipPython 本身不是 OpenClaw 运行的必要条件但很多插件比如涉及数据处理、调用外部脚本的扩展会依赖 Python 环境。顺手装上后面少踩坑。2.4 目录规划与普通用户权限强烈建议把 OpenClaw 安装在/opt/openclaw这种系统级目录下而不是塞在个人目录里。同时不要用 root 用户直接跑服务——这是安全底线。创建一个专用用户来跑服务sudo useradd -r -m -s /bin/bash openclaw sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw提示用专有用户运行的好处是即使 OpenClaw 被攻破或者插件出现严重 bug权限范围也仅限于该用户不会直接波及整个系统。3. 正式安装从拉源码到首次启动3.1 获取 OpenClaw 源码环境就绪后切到规划好的目录拉取官方仓库。OpenClaw 是活跃维护的开源项目主分支通常就是最新可用的版本。su - openclaw cd /opt/openclaw git clone OpenClaw 官方仓库地址 .如果你习惯先看版本再拉也可以到项目的 Releases 页面找最新的稳定 tag用git checkout切到对应版本。我个人的原则是生产环境尽量用 stable tag开发尝鲜才用主分支。3.2 安装项目依赖进入项目目录后第一件事是安装 npm 依赖。这里有几个人容易忽略的点cd /opt/openclaw npm install如果项目里有锁文件package-lock.jsonnpm install会自动按锁定版本安装保证可复现。如果网络环境不理想npm install经常卡住超时可以切换 npm 镜像源再试npm config set registry https://registry.npmmirror.com npm install注意不要因为 install 太慢就随意中断进程。npm 在处理大型依赖树时长时间停在node_modules阶段是正常的。实在超时可以加上--fetch-retries5 --fetch-retry-factor2增加重试容错。3.3 构建项目依赖装完后很多 Node 项目需要一次构建才能生成可执行文件。执行项目里定义好的构建脚本npm run build构建过程一般几十秒到几分钟不等取决于机器配置。看到类似Build completed successfully的输出就算成功。如果在这里报错九成是前面 Node 版本不对或者是编译工具链缺失回去检查 2.1 和 2.3 即可。3.4 首次启动前的配置初始化OpenClaw 的配置使用 JSON 文件管理。项目通常会提供一个样例配置先复制一份再改cp openclaw.json.example openclaw.json用你习惯的编辑器打开openclaw.json里面主要的字段包括模型 provider 配置、各聊天平台的接入令牌、agent 的角色定义、插件开关等。第一次启动前至少要把模型 provider 配好否则 OpenClaw 不知道该找谁要脑子。4. 接入大模型官方 API 与本地模型双方案OpenClaw 本身不包含模型它是个壳真正的对话和决策能力来自外部大模型。目前主流玩法有两种接 Anthropic 官方 API接本地 OpenAI 兼容服务。4.1 方案一接入 Anthropic 官方模型这是 OpenClaw 体验最完整、默认支持最好的方案。你需要去 Anthropic 控制台申请一个 API Key然后在openclaw.json里配置{ modelProvider: anthropic, model: claude-3-5-sonnet-20241022, apiKey: sk-ant-你的密钥, maxTokens: 4096 }maxTokens建议至少给 4096因为 OpenClaw 在复杂任务里需要生成工具调用参数输出长度太短就会莫名其妙出现话没说完的情况。注意API Key 千万不要提交到 Git 仓库也不要写在会被别人看到的配置文件里。建议通过环境变量注入比如在 systemd service 文件里用EnvironmentANTHROPIC_API_KEYxxx来管理。4.2 方案二接入本地模型以 Qwen2.5 为例不想把数据送到云端 API 的话可以在本机跑开源模型。最近很多人问qwen2.5-3b 怎么关联到 openclaw其实思路很简单OpenClaw 支持 OpenAI 兼容接口只要你本地有一个暴露 OpenAI 风格 API 的模型服务就能接入。最省事的本地模型运行方式是 Ollama。安装curl -fsSL https://ollama.com/install.sh | sh systemctl enable ollama systemctl start ollama拉取 Qwen2.5 3B 模型ollama pull qwen2.5:3b然后确认 Ollama 的 API 在 11434 端口正常工作curl http://localhost:11434/v1/models能看到模型列表就说明服务起来了。接着在openclaw.json里这样配{ modelProvider: openai-compatible, baseURL: http://localhost:11434/v1, model: qwen2.5:3b, apiKey: ollama }apiKey可以随便填一个非空字符串因为本地服务通常不做鉴权但 OpenClaw 的客户端库会要求这个字段存在。配好之后重启 OpenClaw它走的就完全是本地推理链路了。4.3 不同模型的选择建议我对两种方案的实际体验做个对比方便你按场景选维度Anthropic 官方 API本地 Qwen2.5Ollama推理质量高复杂工具调用稳定中等简单任务够用数据隐私数据会发送到云端完全本地不出机器成本按 token 计费只需电费和硬件硬件要求无任何机器都行建议至少 16G 内存跑 3B 量化版适合场景生产环境、多用户使用个人试用、隐私敏感场景我的建议是如果只是个人体验、折腾着玩本地 Qwen 完全够用如果是正经部署给团队用Anthropic 官方 API 的稳定性和工具调用准确率明显更高不容易出现模型理解不了工具参数的尴尬情况。5. 接入聊天平台让助理真正和你对话模型配好了但 OpenClaw 默认还没有入口。它需要接到一个聊天平台上你才能用日常通信软件和它交互。下面挑两个最常见的讲。5.1 接入 Microsoft TeamsTeams 的接入流程相对繁琐因为它依赖微软的身份注册体系。核心步骤是到 Azure 门户注册一个应用类型选机器人服务。拿到 Bot 的Client ID和Client Secret。在开放平台配置消息端点填写你的 OpenClaw 回调地址。在openclaw.json或环境变量里填入 Bot 凭据。Teams 最容易出问题的点是无法安全验证这一类证书或密钥报错。如果你遇到这个问题优先检查三处回调地址是否用了 HTTPSTeams 强制要求Client Secret 是否复制完整没有多余空格本地时钟是否准确证书校验失败有一半是系统时间不同步导致的。5.2 接入 SlackSlack 比 Teams 简单得多尤其是用 Socket Mode 模式时连公网回调地址都不用暴露。步骤去 Slack API 控制台创建一个新 App打开 Socket Mode。给 Bot 添加chat:write、app_mentions:read等权限。安装到工作区拿到Bot Token。配置到 OpenClawexport SLACK_BOT_TOKENxoxb-你的token export SLACK_APP_TOKENxapp-你的tokenSlack 走的是 WebSocket 长连接只要服务器能访问 Slack 的网关就能工作。实测下来这个方案最稳推荐作为第一个接入的渠道。5.3 权限与安全别给你的 AI 完全放开手脚OpenClaw 的能力越强越要小心授权范围。我一个朋友把它接入自己的服务器目录后发现 AI 能删除文件、能改系统配置——他自己都吓了一跳。这里给几个安全建议用专用系统用户跑 OpenClaw而不是 root。在配置里明确限制 agent 可访问的文件路径只开放工作目录。如果需要暴露回调地址用防火墙限制来源 IP别直接全开公网。定期备份openclaw.json和 agent 配置防止误操作改坏。6. 常见问题与排查实录我在多台 Linux 机器上安装调试 OpenClaw攒了一批高频报错和对应的处理办法。按这个表排查能省不少时间现象常见原因解决办法Cannot find module xxx依赖没装全或装的时候被中断删除node_modules和package-lock.json重新npm install启动后立即退出Node 版本不满足要求node -v确认版本升级到 18/20 LTSEACCES: permission denied用普通用户访问了 root 创建的目录检查目录属主chown -R 用户:用户 /opt/openclaw端口被占用默认端口被其他服务占用修改配置文件里的端口或停掉冲突进程Teams 接入报无法安全验证回调不是 HTTPS、密钥不对、系统时间不同步逐项检查重点是系统时间用date确认WebSocket 连接失败用了 NAT 网络但没配置代理、或平台域名不通检查网络连通性确认平台端 Socket Mode 已开启npm install卡死网络波动或依赖源不稳定切换 npmmirror 镜像源后重试模型调用一直超时baseURL 配错或本地模型服务没起来curl直接测模型服务地址确认返回正常消息有去无回平台回调地址写错或 token 没生效看 OpenClaw 日志journalctl定位报错行除了表格里的这些还有一个非常容易忽略的隐性坑磁盘空间。OpenClaw 加上 Node 依赖再叠加本地模型文件体积比想象中大得多。df -h看一下/opt分区剩余空间低于 20G 就要注意了本地模型拉取过程中写满磁盘会导致进程异常退出而且日志里不一定有明显的报错信息。排错的基本功是学会看日志。用 systemd 托管的话查看实时日志非常方便journalctl -u openclaw -f看到带ERROR或WARN的行再结合上面的排查表定位基本都能解决。7. 让 OpenClaw 长期稳定运行装好、配好、跑通只是第一步。一个合格的部署还得保证它开机自启、挂掉自动拉起、资源不失控。7.1 用 systemd 托管 OpenClaw手动用npm start跑服务的问题是终端一关服务就停而且开机不会自动启动。正确做法是写一个 systemd service。在/etc/systemd/system/openclaw.service里写入[Unit] DescriptionOpenClaw AI Assistant Gateway Afternetwork.target [Service] Useropenclaw WorkingDirectory/opt/openclaw ExecStart/usr/bin/node /opt/openclaw/build/index.js Restartalways RestartSec5 EnvironmentNODE_ENVproduction EnvironmentANTHROPIC_API_KEY你的密钥 [Install] WantedBymulti-user.target然后sudo systemctl daemon-reload sudo systemctl enable --now openclawRestartalways和RestartSec5这两行是精华进程意外退出后 5 秒自动拉起基本不用人工干预。7.2 资源限制与监控如果你的服务器只有 2G 内存跑 Node 服务再加上本地模型内存容易吃紧。可以给 service 加上资源限制MemoryMax1500M CPUQuota80%不要小看这两行。有一次我在 1G 内存的小机器上跑忘了限制内存OOM Killer 直接把进程杀了日志里连 ERROR 都没有只有一条 kernel 日志提到被杀死。加上MemoryMax后OpenClaw 会在接近上限时主动触发 GC反而稳定很多。7.3 后续还可以怎么玩OpenClaw 部署完成只是起点。我跑了一周之后又给它接了几个实用扩展Obsidian 插件让它可以往我的知识库直接写入笔记摘要定时任务每天早晨把项目仓库的最新 commit 汇总发到 Slack多 Agent 配置里分出一个写作助手、一个运维助手权限和模型各自独立。这些玩法官方文档都有对应的配置条目顺着插件目录挨个试即可。我个人在实际操作中的体会是OpenClaw 这个项目最大的价值不是又多了个聊天机器人而是它把 AI 从回答问题推进到了完成事情。安装过程本身不难难的是你对权限边界的把控、对模型能力的合理预期、以及对运维细节的耐心。建议第一周先跑在本地小模型上摸清它的行为习惯和日志套路再切换到更强的模型、接入更多的平台。这样即便出问题你也能从容地按日志一步步排查而不是对着一个完全黑盒的进程干着急。