先说结论OpenClaw命令行入口叫 Clawdbot现在的一键部署确实比初代版本简单太多了官方脚本基本能做到“一条命令起服务”。但哪怕再简单第一次装完十个人里有七八个还是会卡在同一个地方不是模型连不上就是控制台起不来或者微信接入后消息发不出去。这篇就是把我从 2025 年底到 2026 年初反复重装、反复踩坑的完整流程写下来按步骤抄作业就行尤其适合只想要“能用”而不是“原理全懂”的朋友。OpenClaw 说人话就是一个“本地优先的 AI 智能体运行时”。你可以把它理解成一个常驻后台的机器人管家给它配好模型和消息入口之后它就能在微信、钉钉、网页控制台这些地方跟你对话还能调用预设技能、定时任务、文件读写这些能力。Clawdbot 是它命令行下的主进程名字安装完直接敲这个命令就能进交互界面所以社区里经常用 Clawdbot 指代整个程序。这套教程适合三类人一是被各种短视频“智能体”种草、想在自己电脑上跑一个真正属于自己机器人的人二是公司内部想做消息群聊机器人、但又不想买一堆 SaaS 服务的人三是已经在用其他 Agent 框架、想换到一个更轻量方案的人。下面直接按“准备 - 部署 - 配置 - 排查”的顺序讲每一步我都写在什么环境验证过、大概花了多少时间。1. 部署前你需要先想明白三件事1.1 官方开源版本和“代部署服务”的区别我估计很多朋友搜 OpenClaw 时会看到带“终身会员特惠”的推送、广告位里“一键部署工具”之类的东西。这里先泼一盆冷水OpenClaw 本体是开源的官方部署脚本、Docker 镜像、配置文件模板都是免费公开的你不需要为“安装部署”这个动作付费。那些号称“终身会员”的本质是在卖服务卖的是帮你配好环境、给你远程讲解的时间不是软件本身。预算充足的可以买服务省时间但千万别被“不买会员就用不了”这种话术吓住。1.2 机器配置到底要多高如果只是接 API 跑对话CPU 4 核、内存 8GB 就够用云服务器 2C4G 也能跑起来只是编译部分慢一点。如果要在本机跑 7B 以上的开源模型建议显卡显存至少 12GB内存 16GB 以上没有 NVIDIA 显卡的可以用 CPU 推理速度会比较感人但也不是不能用。我在 16GB 内存的 M1 MacBook Air 上部署过接 API 完全没问题但跑本地 7B 模型会明显吃力响应经常要等十几秒。所以第一步先想清楚你是打算用云上 API还是跑本地模型。这决定了后续所有配置方向。1.3 提前确认的账号和网络资源部署前把这三样准备好一个模型 API key如果是本地模型先装好 Ollama 或 vLLM一个用于接收消息的钉钉或企业微信账号个人微信有条件限制后面细说。另外如果你准备在云服务器上部署最好提前确认一下服务器地域和模型服务商的连通性不同地域访问同一个 API 的延迟差别很大这会影响你后续调试时的心情。这个不是教程重点但值得提前留意。2. 环境准备与最小依赖安装2.1 各平台环境要求速查在开始跑安装脚本之前先对着表格检查一下自己的环境。这套要求是我实测过的最低标准再低就会出现编译失败或者页面白屏。平台推荐配置最低配置主要限制Windows 10/1116GB 内存、SSD8GB 内存部分模型需要 WSL2macOS 12Apple Silicon 16GB 内存Intel 8GB 内存本地模型依赖 MetalLinuxUbuntu 22.0416GB 内存、NVIDIA GPU4GB 内存CUDA 驱动需提前确认云服务器4C8G2C4G无 GPU 时只能跑 API 模式如果你用的是 Windows强烈建议先装上 WSL2因为 OpenClaw 很多底层工具链在 Linux 环境下更顺滑。装完之后在 WSL 里执行安装命令比你直接在 PowerShell 里折腾少踩很多坑。2.2 安装 Git、Node.js、DockerOpenClaw 安装脚本依赖 Git 来拉取组件Node.js 用来跑 Control UIDocker 则是可选方案的基础。三个工具的安装可以分开来看Windows 下用 winget 一次性装齐winget install Git.Git OpenJS.NodeJS.LTS Docker.DockerDesktopmacOS 下用 Homebrewbrew install git node dockerDebian/Ubuntu 下用 aptsudo apt update sudo apt install -y git curl curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs docker.io sudo systemctl enable --now docker装完后分别验证一下版本git --version node --version docker --versionNode 版本建议 20 以上。我之前在一台只有 Node 16 的旧服务器上装Control UI 怎么都起不来升级到 20 之后一次通过。2.3 目录规划与备份思路OpenClaw 所有数据默认放在~/.openclaw包括配置文件、日志、数据库、Skill、Companion 模型缓存。这个目录就是它的“整个家”。我建议安装前就做好一个习惯每次改配置之前先cp -r ~/.openclaw ~/.openclaw.bak。换机器时直接把这个目录整个打包带走比重新配置快得多比重新引导模型快得多。社区里说的“openclaw portable pack”本质上就是把~/.openclaw连同可执行文件一起打成压缩包。你在 Windows 上跑通了配置把整个.openclaw目录复制到 Linux 服务器上只要路径和用户权限对上基本能直接接着用。这一点对二次开发的朋友尤其重要。3. 一键部署的三种方式按场景选3.1 官方安装脚本最推荐打开终端执行curl -fsSL https://openclaw.sh/install.sh | bash如果你是 Windows PowerShell用iwr -useb https://openclaw.sh/install.ps1 | iex安装脚本会依次做四件事下载主程序二进制、初始化~/.openclaw目录、生成默认的openclaw.yaml、检测 node/docker/git 是否可用。整个过程大概三分钟。装完先跑一个体检命令clawdbot doctor看到所有检查项都是OK就可以继续了。如果中途失败最常见原因是网络超时重新跑一次脚本就行脚本本身支持断点续传不会重复下载已经完成的部分。3.2 Docker 部署适合服务器和无痕环境不想污染本机环境或者需要在云服务器上快速起一个实例用 Docker 最省心docker run -d --name openclaw \ -v ~/.openclaw:/root/.openclaw \ -p 8080:8080 -p 8081:8081 \ ghcr.io/openclaw/openclaw:latest启动后看日志docker logs -f openclaw看到类似OpenClaw runtime started就说明起来了。这里要注意一个 Volume 权限问题容器里的用户 id 和宿主用户 id 不一致时文件权限会混乱症状是你能写文件但容器里的进程读不到。解决办法是在启动命令里显式指定docker run -d --name openclaw \ -e USER_UID$(id -u) -e USER_GID$(id -g) \ -v ~/.openclaw:/root/.openclaw \ -p 8080:8080 -p 8081:8081 \ ghcr.io/openclaw/openclaw:latest如果之前已经用错误方式启动过记得先docker rm openclaw再重建。3.3 Windows 桌面安装包和便携包官方 Release 页面会同时提供 exe 安装包和便携包。普通用户建议直接装 exe双击无脑下一步。便携包适合想放 U 盘里到处跑的人下载后解压双击start.bat就行。这里提醒一下首次运行 Windows Defender 有时会误报因为它里面本地带了 Python 运行时和推理引擎杀软会当成风险文件处理。遇到这种情况在“病毒和威胁防护”里把 OpenClaw 目录加入排除名单而不是关闭整个防护。3.4 安装后的完整目录结构装完之后打开~/.openclaw你会看到这样的结构~/.openclaw/ ├── openclaw.yaml # 主配置文件 ├── .env # 密钥环境变量文件 ├── config/ │ ├── channels/ # 微信/钉钉等通道配置 │ └── skills/ # 技能目录 ├── data/ │ └── openclaw.db # SQLite 数据库 ├── logs/ │ ├── controller.log # 控制台日志 │ ├── runtime.log # 运行时日志 │ └── channel-wechat.log # 微信通道日志 ├── models/ # 本地模型缓存 └── skills/ # 用户自定义技能我建议你把logs/目录记到收藏夹里。以后出任何问题第一件事就是打开runtime.log看最后 50 行百分之八十的报错密码都藏在这里。4. 让 OpenClaw 听懂人话模型与基础配置4.1 openclaw.yaml 核心参数逐个说OpenClaw 启动时读取~/.openclaw/openclaw.yaml这个文件是整个系统的心脏。默认模板长这样server: port: 8080 ui_port: 8081 runtime: metadata: auto storage: sqlite model: default: deepseek providers: deepseek: api_key: ${DEEPSEEK_API_KEY} base_url: https://api.deepseek.com/v1 model: deepseek-chatserver.port是 API 端口ui_port是 Control UI 的端口后面访问网页控制台用的就是它。runtime.metadata这个字段经常被忽略它记录的是 OpenClaw 的运行时指纹和平台信息升级版本后可能失效需要执行clawdbot runtime init重新生成。如果你升级完时不时报兼容性错误先试试重新初始化元数据。4.2 配置 DeepSeek / OpenAI / 千问等 API不同模型服务商的配置差异只在于base_url和model名字。以 DeepSeek 为例先在~/.openclaw/.env里写入密钥DEEPSEEK_API_KEYsk-xxxx OPENAI_API_KEYsk-xxxx DASHSCOPE_API_KEYsk-xxxx然后在openclaw.yaml里声明多个 providermodel: default: deepseek providers: deepseek: api_key: ${DEEPSEEK_API_KEY} base_url: https://api.deepseek.com/v1 model: deepseek-chat openai: api_key: ${OPENAI_API_KEY} base_url: https://api.openai.com/v1 model: gpt-4o-mini qwen: api_key: ${DASHSCOPE_API_KEY} base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 model: qwen-max这里有个非常关键的习惯密钥永远不要写死在openclaw.yaml里而是引用${}环境变量。好处有两个一是防止你把配置分享给别人的时候顺手把密钥发出去二是换环境时只要改.env文件不用动主配置。这个习惯能避免你少删 N 次库重来。4.3 接入本地模型与 NVIDIA NIM本地模型走的是 OpenAI 兼容接口。以 Ollama 为例先启动 Ollama 下载模型ollama pull qwen2.5:14b ollama serve然后在 provider 里加一个locallocal: base_url: http://127.0.0.1:11434/v1 api_key: ollama model: qwen2.5:14b如果你用 NVIDIA NIM配置思路一样只是base_url指向你启动 NIM 服务的地址和端口。NIM 的好处是 NVIDIA 把推理引擎和硬件驱动封装好了跑支持列表里的模型时性能比裸装 vLLM 更省心。但 NIM 对显卡驱动版本要求很严格装之前先跑一下nvidia-smi确认 driver 版本在支持列表里不然你会花大量时间在“启动就崩溃”的排查上。4.4 把默认模型切到你想要的所有 provider 配好之后改model.default就能切换默认模型比如model: default: local然后执行测试clawdbot test --prompt 你好用一句话介绍你自己如果返回正常说明配置生效如果报unknown model: deepseek或者其他model not found类错误大概率是 provider 名字写错了或者.env里的环境变量没加载。clawdbot doctor可以快速定位是哪个环节断的。5. 接入微信、钉钉与消息通道5.1 微信个人号接入的注意事项接入微信需要先安装官方的微信桥接组件clawdbot channel install wechat首次运行会生成一个二维码用你的微信扫码后配置文件里会自动填入凭证。这里必须说清楚个人号协议存在被风控的风险OpenClaw 官方也反复强调不建议在主力微信号上长期挂机。你用主号扫了码过两天突然收到“当前环境异常”提示那就是被限制登录了。所以我的建议是测试请用一个专用小号出了事也不会影响日常使用。如果是公司内部用优先走企业微信稳定程度完全不是一个量级。5.2 钉钉机器人接入钉钉的接入过程比微信更正规也更简单。先去钉钉开放平台创建一个企业内部应用拿到 AppKey 和 AppSecretchannels: dingtalk: enabled: true app_key: xxx app_secret: xxx webhook_callback_url: https://你的域名:8090/dingtalk/callback部署在云服务器上的时候需要在安全组放行 8090 端口并把这个回调地址填到钉钉应用的“事件订阅”里。如果暂时没有域名用 IP 也能凑合但钉钉对回调地址要求比较严格建议直接配一个域名加上合法的 TLS 证书后面省心很多。5.3 开启 Control UI 网页控制台正常启动后浏览器访问http://localhost:8081就能看到 OpenClaw 的网页控制台。这个页面可以实时看对话日志、管理技能、查看记忆数据库相当于一个图形化的驾驶舱。如果你在云服务器上部署本地访问不了 8081最简单的办法是用 SSH 隧道转发端口而不是直接把 8081 暴露到公网。遇到openclaw control UI did not start这种报错按下一章排查方法处理大概率是端口被占用或者 Node 版本问题。6. 踩坑实录常见问题与排查速查表6.1 openclaw control UI did not start 到底怎么查这个报错几乎每个新手都会遇到但我可以负责任地说百分之八十的情况不是 OpenClaw 的问题而是环境问题。排查按三步走第一步看服务有没有起来clawdbot status第二步看 8081 端口有没有被监听netstat -ano | findstr :8081第三步看日志tail -n 50 ~/.openclaw/logs/controller.log如果日志里出现EADDRINUSE就是端口被占换个端口或杀掉占用进程即可。如果出现 Node 版本相关错误去升级 Node 到 20。如果日志里什么都没有很可能是 UI 构建文件缺失重新执行一次clawdbot ui rebuild就能解决。6.2 EBUSY / resource busy or locked 问题这个报错在 Windows 上很常见安装失败后想删除~/.openclaw重装系统提示failed to remove ~\.openclaw: error: ebusy: resource busy or locked, unlink。原因是后台clawdbot进程还占着文件或者杀毒软件正在扫描。解决思路是先杀进程再删目录taskkill /F /IM clawdbot.exe taskkill /F /IM node.exe rd /s /q C:\Users\你的用户名\.openclaw如果还是删不掉打开任务管理器看有没有 Windows 安全中心触发的实时扫描等几秒再试。macOS/Linux 下对应的是pkill -f clawdbot rm -rf ~/.openclaw执行删除前务必确认这个目录里没有你需要保留的数据库和配置删了可找不回来。6.3 unknown model: deepseek / zero token 问题agent failed before reply: unknown model: deepseek这个报错我在社区里见了无数回。原因是 OpenClaw 在 providers 列表里没找到叫deepseek的模型定义。常见原因有三个配置文件缩进或字段命名错误provider 没被正确解析.env文件没被加载导致带${}引用的 provider 被整体跳过安装时用了精简模板配置文件里根本没有deepseek这个 provider。排查方法是先看模型列表clawdbot model list再运行体检clawdbot doctor如果列表里确实没有把openclaw.yaml里的 provider 段补完整重新执行clawdbot reload即可。如果你开了 zero token 模式意思是某些场景下模型不消耗 token同时报这个错先检查模型是否支持这种调用方式不支持就把该选项关掉。6.4 云端部署 OpenClaw 时必须注意的细节云服务器部署时官方脚本和 Docker 方式都可以但我必须强调几点第一不要直接用 root 账号跑安装脚本建议新建一个普通用户并且切换过去再装。第二云厂商的安全组不要把 8080、8081 全部暴露给 0.0.0.0只放开你需要的消息通道端口。第三公网环境建议在 OpenClaw 前面加一层反向代理Caddy 或 Nginx加上简单的 Basic Auth 或 OAuth 认证否则你的控制台等于裸奔任何人都能访问并操作你的智能体。7. 让 OpenClaw 更像“长期员工”Companion 与 Active Memory7.1 Companion 本地模型怎么配Companion 是 OpenClaw 里负责生成对话摘要、情感分析、记忆提取的小模型。默认情况下它走 API每次对话都会消耗一定 token。如果你希望摘要过程不消耗 API token或者数据敏感不想把对话内容送到云端可以把 Companion 切到本地模型companion: provider: local base_url: http://127.0.0.1:11434/v1 api_key: ollama model: qwen2.5:7b配置完之后重启 OpenClaw再对话几次观察日志里是否出现companion summary generated之类的记录有就说明正常工作了。我实测下来本地 7B 模型做摘要的质量足够日常使用速度在 16GB 内存的机器上也能接受。7.2 Active Memory 高阶思路构建长期工作记忆Active Memory 是 OpenClaw 里比较有代表性的功能它给 Agent 塞了一块“长期工作记忆”平时把对话中的关键信息比如你的名字、常用项目路径、偏好设置写入到 SQLite 数据库里下次对话时再自动取出来。换句话说它不会每次对话都“失忆”而是能记住你上周说过的话。查看当前记忆clawdbot memory query --all我建议装好后先做一次记忆测试告诉它你的名字和一个项目路径隔十分钟再问它是否记得。如果记忆丢失检查~/.openclaw/data目录权限以及 active memory 开关是否打开。这个功能如果你长期不用到后面 Agent 的行为会显得非常“没有上下文”所以推荐从一开始就开着。7.3 多模型路由与 Skill 扩展当多个模型并存时OpenClaw 支持在对话里通过model 模型名临时切换model openai 帮我总结这个文档这相当于把 DeepSeek 当日常助手、把 OpenAI 当特定任务专家、把本地模型当隐私数据专用通道一个实例搞定所有场景。Skill 机制则更灵活本质就是放在~/.openclaw/skills/下的一组脚本每个 skill 一个目录包含skill.yaml和可执行文件。我去社区抄过一个“定时钉钉日报”的 skill每天早上九点自动读取昨天的数据、调用模型生成日报、推到钉钉群效果很稳。配置并不复杂核心就是写好skill.yaml里的触发条件和命令。至于有人拿 OpenClaw 配合 Obsidian 做项目管理思路其实就是把 OpenClaw 当成调度器你只需要把会议纪要丢进 vault让 Agent 定期生成计划文档再主动记忆你的项目偏好。这个组合在个人知识管理场景里意外地好用后续可以单独写一篇展开说。最后分享一个我自己的习惯每次装完 OpenClaw我都会先花 5 分钟把openclaw.yaml里改过的字段在一个 markdown 文件里记一下顺便把模型 API key 放到.env而不是主配置里。这样以后升级版本、换机器基本能做到 10 分钟恢复。手机端那些玩法我也试过Termux 可以跑轻量便携包但强烈建议先用电脑把所有流程跑通再折腾手机不然排查起来非常劝退。