我一直觉得AI Agent 这类东西最劝退人的不是它有多难而是网上的教程清一色默认你是个“读了十年计算机的老手”。一会儿让你配环境变量一会儿让你改 source 列表折腾一晚上连个对话框都没跑起来。所以当 OpenClaw社区也叫 Clawdbot这类项目出现的时候我第一反应是能不能真正做到“一条命令跑起来”实测下来答案是能但前提是你得知道命令背后在干什么以及踩坑点在哪。这篇教程就是干这个的。我会带着你从零开始先在云服务器上用 1 分钟把 OpenClaw 部署起来再教你把同样的流程搬到本地 Windows 或 Linux 机器上最后讲清楚 skill 到底是个什么东西、怎么集成、怎么写一个最简版本。整个过程全程保姆级每个命令我都会解释它干了啥每个配置我都会说清楚为什么这么写。不管你是第一次碰 Docker 的小白还是想了解 Agent 扩展机制的进阶玩家照着敲就行。1. 部署前的准备搞清楚你要跟哪些“零件”打交道1.1 方案选型为什么我坚持用 Docker 而不是裸机装在正式开始敲命令之前我想先花两分钟跟你聊聊部署方案的选型问题。因为 OpenClaw 本身是一个 Node.js 项目社区也提供了一键安装脚本可以让你直接在系统上装依赖、跑进程。但我的建议始终是能用 Docker 就别裸奔。原因有三点。第一OpenClaw 的依赖链不算短Node 版本、npm 包、配置文件路径稍有偏差就能让整个服务起不来而 Docker 镜像把这些乱七八糟的依赖全部打包好了你拉下来就是一个干净、固定的运行环境。第二OpenClaw 需要调用外部 API同时也会监听本地端口容器化之后端口映射、网络权限、日志管理都变得非常可控出了问题删掉容器重建就行不会污染你的系统。第三云服务器和本地电脑的操作系统可能不一样你在 Mac 上本地调试没问题但云上是个 CentOS裸机部署多半会遇到奇奇怪怪的兼容性差异而 Docker 把这种差异全部抹平了。打个比方Docker 就像是一个打包好的“毛坯房”里面水管、电线、门窗全部装好了你只需要拎包入住而裸机部署就像你买了一块地自己盖楼每一步都可能出问题。对于“0 基础 1 分钟部署”这个目标来说Docker 是不二之选。我目前常用的部署方式是云服务器上用 Docker 跑 OpenClaw本地开发时同一套镜像直接拉起来两边行为一致几乎没有环境差异导致的坑。这样也方便我把配置文件统一管理后面讲 skill 集成的时候你会体会到这个好处。1.2 硬件与环境要求云上和本地各需要什么别被“AI Agent”这个词吓到OpenClaw 本身不是什么吃显存的大模型它只是一个调度框架真正干活的模型在云端 API 或者你本地跑的 Ollama 里。所以它对硬件的要求低得惊人。部署方式推荐配置最低可跑配置使用场景云服务器2核4G40G SSD1核2G轻量级使用7x24 小时在线、接入 Teams/飞书等办公场景本地电脑16G内存随便一颗现代CPU8G内存Docker Desktop 能跑开发调试、本地模型联动、学习体验有一点必须提醒你OpenClaw 在云上跑和在本地跑唯一的硬性区别是你有没有外网访问能力。因为它的多数 skill 和部分 channel 回调需要公网地址本地跑的话一般只做调试用真要接入飞书机器人或者 Teams 机器人还是建议放在云上。另外如果你打算在本地接 Ollama 这类本地模型那就要考虑模型本身的参数量和显存占用2B 模型大概需要 4-6G 内存7B 模型建议 16G 以上。这个我后面会专门讲。操作系统方面Docker 官方支持 Windows、macOS、主流 Linux 发行版。Windows 上用 Docker Desktop 即可Linux 上用命令行安装 docker-ce。需要注意 Windows 老版本比如 Win10 家庭版可能没有 Hyper-V装 Docker Desktop 会失败建议直接搜“启用 WSL2”教程把 WSL2 打开再装 Docker这是最省事的路子。1.3 前置资源API 密钥和大模型 API 的选择思路OpenClaw 自己不带大模型它只是一个“大脑的经纪人”真正思考的是你接入的模型。在你开始部署之前先想清楚一个问题这个 Agent 的大脑要用谁的主流选择有三类大厂官方 APIDeepSeek、阿里千问、OpenAI、Anthropic 等优点是与 OpenClaw 兼容性好、响应快、不用自己维护模型缺点是花钱但 DeepSeek 这类国产模型的定价非常便宜日常使用成本可以忽略。本地模型通过 Ollama 跑 Qwen、DeepSeek 蒸馏版、Ministral 这类开源模型OpenClaw 通过本地接口对接。优点是免费、数据不出内网缺点是电脑性能要有底线且模型能力不如云端 API 强。中转/聚合 API一些服务商提供多模型聚合接口OpenClaw 也能对接。这个我不展开推荐你自己选择正规渠道就行。我建议小白第一次跑通流程时直接用 DeepSeek 或千问的 API因为它们的接口兼容 OpenAI 格式OpenClaw 配置起来几乎是填空。先去对应开放平台注册账号、创建 API Key、充值几块钱部署的时候就能直接用。等你把整个流程跑熟了再尝试把大脑换成 Ollama 本地模型也不迟。这里我踩过一个大坑很多人部署完之后发现 Agent 回复“/api_key 没有配置”但明明在配置文件里写了。后来我发现是配置文件里的 Key 字段和 OpenClaw 实际读取的环境变量名对不上。所以拿到 API Key 之后先别急着往配置里填先想清楚它是给哪个 provider 的、格式长什么样这个到第二章我会详细讲。2. 核心配置解析看懂 OpenClaw 的“大脑”和“手脚”2.1 配置文件到底长什么样一个真实案例拆解OpenClaw 启动后会自动生成一个配置目录通常是工作目录下的~/.openclaw/里面有一个叫config.yaml的主配置。你第一次跑起来之后会看到它自动生成了一个默认配置那个默认配置是不带任何模型 API 的需要你自己填。拿我自己的实际配置举个例子# config.yaml 核心摘录 agent: name: my-helper model: provider: deepseek # 指定用哪个模型服务商 api_key_env: DEEPSEEK_API_KEY # 从环境变量里读 Key base_url: https://api.deepseek.com model_name: deepseek-chat channels: - type: terminal # 让 Agent 在命令行里跑起来 - type: feishu # 接入飞书机器人 app_id: cli_xxxxx app_secret: xxxxx servers: - port: 8080 # 提供一个 HTTP 服务方便调试看到这个配置你应该能理解 OpenClaw 的设计理念了。它把 Agent 拆成了三个核心部分大脑model、手脚channels和神经servers。大脑负责理解你说的话、生成回复手脚负责跟外界交互比如在飞书里收消息、在 Teams 里发卡片神经负责提供 API 接口方便你别的方式调它。这里最值得注意的是api_key_env这个字段。它是说你可以在配置文件里不直接写 Key而是写一个环境变量的名字然后在启动容器或系统里设置这个环境变量。这样做的最大好处是你的配置文件可以被分享、进 Git 仓库不会把你的密钥泄露出去。我强烈建议你也这样做特别是打算把配置备份到云上或者给朋友看的时候。还有一个容易忽略的字段是model_name。不同服务商的三款模型名称五花八门比如 DeepSeek 叫deepseek-chat阿里千问叫qwen-plus。如果你填错了名字OpenClaw 调用 API 时就会报错且报错信息通常很模糊比如“Model not found”或者“Unknown request URL”。所以填配置时一定要去对应模型服务商的文档里查一遍准确的模型名别凭标题里的印象填。2.2 模型怎么选DeepSeek、千问还是本地 OllamaModel 配置决定了 Agent 的“智商”。不同模型在处理 Agent 场景时的差距非常明显特别是工具调用function call能力。我自己的实测感受是如果你要用 skill至少要选一个能稳定输出工具调用的模型。DeepSeek 的deepseek-chat虽然是性价比之王但偶尔也会出现“忘记调用工具直接硬编回复”的情况千问系列在中文场景下表现更稳但价格略高。如果你不想花钱本地 Ollama 是很好的替代方案。Ollama 的安装非常简单装好后在终端跑ollama run qwen2.5:7b就能把模型拉起来。然后你要把 OpenClaw 的 provider 指向本地地址agent: model: provider: ollama base_url: http://host.docker.internal:11434 # 注意容器内访问宿主机要用这个 model_name: qwen2.5:7b为什么写成host.docker.internal而不是localhost因为 OpenClaw 跑在 Docker 容器里容器里的localhost指的是容器自己不是你的宿主机。host.docker.internal是 Docker 给容器预留的一个魔法域名指代宿主机。这一点非常容易踩坑很多人本地模型配了半天连不上就是卡在这。至于模型的温度、max_tokens 这些参数我建议新手先不要动保持默认即可。等你跑通了再慢慢调“temperature”来让 Agent 更活泼或更保守。2.3 skill 到底是个什么东西从目录结构到触发机制如果你用过 ChatGPT 的插件或者 Coze 的插件那 skill 一点也不陌生。skill 就是给 Agent 加装的一根“专用工具手”它由一组指令、脚本和配置文件组成目的是让 Agent 在特定话题下干得更专业。OpenClaw 的 skill 机制很老派也很务实每个 skill 就是一个文件夹放在~/.openclaw/skills/下面里面至少有一个SKILL.md文件作为说明书还可能有几个脚本文件。当你在对话里提到跟这个 skill 相关的关键词时Agent 会去读 SKILL.md按照里面的说明一步一步执行。我给一个最简单的 skill 例子名字叫math_helper作用是让 Agent 在回答数学问题时先算再答mkdir -p ~/.openclaw/skills/math_helper cat ~/.openclaw/skills/math_helper/SKILL.md EOF # math_helper ## 描述 这是一个数学计算辅助 skill。当用户提出数学计算问题时必须使用 python3 脚本先计算再给出结论。 ## 触发条件 用户消息中包含“计算”、“多少”、“等于”等词或明显是一个数学表达式。 ## 执行步骤 1. 接收用户输入 2. 提取表达式 3. 调用同目录下 calc.py 完成计算 4. 把结果整合成回答 EOF cat ~/.openclaw/skills/math_helper/calc.py EOF import sys print(eval(sys.argv[1])) EOF这样建好之后重启 OpenClaw你再说“帮我计算 12345 乘以 6789”Agent 就会调用这个 skill而不再是凭它自己的算力硬算。这个模式的价值在于你可以把任何重复性的工作固化成 skill比如查天气、做笔记、翻译文档、调用公司内部 API 等。这里必须强调一个程序员思维的转变skill 的核心不是写脚本本身而是定义好“什么时候触发”和“怎么执行”。SKILL.md 写得越清晰Agent 调用的准确率越高。我见过不少人写 skill脚本牛逼得不行但 SKILL.md 就一句话结果 Agent 压根不触发。你得把它当成一份给“笨但认真”的实习生看的说明书。2.4 channel 选择与平台接入飞书、Teams 还是 CLIchannel 是 OpenClaw 的“耳朵和嘴巴”决定了 Agent 从哪儿听消息、把消息发到哪儿。新手从terminalchannel 开始是最稳的因为不需要任何平台配置直接就地在命令行里跟 Agent 对话。但大多数人感兴趣的是接入办公软件让 Agent 变成团队里一个真正的成员。常见的选择是飞书和 Microsoft Teams。配置方式在上面的示例里已经给过雏形飞书需要在开放平台创建应用、拿到 App ID 和 App Secret再把消息回调地址填到平台后台。Teams 则更复杂一点需要你在 Azure 门户注册机器人应用配置 Bot ID 和密码。这里我想特别提醒一个 2025 年 OpenClaw 社区特别热的痛点飞书输出容易被截断。原因是飞书消息有长度限制Agent 回复一长就直接被切掉用户只看到半截话。解决思路有两个一是把模型配置里的max_tokens调小逼 Agent 说短话二是写一个专门的截断处理 skill让 Agent 输出前强制分段或者把长内容写成 Markdown 消息卡片。就我的体验来说如果你只是想自己体验一下 Agent用terminal就够了如果你想让它干活、接入团队协作优先选飞书因为国内网络环境稳定、文档丰富Teams 适合外企或习惯 Office 生态的团队。选 channel 的核心标准不是“哪个酷”而是“你的团队本来就用哪个”。3. 实操部署全流程云端 1 分钟跑起来3.1 云端部署购买服务器后的 5 步操作我在云上部署过不下十次从腾讯云到阿里云到轻量级 VPS 都试过。最流畅的路径是买一台 2 核 4G 的轻量服务器系统选 Ubuntu 22.04然后按下面五步走。第一步更新系统并安装 Dockercurl -fsSL https://get.docker.com | sh systemctl start docker这个命令秒装 Docker 官方源不用你去配什么 yum 源。装完之后docker --version验证一下。第二步拉取 OpenClaw 镜像。社区镜像名通常是ghcr.io/openclaw/openclaw或者 Docker Hub 上的openclaw/openclaw具体看你用的版本说明。我用的命令是docker pull openclaw/openclaw:latest第三步创建配置目录和密钥文件mkdir -p /opt/openclaw export DEEPSEEK_API_KEYsk-你的密钥第四步启动容器把内部端口映射到宿主机docker run -d \ --name openclaw \ -p 8080:8080 \ -v /opt/openclaw:/root/.openclaw \ -e DEEPSEEK_API_KEY$DEEPSEEK_API_KEY \ openclaw/openclaw:latest这行命令看着长拆开其实就四件事给容器起名、把宿主机 8080 端口映射到容器内部 8080、把/opt/openclaw目录挂载成容器内的工作目录、把刚才设置的环境变量传进去。第五步验证启动是否成功docker logs -f openclaw看到日志里出现类似“Agent is running”的字样就说明部署成功了。此时你可以直接敲docker exec -it openclaw /bin/bash进入容器跑一个对话测试。实测下来整个过程不会超过两分钟唯一可能卡住的是拉镜像那一步如果你服务器网络在境外资源上比较慢可以配置镜像加速器这个每个云厂商控制台都有教程。拉下来之后启动是非常快的。3.2 本地部署Windows 用户和 Linux 用户的两种姿势本地部署的最终效果跟云上一样但有一个前提你必须先把 Docker 装好。Windows 用户直接安装 Docker Desktop 就行记得安装完之后把 WSL2 打开。Linux 用户按上一节第一步那样安装 docker-ce 即可。装好 Docker 之后流程跟云上几乎完全一样。我直接给 Windows 用户一个可以在 PowerShell 里跑的版本mkdir C:\openclaw docker pull openclaw/openclaw:latest docker run -d --name openclaw -p 8080:8080 -v C:\openclaw:/root/.openclaw -e DEEPSEEK_API_KEYsk-xxx openclaw/openclaw:latest注意 Windows 的路径挂载格式是C:\openclaw这种盘符写法在 Docker Desktop 里会自动转换成宿主机路径。如果你用的是 Git Bash路径写法可能又要变成/c/openclaw反正多试两下就懂了。本地启动成功后你在浏览器访问http://localhost:8080就能看到一个简单的调试页面或者在终端里执行docker exec -it openclaw openclaw chat直接在命令行里跟 Agent 对话。这个“本地 Chat”模式特别适合练手因为它不依赖任何外部回调服务关键是还能看到 Agent 的完整日志输出对理解 skill 的触发逻辑帮助极大。3.3 本地模型联动Ollama 与 OpenClaw 的低成本组合本地部署 本地模型是很多人追求的“离线可用的 AI 助手”。真要把这两样串起来核心就在于让容器里的 OpenClaw 找到宿主机里的 Ollama。这里我把步骤拆解一遍。第一步宿主机安装 Ollama装完跑一个轻量模型curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:3b ollama run qwen2.5:3b第二步修改 OpenClaw 配置把 model provider 指到 Ollama。配置文件里写上agent: model: provider: ollama base_url: http://host.docker.internal:11434 model_name: qwen2.5:3b第三步重启容器让配置生效docker restart openclaw然后你在命令行里跟 Agent 说一句话如果它回复了那整套本地模型链路就通了。如果没通99% 的问题是base_url写错。在容器里跑一个curl http://host.docker.internal:11434就能验证 Ollama 是否可达。这个组合的吸引力在于完全免费、完全离线。不过我也得说实话3B 模型的智商跟deepseek-chat差了两个量级更复杂一点的 skill 调用容易翻车。所以我的建议是本地模型适合做测试、做隐私保护场景真要干重活还是得接云端 API。3.4 验证技能让 Agent 干点实事部署完成之后别急着庆祝先做三个小测试确保整个系统不是“看起来活着实际是死的”。第一个测试叫“基础对话测试”。你直接发一句“你是谁”如果 Agent 快速回复说明大脑连接正常。如果卡住没反应去docker logs openclaw看有没有 API 报错。第二个测试叫“skill 触发测试”。你先装一个技能比如前面写的math_helper然后发“请帮我计算 2 的 10 次方”。如果 Agent 的回答不是一个大概数字而是一个精确数字说明 skill 调用成功。如果它回了一个错误答案说明触发失败或脚本有问题去日志里查 python 进程有没有跑起来。第三个测试叫“channel 连通测试”。如果你配了飞书就让同事给你发一条消息如果只有 terminal那就不用测了。这三个测试做完才算真正跑通了。跑通之后你就可以开始琢磨 skill 扩展了——这个过程非常有趣稍微改一下 SKILL.mdAgent 就能学会一项新技能有点像在给一个外教不断更新教材。4. 常见问题与排查技巧实录4.1 session file locked 超时报错到底是谁锁住了文件OpenClaw 社区有个高频报错原文是“agent failed before reply: session file locked (timeout 60000ms)”。我第一次看到这个报错时一头雾水后来排查才发现问题出在多个 OpenClaw 实例在同时读写同一个 session 文件。最常见的情形是你跑了一个容器又手贱在宿主机上跑了一个二进制版本两边共用了同一个配置目录session 文件就被锁住了。解决办法分三步先查一下有没有多实例在跑docker ps看容器列表再用ps aux | grep openclaw看宿主机进程。把多余的实例关掉只保留一个。如果还是报错直接删除 session 目录里的锁定文件rm -rf ~/.openclaw/sessions/*.lock然后重启容器。这个报错的本质是文件锁机制跟“网络不行”“API 不行”都没关系你不用绕弯路去检查 API Key。我遇到过有人因为这个报错去重装了一整遍系统其实只要删掉锁文件就好了。4.2 飞书输出截断问题三种解法照着选在飞书里用 OpenClaw长回复被截断几乎是必经之痛。飞书对单条消息的长度有硬限制超过就会被平台强行切掉用户看到的回复内容就断了很影响体验。我的处理经验分成三个等级。第一级是治标把模型的max_tokens调小一点从默认的 4096 调到 2048逼 Agent 精简回复。第二级是治本制作一个“分段输出”的 skill让 Agent 在生成内容前先规划好段落每段控制在较短字数内然后用多个消息卡片分段发送。第三级是另辟蹊径让 Agent 在回复里生成摘要把详细内容写成 Markdown 文件或者文档链接用户需要详情再点开。我推荐至少做到第二级因为调小 tokne 会降低回复质量而分段输出对用户是透明的体验最好。4.3 新手最容易踩的坑汇总这部分是我踩过无数坑之后总结出来的高发区。整理成一张速查表你照着排查能省大量时间。症状根本原因解决办法容器启动了但对话没反应API Key 没填对或环境变量没传进容器检查docker inspect openclaw里有没有对应的 Env 变量回复全是乱码或问号终端编码问题飞书里则是模型输出被错误解析Windows 终端切 UTF-8 编码飞书场景检查是否开了“富文本卡片”模式skill 永远不触发触发关键词写得太模糊或 SKILL.md 格式不对重写触发条件用更精准的动词或名词本地 Ollama 连不上base_url写成了localhost改成host.docker.internal飞书消息回调失败公网 IP 没有暴露给飞书平台或端口没映射确保服务器安全组放行对应端口并检查应用回调地址是否填写准确每次重启配置就丢没挂载配置目录启动容器时记得-v参数挂载外部目录这里面我最想强调的是“每次重启配置就丢”这个问题。很多人第一次用 Docker 都会踩因为容器是临时的你不挂载外部目录配置就写在容器内部一删容器就全没了。养成习惯所有要保留的数据都得通过-v挂在宿主机上这等同于“把贵重物品放进保险箱”。5. 最后再分享一个关于 skill 的小技巧我现在每天都在用 OpenClaw最多的场景不是让它耍酷聊天而是帮我把零散的笔记整理成结构化文档。这靠的就是一个我自己写的 skill触发词是“帮我整理”SKILL.md 里写明“读取输入内容的主题、分段、提炼要点、输出 Markdown”。这个 skill 逻辑非常简单但价值极大。给你一个可以直接抄的模板思路SKILL.md 一定要包含三块内容。“描述”部分说明这个 skill 擅长什么“触发条件”部分写清楚哪些词或句式应该触发它“执行流程”部分按步骤写清楚 Agent 拿到输入后先做什么、再做什么、最后输出什么格式。在部署和 skill 集成的过程中我个人最深的体会是工具本身不复杂复杂的从来都是环境差异和配置细节。所以遇到报错别慌先去查日志再对照我上面给的排查表逐项过一遍。把这一步走通了你就能从“能跑通”进阶到“会调教”Agent 才会真正变成你的得力助手。