OpenClaw 安装部署全攻略：从环境搭建到 API 配置的避坑指南

1. 为什么大家都在聊 OpenClaw但一半人卡在安装这一步OpenClaw 这个项目最近在技术圈里的热度确实有点离谱。不管你是刷技术社区、翻群聊记录还是看朋友转发的截图总能看到有人在讨论它。但有意思的是真正跑起来的人和不跑起来的人比例大概是三七开——七成的人卡在了安装环节。我自己前前后后在不同机器上装过五六次Windows、Linux、Mac 都试过踩过的坑能写满一页纸。所以这篇内容就是把我自己以及身边朋友的真实安装经验整理出来让你少走弯路。先说清楚 OpenClaw 是什么。简单讲它是一个开源的 AI Agent 框架能让你把大语言模型接入到各种聊天平台里比如飞书、Teams 这些然后通过对话的方式让 AI 帮你干活。它的核心价值在于“连接”——把模型能力和你日常用的工具打通。适合谁来参考如果你是开发者、运维、或者对 AI 工具感兴趣的技术爱好者想自己部署一套玩玩或者用在团队里那这篇内容就是写给你的。完全没接触过命令行的朋友也不用慌我会尽量把每一步都拆开讲。安装 OpenClaw 这件事说难不难说简单也不简单。它的依赖链条比较长Node.js 运行时、Docker 容器环境、API Key 配置、Channel 选择任何一个环节出问题都会导致启动失败。而且很多报错信息非常不友好比如agent failed before reply: session file locked (timeout 60000ms)这种第一次看到完全不知道从哪里下手。我见过太多人在这一步直接放弃了。但好消息是只要你理解了每个组件的作用和它们之间的关系整个安装过程其实是可以压缩到十几分钟以内的。关键是要知道“为什么需要这个”、“装错了会怎样”、“报错了怎么排查”。下面我会按照实际操作的顺序从环境准备到最终跑通一步步拆解。2. 安装前的整体思路与方案选型2.1 先搞清楚 OpenClaw 的依赖关系很多人一上来就照着某个教程敲命令结果装到一半发现版本不对、环境缺失又得回头重来。我的建议是动手之前先花两分钟理解一下 OpenClaw 的架构依赖。OpenClaw 的运行依赖三个核心组件Node.js 运行时OpenClaw 本身是基于 Node.js 开发的所以你需要一个合适版本的 Node.js 环境。根据我的实测Node.js 18.20.4 LTS 版本兼容性最好不建议用太新的版本有些依赖包还没跟上。Docker 容器环境OpenClaw 的某些功能模块比如沙箱执行、数据库服务是跑在 Docker 容器里的。你需要 Docker DesktopWindows/Mac或者 Docker EngineLinux。API Key这是让 OpenClaw 能调用大语言模型的关键。你可以用 OpenRouter 的 API Key也可以用 DeepSeek、智谱等国内模型的 API。不同模型的配置方式略有差异。这三个组件的关系可以这样理解Node.js 是发动机Docker 是底盘API Key 是油卡。缺一个车都跑不起来。2.2 为什么推荐 Docker 部署而不是裸装OpenClaw 支持两种安装方式一种是直接用 npm 全局安装另一种是通过 Docker 部署。我两种都试过最后稳定用的是 Docker 方案。原因有三第一环境隔离。OpenClaw 依赖的某些服务比如 Redis、数据库如果裸装在宿主机上版本冲突的概率很高。Docker 把每个服务隔离开互不干扰。第二迁移方便。你在开发机上跑通了想把配置搬到服务器上Docker 直接导出镜像和配置文件就行不用重新折腾环境。第三清理干净。不想用了直接把容器和镜像删掉宿主机上不留任何残留。裸装的话各种全局包和配置文件散落在系统里清理起来很烦。当然 Docker 方案也有代价——你需要先装好 Docker Desktop而 Docker Desktop 本身在 Windows 上就可能遇到virtualization support not detected的问题。这个后面会详细讲怎么解决。2.3 模型 API 的选择策略OpenClaw 支持接入多种大语言模型常见的选择包括 OpenRouter、DeepSeek、智谱等。选哪个我的建议是根据你的使用场景来定。如果你需要频繁调用、对成本敏感DeepSeek 的 API 性价比很高中文理解能力也不错。如果你需要多模型切换、灵活对比效果OpenRouter 是个好选择一个 Key 可以调用多种模型。如果你在企业环境里用智谱的 API 在合规性方面更稳妥。配置 API Key 的时候有个细节要注意不同模型的 API 格式不完全一样。比如 DeepSeek 的 API 端点、模型名称、参数格式都有自己的规范。你在 OpenClaw 的配置文件里填的时候要对照官方文档确认字段名和格式不然会报api error: 400 the supported api model names are...这类错误。3. 核心环境搭建实操Node.js 与 Docker 的安装细节3.1 Node.js 安装版本选择比安装过程更重要Node.js 的安装本身不复杂去官网下载对应系统的安装包一路下一步就行。但版本选择是个容易被忽略的坑。我强烈建议用Node.js 18.20.4 LTS这个版本。为什么因为 OpenClaw 的某些依赖包在 Node.js 20 以上的版本会出现兼容性问题而 16 以下的版本又缺少一些必要的 API。18.20.4 是目前验证过最稳定的版本。安装步骤以 Windows 为例去 Node.js 官网下载 18.20.4 LTS 的 Windows 安装包.msi 文件双击运行安装路径建议保持默认安装向导中有一个“Automatically install the necessary tools”选项不要勾选否则会额外安装一堆你用不到的东西还容易卡住安装完成后打开命令行输入node -v和npm -v验证如果你在 Linux 上比如 CentOS 7.9推荐用 nvm 来管理 Node.js 版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 18.20.4 nvm use 18.20.4注意CentOS 7.9 自带的 glibc 版本比较老如果你直接下载 Node.js 的二进制包可能会报GLIBC_2.28 not found的错误。用 nvm 安装可以规避这个问题因为 nvm 会下载预编译好的版本。安装完成后建议配置一下 npm 的镜像源不然安装依赖的时候速度会很慢npm config set registry https://registry.npmmirror.com这个操作在国内网络环境下几乎是必须的否则npm install可能要等十几分钟甚至超时。3.2 Docker Desktop 安装Windows 用户的最大拦路虎Docker 的安装是整个过程里最容易出问题的环节尤其是 Windows 用户。最常见的报错就是virtualization support not detectedDocker Desktop 直接启动不了。这个问题的根源是 Windows 的虚拟化功能没有开启。解决方法分两步第一步确认 CPU 虚拟化在 BIOS 里已经开启。重启电脑进入 BIOS 设置通常是按 F2、Del 或 F12找到 Intel VT-x 或 AMD-V 选项确保是 Enabled 状态。第二步在 Windows 里开启相关功能。打开“控制面板 → 程序和功能 → 启用或关闭 Windows 功能”勾选以下两项Hyper-VWindows 专业版及以上虚拟机平台Virtual Machine Platform如果你用的是 Windows 家庭版没有 Hyper-V 选项那就需要安装 WSL2Windows Subsystem for Linux 2。Docker Desktop 在家庭版上依赖 WSL2 来运行。安装 WSL2 的命令以管理员身份打开 PowerShellwsl --install执行完重启电脑然后再启动 Docker Desktop一般就能正常工作了。还有一个常见的报错是failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen。这个通常是因为 Docker Desktop 的后台服务没有正常启动。解决方法右键点击系统托盘里的 Docker 图标选择“Restart”如果重启无效打开“服务”services.msc找到 Docker Desktop Service手动启动还是不行的话卸载 Docker Desktop重启电脑重新安装实操心得Windows 上安装 Docker Desktop 之前先把 Windows 更新到最新版本。很多虚拟化相关的问题都是因为系统版本太旧导致的。另外安装完 Docker Desktop 之后建议在设置里把“Use WSL 2 based engine”勾上性能比 Hyper-V 后端好很多。Linux 上安装 Docker 就简单多了以 CentOS 为例sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo sudo yum install -y docker-ce docker-ce-cli containerd.io sudo systemctl start docker sudo systemctl enable docker安装完成后用docker run hello-world验证一下能正常输出就说明 Docker 环境没问题了。3.3 Docker Compose多容器编排的必备工具OpenClaw 在运行过程中可能需要同时启动多个服务比如主程序 Redis 数据库这时候用 Docker Compose 来管理会方便很多。Docker Desktop 自带 Compose 插件Linux 上需要单独安装sudo curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose sudo chmod x /usr/local/bin/docker-compose验证安装docker-compose --version。如果你需要跑 Redis 主从或者 MySQL 8.0 作为 OpenClaw 的配套服务用 Docker Compose 编排是最省事的方式。一个典型的docker-compose.yml大概长这样version: 3.8 services: redis: image: redis:7-alpine ports: - 6379:6379 volumes: - redis-data:/data mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: your_password MYSQL_DATABASE: openclaw ports: - 3306:3306 volumes: - mysql-data:/var/lib/mysql volumes: redis-data: mysql-data:这个配置文件定义了 Redis 和 MySQL 两个服务数据都做了持久化。你只需要把密码换成自己的然后docker-compose up -d就能一键启动。4. OpenClaw 部署全流程与 API 配置实战4.1 拉取镜像与初始化配置环境准备好之后就可以开始部署 OpenClaw 了。如果你用的是 Docker 方案第一步是拉取镜像docker pull openclaw/openclaw:latest拉取完成后需要创建一个配置文件。OpenClaw 的配置通常是一个.env文件或者config.yaml里面包含 API Key、模型选择、Channel 配置等信息。一个最小化的配置示例api: provider: deepseek key: sk-your-api-key-here model: deepseek-chat base_url: https://api.deepseek.com/v1 channel: type: feishu app_id: your_app_id app_secret: your_app_secret agent: name: my-assistant max_tokens: 4096这里有几个关键点要说明API Key 的获取如果你用 DeepSeek去官网注册账号后在控制台创建 API Key。如果用 OpenRouter同样在它的平台上生成 Key。注意 Key 的格式一般是sk-开头的一串字符复制的时候不要多带空格。模型名称的填写不同平台的模型名称不一样。DeepSeek 的对话模型叫deepseek-chatOpenRouter 上的模型名称格式是provider/model-name比如anthropic/claude-3-opus。填错了会报api error: 400 the supported api model names are...。Channel 的选择OpenClaw 支持接入飞书、Teams 等多种渠道。选哪个取决于你的使用场景。飞书在国内用得多配置相对简单Teams 适合企业环境。配置 Channel 的时候需要填写对应的 App ID 和 Secret这些在平台的开发者后台都能找到。4.2 启动容器与验证配置文件准备好之后启动 OpenClaw 容器docker run -d \ --name openclaw \ --env-file .env \ -p 3000:3000 \ -v ./config.yaml:/app/config.yaml \ openclaw/openclaw:latest启动后查看日志确认是否正常运行docker logs -f openclaw如果看到类似Server started on port 3000的输出说明启动成功了。如果报错根据错误信息排查。常见的启动报错及原因报错信息原因解决方法session file locked (timeout 60000ms)多个实例同时运行文件锁冲突停掉其他实例删除锁文件后重启api error: 400API Key 或模型名称配置错误检查 Key 是否有效、模型名是否正确ECONNREFUSED依赖服务Redis/MySQL未启动先启动依赖服务再启动 OpenClawCannot find moduleNode.js 依赖未安装完整重新执行npm install4.3 API 调用测试与模型切换容器跑起来之后建议先用一个简单的 API 调用测试一下模型是否正常工作。你可以用 curl 直接测试curl -X POST http://localhost:3000/api/chat \ -H Content-Type: application/json \ -d {message: 你好请回复一个测试消息}如果返回了模型的回复说明整条链路是通的。如果报错重点检查 API Key 和网络连接。关于模型切换OpenClaw 支持在运行时动态切换模型。你只需要修改配置文件中的model字段然后重启容器即可。如果你用的是 OpenRouter还可以在配置里设置多个模型通过参数来指定使用哪个。实操心得API 调用量大的时候建议在配置里设置max_tokens和timeout参数。max_tokens控制单次回复的最大长度设置太小会导致回复被截断比如在飞书里输出容易被截断就是这个原因设置太大又会浪费 token。一般 4096 是个比较平衡的值。timeout建议设置 30 秒以上因为有些模型的响应速度比较慢。5. 常见问题排查与避坑指南5.1 安装阶段的高频问题问题一Docker Desktop 启动失败提示虚拟化未检测到这个前面已经详细讲过了核心是 BIOS 虚拟化 Windows 功能 WSL2 三件套。补充一个细节如果你用的是 AMD 的 CPUBIOS 里的选项叫 SVMSecure Virtual Machine不是 VT-x。另外某些安全软件会占用虚拟化资源导致 Docker 无法启动临时关闭安全软件试试。问题二Node.js 版本不对导致依赖安装失败表现是npm install的时候报一堆gyp ERR或者node-gyp相关的错误。解决方法就是切换到 18.20.4 LTS 版本。如果你已经装了其他版本用 nvm 切换nvm install 18.20.4 nvm use 18.20.4然后删除node_modules目录重新npm install。问题三npm 安装速度极慢或超时这个基本就是网络问题。配置国内镜像源npm config set registry https://registry.npmmirror.com如果还是慢可以试试用cnpm或者pnpm替代 npm。5.2 运行阶段的典型故障问题agent failed before reply: session file locked这个报错的意思是会话文件被锁定了通常是因为上一次的会话没有正常结束锁文件没有被释放。解决方法找到 OpenClaw 的数据目录一般在./data或容器内的/app/data删除.lock后缀的文件重启容器如果你经常遇到这个问题可以在配置里把session_timeout调小一点让锁自动释放。问题API 返回 400 错误提示模型名称不支持这个就是模型名称填错了。不同平台的模型名称格式不一样一定要对照官方文档填写。比如 DeepSeek 的模型名称是deepseek-chat和deepseek-reasoner不是deepseek-v4或者deepseek-flash。OpenRouter 的格式是provider/model比如openai/gpt-4。问题飞书输出被截断这个是因为飞书的消息长度有限制而模型的回复可能很长。解决方法有两个一是在 OpenClaw 配置里设置max_tokens限制回复长度二是开启消息分段发送功能让 OpenClaw 自动把长回复拆成多条消息。5.3 独家避坑技巧汇总以下是我在实际操作中总结的几个技巧常规文档里不会写技巧一先用最小配置跑通再逐步加功能。很多人一上来就把所有功能都配上结果出了问题不知道是哪个环节的错。建议先用最简单的配置一个模型 一个 Channel跑通确认没问题后再加 Redis、数据库这些。技巧二日志级别调到 debug。OpenClaw 默认的日志级别是 info很多细节看不到。在配置里把日志级别改成 debug排查问题的时候能省很多时间。技巧三Docker 容器的时间同步。如果你在容器里跑定时任务可能会遇到时间不对的问题。启动容器的时候加上-v /etc/localtime:/etc/localtime:ro把宿主机的时间同步进去。技巧四备份配置文件。每次修改配置之前先备份一份改错了可以快速回滚。我一般用cp config.yaml config.yaml.bak这个命令。技巧五API Key 不要硬编码在配置文件里。用环境变量或者.env文件来管理避免 Key 泄露。如果你要把配置分享给别人记得先把 Key 删掉。6. 关于 Channel 选择与多平台接入的几点经验Channel 的选择其实比很多人想象的重要。它决定了你的 OpenClaw 能在哪个平台上跟用户交互也影响了整体的使用体验。飞书是目前国内用户最多的选择。配置流程是在飞书开放平台创建一个应用获取 App ID 和 App Secret然后在 OpenClaw 配置里填入。飞书的优势是消息推送稳定、API 文档完善缺点是消息长度有限制长回复需要分段。Teams 适合企业环境。如果你的团队已经在用 Teams把 OpenClaw 接进去可以无缝融入现有工作流。配置稍微复杂一些需要在 Azure AD 里注册应用但流程是标准化的。如果你需要同时接入多个平台OpenClaw 支持配置多个 Channel。每个 Channel 有独立的配置文件互不影响。我试过同时接飞书和 Teams运行很稳定消息也不会串。关于 Channel 的一个常见问题是权限配置。飞书应用需要申请消息发送、群组管理等权限Teams 应用需要 API 权限。这些权限在平台后台配置漏了会导致消息发不出去。建议配置的时候对照官方文档逐项检查。最后说一个实际使用中的体会Channel 的消息格式适配很重要。不同平台对 Markdown 的支持程度不一样飞书支持部分 Markdown 语法Teams 的支持更有限。如果你的 AI 回复里包含大量格式化内容建议在 OpenClaw 配置里开启格式转换功能把 Markdown 转成平台支持的格式不然用户看到的可能是一堆乱码。我个人在实际操作中的体会是OpenClaw 的安装和部署确实有一定的门槛但一旦跑通之后后续的维护和扩展其实很轻松。关键是把环境搭好、配置写对、日志看仔细。遇到报错不要慌大部分问题都能通过日志定位到具体原因。如果实在搞不定去项目的 Issues 页面搜一下报错信息大概率已经有人遇到过并给出了解决方案。