OpenClaw 这个项目最近在智能体玩家圈子里讨论度挺高。简单说它是一套把大模型、技能插件和任务流程串起来运行的开源智能体框架解决的是“模型有了、API 也有了但怎么让它稳定地替我干活”的问题。它的部署逻辑并不复杂真正让新手卡住的反而是 WSL2 环境状态、Node.js 版本、Ollama 端口这些细节。这篇文章我不打算抄官方 README而是把我实际部署 OpenClaw 从零到跑通的完整过程写下来包含环境检查、模型关联、Windows 端 Companion 配置、常见报错处理以及内网私有化部署的要点。适合三类人本地大模型玩得顺但没碰过 agent 框架的开发者、想在内网部署私有助手的技术运维、以及嫌 WebUI 不够灵活、想自己定制技能的折腾党。1. 项目概述与部署思路1.1 OpenClaw 到底是什么先拆清楚再动手很多人一听到“部署 OpenClaw”就以为是装一个软件其实它是一整个运行时体系。我的理解是OpenClaw 本质上是一个“智能体编排框架”核心由四部分组成。第一是运行时核心负责调度、任务队列、会话管理和日志输出。你可以把它想象成一个管家接收你的指令拆解步骤然后调用后面的工具去执行。第二是 Skill 管理器Skill 是 OpenClaw 的插件单位一个 Skill 就是一组“提示词模板 可执行脚本 参数定义”本质上是赋予智能体一项具体能力比如读 PDF、查数据库、写代码、调 API。第三是模型接入层OpenClaw 本身不内置大模型它通过 OpenAI 兼容接口去对接各种模型服务Ollama、vLLM、DeepSeek、Qwen 系列都能接进来。第四是客户端和 Companion包括 Web 控制台、命令行工具Windows 上还有一个桌面伴侣程序用来做系统级交互和剪贴板、文件操作。把这四块想清楚就明白部署不是一个“装完就结束”的动作而是把模型、技能、运行时、客户端四条线接到一起。5 分钟能跑通指的是在环境基本干净、模型已经就绪的前提下完成串联如果是从头开始装依赖、下载模型那第一次花 20 分钟到半个小时非常正常别被网上的演示误导。1.2 为什么说“5 分钟部署”不是虚的先说结论OpenClaw 的设计目标就是“配置驱动 命令先行”只要依赖满足整个启动流程可以压缩到五步以内装包、初始化、填模型地址、启动服务、跑一条测试任务。它的部署逻辑跟传统单体应用不太一样。OpenClaw 不强制你一开始就搞数据库、搞容器编排默认情况下组件可以先用轻量进程方式跑起来。官方把这种形态叫“本地优先模式”也就是所有组件默认绑定 localhost不依赖外部系统数据先落在本地目录。这种模式的好处很明显第一是排障链路短出问题可以直接用日志定位第二是没有分布式系统的心智负担适合日常开发和测试第三是后续想上生产环境可以在同一套配置基础上叠加 Docker、反向代理、HTTPS 证书不需要推倒重来。所以 5 分钟部署的前提是你的机器已经具备 Node.js 20 及以上运行环境模型服务比如 Ollama已经装好并下载了至少一个小参数模型网络能正常访问 npm 和 Git 仓库。满足这三条剩下的操作确实就是复制粘贴几条命令的事。1.3 部署方案选型不是所有环境都适合同一套流程OpenClaw 社区里常见的部署方式有四种我在实际测试里都跑过各有明显的适用场景。方案适用场景优点需要注意的点Linux / macOS 裸机部署开发机、内网服务器环境干净、权限清晰、性能损耗最小需要手动处理 Node 版本和系统依赖Windows WSL2 部署大多数 Windows 桌面用户与 Windows 文件互通可配合 Companion 使用WSL2 状态和网络互通是最容易踩坑的地方Docker Compose 部署生产环境、内网私有化组件隔离、一键启动、迁移方便需要理解容器端口映射和数据卷挂载Termux 手机端部署安卓设备、轻量体验便携、能跑小模型资源受限仅适合演示和简单任务我的建议是第一次部署别上来就用 Docker。虽然容器方案看起来很干净但你在容器里排障时日志路径、网络模式、挂载目录都会变成额外变量。先在裸环境跑通确认模型连接和 Skill 功能正常再考虑容器化。Windows 用户我推荐直接用 WSL2 作为运行环境后面会详细说怎么检查 WSL2 状态。2. 环境准备与前置检查2.1 最小依赖清单少一样都会卡住列一个我实测下来的最小依赖清单每一项都不是可选的。Node.js 20.x 或更高版本npm 9 以上。OpenClaw 的运行时是 Node 实现的版本太低会出现语法不兼容和依赖安装失败。Git用来拉取官方仓库和 Skill 仓库。模型服务推荐 Ollama下载安装后需要把至少一个模型拉取到本地我习惯用 qwen2.5:3b 起步资源占用小、中文理解够用。命令行终端Windows 上强烈建议用 PowerShell 或 Windows Terminal而不是老旧的 CMD因为后者对 UTF-8 和 ANSI 颜色支持有问题。一个空闲端口默认情况下 OpenClaw 服务监听 3000 端口Ollama 监听 11434 端口。检查命令并不复杂我每次部署都会先执行这三条node -v npm -v git --version如果 Node 版本低于 20去 Node.js 官网下载 LTS 版本重新安装即可。注意 Windows 上装完 Node 后要重新打开终端否则环境变量不会刷新。2.2 Windows 用户必查的 WSL2 状态搜索热词里有一条“OpenClaw 无法安全验证 sl2 环境请在 PowerShell 中运行 wsl -- status”这个问题我遇到过太多次了。OpenClaw 在 Windows 上运行时经常需要调用 WSL2 里的工具链如果 WSL2 没有正确启用程序会给出“无法安全验证 WSL 环境”之类的提示。先用 PowerShell 执行状态检查wsl --status正常输出会包含“默认版本: 2”和当前发行版信息。如果显示“适用于 Linux 的 Windows 子系统没有已安装的分发版”或者版本号是 1你需要先启用 WSL 功能并安装一个发行版。在管理员 PowerShell 里执行wsl --install安装完成后重启系统再执行wsl --status确认默认版本为 2。还有一个容易被忽略的地方Windows 的“虚拟机平台”功能必须开启否则即使 WSL2 安装成功运行 OpenClaw 时也会出现性能异常或直接无法启动。检查方式是“控制面板 - 程序 - 启用或关闭 Windows 功能”找到“虚拟机平台”和“适用于 Linux 的 Windows 子系统”确保两者都勾选。2.3 模型服务的两种接法本地推理和 API 都能用OpenClaw 社区里常被问到一个问题“这个框架是不是只能用接入 API 的方式使用算力”答案是否定的。模型接入层设计成 OpenAI 兼容格式目的正是为了同时兼容“本地推理”和“远端 API”两条路。本地推理的典型路径就是 Ollama。装好 Ollama 后拉取模型ollama pull qwen2.5:3b启动服务后OpenClaw 只需要把模型提供方配置为http://localhost:11434/v1API Key 可以随便填一个占位符因为本地服务不做鉴权。这种方式的数据完全不出机器隐私性最好但算力受限于本地硬件。API 方式则指任何提供 OpenAI 兼容接口的服务包括云厂商的模型 API、内网自建的 vLLM 服务、DeepSeek 的开放接口等。只需要在配置里填上 base_url 和 API KeyOpenClaw 就能把请求转发过去。这种方式适合没有 GPU 的机器或者需要使用更大参数模型的场景。后面第 5 章我会专门讲算力选型的取舍这里先记住一个结论OpenClaw 不挑算力来源它只要求模型服务长成一个“标准接口”的样子。2.4 端口与网络规划部署前先想清楚这几个数字部署前花两分钟理清网络规划能省掉后面一半的排障时间。我习惯用一个表格记下所有关键地址和端口。组件默认地址端口说明OpenClaw 运行时localhost3000主服务 HTTP 端口Ollama 模型服务localhost11434本地推理服务OpenClaw Companionlocalhost3100Windows 桌面端通信端口Web 控制台localhost3000/console浏览器访问地址如果所有组件都在同一台机器上跑直接保持默认即可。如果需要跨机器调用比如 OpenClaw 装在服务器上、Ollama 装在另一台 GPU 机器上关键是把 Ollama 的监听地址从默认的 127.0.0.1 改成 0.0.0.0然后在 OpenClaw 配置里填http://对方IP:11434/v1。Windows 防火墙可能会拦截跨机器访问部署前要放行对应端口或者直接把两台机器加入同一个受信任网络。3. 核心部署实操流程3.1 获取 OpenClaw两种方式我实测都可行获取 OpenClaw 本体有两种主流方式我分别说下体验。第一种是 npm 全局安装。在终端执行npm install -g openclaw/cli装完以后执行openclaw --version验证版本号。全局安装的好处是命令随处可用适合开发机缺点是升级时要重新执行 npm 安装命令并且 Node 全局目录需要写入权限Windows 下偶尔会遇到权限报错。第二种是 Git 仓库方式。把官方仓库克隆到本地然后安装依赖git clone https://github.com/openclaw/community.git ~/openclaw cd ~/openclaw npm install仓库方式的好处是升级方便git pull就行而且可以随时查看源码和社区 Skill 示例。坏处是占用的磁盘空间会大一些安装依赖也比较久。我个人的习惯是测试环境用 npm 全局包正式项目用仓库方式因为仓库目录里可以直接放自定义 Skill 和配置文件结构更清晰。3.2 初始化配置回答几个问题就生成基础配置OpenClaw 提供了一个交互式初始化命令运行以后会通过问题引导生成配置文件openclaw init它会依次询问选择模型提供方Ollama、OpenAI 兼容 API、OpenAI 官方等、填写模型服务的 base_url、填写 API KeyOllama 可以留空、选择默认模型名称、指定 Skill 目录。我测试时的回答是提供方选 Ollamabase_url 填http://localhost:11434/v1模型名填qwen2.5:3bSkill 目录用默认的~/openclaw/skills。初始化结束后会在当前用户目录下生成一个配置文件夹里面是一个 JSON 格式的配置文件。这个文件里的 api_key 字段是明文存储的所以如果是放在多人使用的服务器上一定要把配置文件权限设置成仅当前用户可读写chmod 600 ~/.openclaw/config.jsonWindows 上则要为用户目录设置 ACL 权限避免其他账户读取。这一步很多人会忽略但它和内网安全直接相关。3.3 把模型“接”进 OpenClaw先验证接口再启动配置完成后先别急着启动 OpenClaw先用 curl 验证模型服务是不是真的通着。检查 Ollama 是否正常curl http://localhost:11434/api/tags如果返回一个包含模型列表的 JSON说明 Ollama 没问题。再测试 OpenAI 兼容接口curl http://localhost:11434/v1/models这一步能提前暴露端口监听、跨机器访问、API 路径错误这三类问题。如果 OpenClaw 配置的是内网 DeepSeek 服务或 vLLM 服务同样先用 curl 打一下对方的 /v1/models 路径确认返回格式是 OpenAI 风格。确认无误后再执行启动命令。这里还要提一下 Skill 与模型的关系。很多新手以为模型参数大就能自动干各种活其实 OpenClaw 的工作方式是模型负责语义理解和决策Skill 负责具体执行。比如你给 OpenClaw 配一个“DeepSeek Harness 技能”本质上就是把一组针对 DeepSeek 模型的调用模板和工具脚本放进 Skill 目录。模型决定调用哪个 SkillSkill 决定具体怎么做。所以在 3.2 初始化时指定 Skill 目录后面导入技能时就是把这个目录里的子文件夹放进去的事。3.4 启动服务并跑通第一条任务启动服务只需要一条命令openclaw serve看到日志输出“Server listening on http://localhost:3000”和“Model provider connected”这两行就说明基本跑通了。启动后我用两种方式验证一种是通过浏览器访问http://localhost:3000/console打开 Web 控制台在聊天框里输入“你好请用一句话介绍你自己”另一种是通过命令行客户端openclaw ask 帮我计算一下 23 乘以 47 等于多少并给出计算过程OpenClaw 会通过 Skill 调度依次执行“调用计算器 Skill”“读取结果”“组织回答”这几个步骤。第一次跑任务时我建议盯着终端日志看能直观看到模型请求发送、Skill 调用链、耗时数据这比事后看链路追踪有用得多。3.5 Windows Companion 的连接配置坑比想象中多Windows 上部署 OpenClaw很多人会顺手安装 Companion 桌面端用来做系统级交互比如读取剪贴板、操作本地文件、唤起其他应用。Companion 与主服务之间走 WebSocket 通信默认端口是 3100。Companion 的配置界面里需要填三个字段主服务地址、通信端口、访问令牌。主服务地址不能填localhost因为在 Windows 桌面端和 WSL2 里的 OpenClaw 服务互通时localhost指向的是不同环境。正确做法是在 WSL2 里执行hostname -I拿到 WSL 的 IP然后在 Companion 端填这个 IP。如果不开跨环境通信也可以在 OpenClaw 配置里开启host.docker.internal之类的映射不过这个要看具体网络模式不如直接用 IP 来得稳。我踩过的坑是访问令牌Companion 首次连接时要求配对配对码只能使用一次如果超时或输错必须重新生成。遇到“Companion 已连接但无法交互”这种诡异情况先检查配对令牌状态再检查 3100 端口防火墙规则90% 的问题都出在这两处。3.6 手机端部署Termux 是个可选的尝鲜方案搜索热词里有人问“如何用 Termux 安装 OpenClaw 手机版”我也顺手测过。Termux 是安卓上的终端模拟器可以安装 Node.js理论上能跑 OpenClaw但受手机 CPU 和内存限制只能承担轻量任务。安装步骤大致是在 Termux 里先更新包管理器安装 Node.js LTS 版本再用 npm 安装 OpenClaw。模型方面不建议在手机上跑大模型而是通过配置连接局域网内其他机器上的 Ollama 服务。实际体验下来OpenClaw 的 Web 控制台在手机浏览器里访问没问题Companion 相关的桌面功能用不了。这套方案适合出门在外临时查一下内网服务状态做演示穿帮的概率会高一些重负载任务还是会卡。4. 常见问题与排查技巧实录4.1 高频报错速查表把实际操作中遇到的高频问题整理成一张表方便你直接对着查。症状根本原因解决方案提示“无法安全验证 WSL2 环境”WSL2 未启动或默认版本不对在 PowerShell 运行wsl --status执行wsl --install并重启openclaw命令找不到npm 全局目录不在 PATH 中重新安装 Node.js或在 shell 配置里加入 npm 全局目录连接 Ollama 超时端口未监听或跨机器访问未放行先curl http://localhost:11434/api/tags自查再检查防火墙模型回答内容为空base_url 路径格式错误确认是/v1结尾而不是/v1/chat/completions全路径Skill 不生效Skill 目录路径不对或缺少依赖脚本检查配置文件里的 skillPath重新执行openclaw skills sync3000 端口被占用之前有进程残留Windows 用 netstat -ano其中“base_url 路径格式错误”是我见过的最高频问题。OpenAI 兼容接口的 base_url 应该写到/v1这一层不要写完整的/v1/chat/completions。模型服务的具体路径由 OpenClaw 在请求时自动拼上多写或少写一层都会导致 404。4.2 日志排查的通用思路OpenClaw 的日志其实是三层结构。第一层是主服务日志直接打在终端里记录请求进出和 Skill 调度。第二层是模型调用日志记录每次向模型服务发送的请求体、响应耗时、Token 消耗。第三层是 Skill 日志每个 Skill 自己输出的执行明细默认在logs/skills目录下。当出现“模型答非所问”或“Skill 执行一半失败”时排查顺序是先看主服务日志有没有报错堆栈再看模型调用日志里响应是否正常最后看具体 Skill 的执行输出。我常用的套路是openclaw logs --tail 50这条命令会实时把最近 50 行日志打印出来。如果能看到“Skill 调用成功但返回空”问题大概率出在 Skill 脚本本身如果日志里连模型请求都没发出去问题出在模型接入配置。记住一句话日志永远是最好的老师不要凭感觉改配置先看日志再动手。4.3 我踩过的几个坑写出来给你避雷先说 WSL2 和 Windows 防火墙的坑。WSL2 的 IP 每次重启可能变化如果 OpenClaw 配置里写死了旧 IP重启后就会连不上。解决办法有两个一是用 WSL2 的固定 IP 配置或者在 Windows 侧加一条端口转发规则二是干脆把 OpenClaw 主服务和 Ollama 都装在同一环境里避免跨环境通信。再说资源占用。OpenClaw 本身不重常驻内存 200MB 上下真正吃内存的是模型。用 qwen2.5:3b 这种模型加载后大概占 2GB 到 3GB 内存。部署前务必看一眼自己的机器内存低于 8GB 的机器建议别用超过 7B 的模型否则跑任务时会频繁触发交换系统卡到鼠标都挪不动。还有一个磁盘空间问题。Skill 仓库里有些示例技能会附带数据集和模型缓存git pull之后磁盘可能突然少掉几个 GB。建议定期执行openclaw skills clean清理无用的缓存文件。Docker 方案下还要注意挂载路径如果启动容器时忘记把配置目录挂载出来容器一删配置就全没了。5. 内网私有化部署与模型算力选型5.1 用 Docker Compose 把 OpenClaw 部署到内网服务器如果你想正式用起来而不是只在开发机上跑我推荐把 OpenClaw 部署到内网服务器并配合 Docker Compose 做编排。一个最小可用的 compose 文件大概长这样version: 3.8 services: openclaw: image: openclaw/community:latest container_name: openclaw restart: unless-stopped ports: - 3000:3000 environment: - OPENCLAW_MODEL_PROVIDERollama - OPENCLAW_OLLAMA_BASE_URLhttp://ollama:11434/v1 - OPENCLAW_MODEL_NAMEqwen2.5:3b volumes: - ./config:/root/.openclaw - ./skills:/root/skills - ./logs:/var/log/openclaw depends_on: - ollama ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped ports: - 11434:11434 volumes: - ollama_data:/root/.ollama volumes: ollama_data:这套编排的关键在于两个容器在同一个 Docker 网络里可以通过服务名互相访问所以 OpenClaw 的 base_url 填的是http://ollama:11434/v1而不是localhost。数据目录config、skills、logs都挂载到宿主机方便备份和后续维护。在服务器上执行docker compose up -d等待镜像拉取完成后就能通过http://服务器IP:3000访问。这里要提醒一句通过服务器 IP 和 3000 端口访问只适合内网环境。如果服务器有公网访问需求千万别把 3000 端口直接暴露到公网必须加一层反向代理和 HTTPS否则你的对话记录和 API Key 都裸奔在网络上。5.2 反向代理与证书自动部署内网部署可以只用 HTTP但我建议至少在重要场景下加上 TLS。原因很简单OpenClaw 的配置里存着 API Key而且对话内容涉及业务数据明文传输风险太高。社区里讨论的“certum 证书自动部署”本质上就是帮你在服务器上自动申请和续期 TLS 证书然后配置到 Nginx 反向代理上。Nginx 反代配置核心部分如下server { listen 443 ssl; server_name openclaw.example.com; ssl_certificate /etc/nginx/certs/fullchain.pem; ssl_certificate_key /etc/nginx/certs/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }证书的自动续期可以用 acme.sh 这类开源工具配置一条定时任务每月检查到期时间到期前自动签发并 reload Nginx。我用了半年基本是“配完就忘”的状态。如果只是内网试用也可以用自签名证书但客户端连接时会有安全警告体验差一些。对外提供服务务必选正规 CA 签发的证书。5.3 算力选型本地推理、私有 GPU 还是云 API聊回那个经典问题OpenClaw 只能用云 API 吗不是算力接入完全取决于你的场景。隐私敏感、数据不能出内网的场景选本地推理。单机 GPU 不够可以用 vLLM 在 GPU 服务器上起一个 OpenAI 兼容服务OpenClaw 通过局域网调用。vLLM 的优势是吞吐量高、显存管理好支持大规模并发适合给团队多人共用。没有 GPU 但需要私有化的场景就用 Ollama 跑小参数模型比如 qwen2.5:3b 或 qwen2.5:7bCPU 也能推理只是速度慢一些。追求最强模型能力、不差钱、数据敏感度低的场景才建议接入云厂商 API好处是免运维、模型版本新坏处是数据要过一圈外网。我个人的建议是“两层都接”默认模型用内网的小模型处理日常分类、提取、格式化这些轻量任务遇到复杂推理任务再切换到一个强模型 API。OpenClaw 支持在同一个配置里维护多个模型 Profile切换时只需要在请求参数里指定模型名。这也是它相比绑定某个厂商的工具优秀的点模型对你来说是插件想换就换。5.4 Skill 生态与框架对比OpenClaw 的独特位置Skill 生态是 OpenClaw 最大的护城河。你可以把一个 Skill 理解成智能体的“职业证书”装了“PDF 处理”技能它就会解析文档结构装了“Doris 查询”技能它就能写 SQL 去查数仓。社区里已经有不少开箱即用的 SkillDeepSeek Harness 这类针对特定模型的技能套件也很流行部署方式就是把技能目录复制到skills文件夹然后执行一次同步命令。经常有人问我WorkBuddy 这类商业产品是不是参考了 OpenClaw 做出来的时间线对不对得上。从技术架构看近两年的智能体框架在“模型路由 Skill 编排 任务队列”这三层设计上确实高度趋同OpenClaw 是这波浪潮里开源做得比较早的后发产品借鉴它的设计思路并不奇怪。但跟 Agno、WorkBuddy 相比OpenClaw 的优势是部署自由度更高、Skill 格式更开放、完全不绑定特定厂商控制台劣势则是界面和文档还比较极客风没有商业产品的上手引导那么顺滑。对愿意折腾的团队来说这个权衡是很值的。我把 OpenClaw 部署到内网服务器后用了大半年最大的感受是它离“玩具”越来越远离“生产力工具”越来越近。建议你第一次部署时不要贪多先用一个小模型跑通最小链路确认日志、Skill、Companion 都正常再逐步扩展模型和技能。这样即使后面遇到问题每一环都是自己亲手验证过的排障会轻松很多。最后再分享一个小技巧在openclaw serve启动后第一时间打开浏览器访问/console的开发者工具把 WebSocket 连接状态截图存下来后面所有“连不上”类问题几乎都能从这张截图里找到线索。