2026年再看AI Agent大家的关注点已经从“能不能跑”变成“跑起来能接多少事”。OpenClaw也就是社区里常说的Clawdbot是我今年花最多时间折腾的开源Agent运行时它的Skills机制、常见模型对接方式以及云上和本地两套部署路径基本可以覆盖从个人玩具到小团队助理的完整迭代过程。这篇东西不打算重复官方文档我基于自己从Windows本地到云服务器完整跑通的经历把OpenClaw从安装初始化、模型配置、Skills安装到Channel接入和踩坑排错整个过程全部按实操顺序写清楚。适合两类人一类想在本地电脑上跑通OpenClaw玩Skills的人另一类想让Clawdbot挂到飞书或Slack上24小时在线的团队。1. 拆开Clawdbot的引擎盖OpenClaw到底由哪几部分组成先花几分钟把概念理清楚。很多人在搜索时才意识到“OpenClaw”和“Clawdbot”到底是不是同一个东西其实这俩的关系很简单OpenClaw是整个项目的名称也是你装在系统里的那个框架本体Clawdbot是它跑起来之后的常驻Agent实例。可以类比成“Node.js”和“node server.js”跑起来的进程或者“Python”和“跑起来的解释器”。社区里说“部署一个Clawdbot”本质上是装好OpenClaw之后初始化一个bot角色让它长期干某类活儿。1.1 三层架构引擎、Paw CLI、扩展生态我自己比较喜欢把OpenClaw拆成三个层面来理解这样后面操作时不会被概念绕晕。第一层是核心调度引擎。它负责维护模型的对话循环、工具调用的决策、记忆读写、多轮上下文管理。这一层你平时看不见但它决定了Agent是“有脑子的助手”还是“只会复读的聊天机器人”。第二层是Paw CLI和Clawdbot进程。Paw是OpenClaw自带的命令行管理工具类似claw命令负责安装、初始化、查看日志、管理Skills、切换Channel。Clawdbot则是常驻后台的运行进程它把配置文件中定义的角色、模型、渠道全部加载起来在对应平台接收消息并触发动作。第三层是Skills扩展生态。Skills是OpenClaw最重要的差异化设计简单说就是给Agent预置的“技能包”。一个Skill可以是纯指令模板也可以是带脚本的工具封装。比如你可以给Clawdbot装一个PDF解析Skill它就能在对话里直接读取PDF文件并总结内容装一个图片生成Skill它就能根据你的描述调用绘图API。把这层结构看明白之后你就知道为什么OpenClaw部署麻烦但值得折腾了模型可替换、渠道可替换、技能可替换三层相对解耦想换掉哪一块都不需要推倒重来。1.2 它和Dify、Claude Code、Codex这类工具的差别现在市面上的Agent工具很多我在部署过程中也反复对比过梳理一张表方便你判断自己到底需要哪个工具/框架核心定位和OpenClaw的差异Dify / LangFlow可视化工作流编排偏流程设计和知识库OpenClaw更偏长驻对话式Agent的运行时Claude Code / Codex CLI编码辅助Agent面向IDE和命令行编码场景OpenClaw是多渠道通用Agent前端、办公、图片生成等技能都有AutoGPT自主任务执行确定性更弱OpenClaw的Skill模板让调用更可控自研脚本API调用自己写死逻辑每次新场景都要从头写OpenClaw用Skills和模型自主决策降低开发量我个人的判断是如果你只是想要一个帮你写代码的终端助手直接用Claude Code或Codex就行如果你想在飞书和Slack里养一个能处理多种事务的员工或者想用自己的本地模型搭一套可扩展的Agent那OpenClaw是更合适的底座。1.3 为什么Skills才是部署的重头戏现在各大Agent框架都在卷“技能/工具调用”但OpenClaw把Skills做成了类似“包管理”的体系。它有一个技能目录、一套SKILL.md描述规范、还有社区维护的superpower skills合集。这意味着你不需要从零写代码很多通用能力装完就能用。后面第三部分我会详细展开Skill的安装和手写方法这里先记住一个结论Skills决定了Agent能干什么模型决定了Agent聪明程度Channel决定了Agent在哪干活。三者各管一摊部署时不要混在一起考虑。2. 本地部署完整实操Windows、Linux、macOS三条路径我都跑通了一遍本地部署最大的优势是数据不出门、调试方便、不花钱。我把三个平台的流程分别跑了一遍下面按踩坑程度从低到高排列。2.1 环境准备三套系统的差异对照先看一张环境准备对照表这是我从多次安装中提炼出来的最小依赖清单系统必装依赖推荐方式难度macOSNode.js 22GitHomebrewHomebrew安装OpenClaw低Ubuntu 22.04/24.04Node.js 22Gitcurlcurl脚本或npm全局安装低Windows 11WSL2 Ubuntu 22.04Node.js 22在WSL2里装Linux版OpenClaw中高Node.js版本很关键。OpenClaw对Node版本有一定要求太老的版本18以下在加载部分Skills时会出现原生模块编译失败的问题。我建议直接用nvm管理Node版本# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 加载 nvm export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh # 安装 Node.js 22 LTS nvm install 22 nvm use 22Windows用户特别注意不要直接在Windows命令提示符里装OpenClaw我实测最稳定的路径是先装好WSL2和Ubuntu然后在Ubuntu里走Linux安装流程。网上有报错“openclaw could not safely verify the wsl2 environment”绝大多数是因为Windows侧的WSL2配置有问题我在第五部分会写详细排查过程。2.2 安装OpenClaw并完成初始化Linux/macOS通用安装命令如下curl -fsSL https://get.openclaw.ai/install | bash如果官方脚本因为网络原因拉不下来可以退而求其次用npm安装npm install -g openclaw安装完成后验证版本claw --version初始化项目claw setup第一次运行会问你几个问题默认模型Provider、是否启用记忆、默认Channel等。这里我建议不要全部用默认值可以把Channel先选成terminal方便本地测试。等后面接入飞书或Slack时再改配置。初始化完成后配置文件在我的环境里位于~/.openclaw/config.yaml。下面是我在本地测试阶段用的配置你可以直接抄model: provider: anthropic name: claude-sonnet-4-5 max_tokens: 4096 memory: enabled: true type: local max_entries: 200 channel: primary: terminal terminal: prompt: clawbot skills: auto_approve: ask allowlist: []auto_approve: ask的意思是当Agent判断需要调用某个Skill时先在终端里征求我的同意。这个设置对本地调试非常友好不会因为误触发技能而浪费API额度。2.3 接入本地模型Ollama、千问、DeepSeek的配置方式OpenClaw吸引人的一点就是模型层做得很松不绑死某一家。我有三分之一的时间都在折腾各种模型这里给出三种典型接入方式。方式一Ollama本地模型如果你手头有块像样的显卡或者只是想用纯本地模型测试Ollama是最快的路子# 安装 Ollama curl -fsSL https://ollama.com/install.sh | sh # 拉取一个适合对话的模型 ollama pull qwen3:32b # 确认服务正常 ollama list然后在OpenClaw配置里切换到Ollamamodel: provider: ollama base_url: http://localhost:11434 name: qwen3:32b注意Ollama默认只监听本机地址如果OpenClaw和Ollama不在同一台机器需要设置OLLAMA_HOST0.0.0.0并放行11434端口。这个在云上部署时会用到。方式二千问/DashScope想让Clawdbot用国内大模型可以走DashScope的OpenAI兼容接口。配置方式也简单model: provider: openai base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 name: qwen-plus api_key_env: DASHSCOPE_API_KEY然后在环境变量里放DASHSCOPE_API_KEY。OpenClaw对OpenAI兼容接口的支持很成熟大部分国产模型的兼容端点都可以用这个套路接进来。方式三DeepSeek或MiniMaxDeepSeek同样有OpenAI兼容接口把base_url换成DeepSeek的API地址、模型名改成deepseek-chat就行。MiniMax h3本地部署则是另一条路如果你是想在本地把MiniMax模型跑起来建议搭配vLLM或LM Studio提供OpenAI兼容服务然后在OpenClaw里把它当自定义provider用。接入完成之后在终端里执行claw chat输入一句你好介绍一下你自己能正常回复就说明模型链路通了。2.4 本地跑通第一个Skills调用模型通了之后随便装一个简单Skill验证技能链路claw skills install community/current-time claw run 现在几点钟如果它返回了当前时间说明Clawdbot已经从“只能聊天”升级成“会调用工具”的状态。到这里本地部署就算真正跑通了后面再往Skills和Channel方向扩展。3. Skills技能系统从安装社区技能到自己手写SKILL.md如果只把OpenClaw当聊天机器人用那有点浪费。Skills才是它值回票价的部分。这一章我会讲清楚Skill的底层规范、安装命令、实用推荐以及怎么手写一个自己的Skill。3.1 SKILL.mdOpenClaw技能的核心规范一个Skill本质上是一个目录目录里有一份SKILL.md文件用YAML前置元数据加Markdown指令体来描述技能。当Agent在对话中判断需要执行某个任务时它会读取对应SKILL.md里的description字段决定是否激活这个技能。SKILL.md的骨架长这样--- name: pdf-summary description: 读取PDF文件并生成结构化中文摘要。当用户提到PDF、论文、报告等关键词时使用。 --- # PDF 摘要技能 ## 使用场景 - 用户提供PDF文件路径 - 用户要求总结文档内容 ## 执行步骤 1. 使用 python3 脚本解析PDF文本 2. 将文本分段送入模型进行摘要 3. 输出包含「核心论点」「关键数据」「待办事项」的结构化结果 ## 注意事项 - 如果单页文本超过模型上下文先按页拆分再摘要注意description字段要写得尽量语义明确。因为模型是根据描述来判断技能适用场景的如果你写得太泛Agent可能在完全不相干的任务里误触发写得太窄则该用的时候又想不到它。3.2 安装技能从官方市场和superpower skills开始OpenClaw有一个内置的技能市场搜索和安装都很方便# 搜索技能 claw skills search pdf claw skills search image # 安装技能 claw skills install community/pdf-tools claw skills install community/image-gen # 卸载技能 claw skills uninstall community/pdf-tools社区里流传度很高的superpower skills是一个技能合集包包含大量通用型技能模板。安装方式claw skills install superpowers装完之后可以用claw skills list查看当前已安装的技能清单。第一次看到长长列表时可能有点懵但别急Agent只在合适时机才会调用它们。3.3 我实测过值得保留的Skills清单下面这些是我在真实场景中用过且觉得靠谱的技能按用途分类列给你技能名称类别具体用途pdf-tools文档处理PDF文本抽取、表格提取、合并拆分mineru-web文档转换把图片、PDF转成结构化Markdown效果很稳定arxiv-daily论文跟踪按研究方向拉取当天的arXiv论文列表paper-summary论文摘要生成带核心贡献、方法、实验对比的深度论文摘要image-gen图片生成集成了常见的文生图APIAgent可按描述调参数excel-wizard表格处理读取Excel、做清洗、生成透视表结果frontend-builder前端开发根据需求描述生成前端页面骨架文件codex-skills编程辅助在Agent里封装代码生成与lint修复流程这里想特别提一下mineru-web。在我多轮测试中它对中文PDF和扫描件的转换效果好于大部分同类方案基本能直接当文档解析管线用。你在做知识库、批量处理资料时这个Skill的价值会非常明显。3.4 手写一个Skill会议纪要转待办清单自己写Skill不需要懂得很深的编程。我拿一个我日常在用的“会议纪要转待办”技能当例子完整代码量很少--- name: meeting-actions description: 从会议纪要文本中提取待办事项、责任人、截止时间并输出Markdown格式的任务清单。当用户粘贴会议纪要或提到会议、待办、行动计划时使用。 --- # 会议纪要转待办 ## 处理流程 1. 阅读用户提供的会议内容 2. 识别每个讨论主题下的「决策」「待办」「责任人」「截止日期」 3. 对信息不完整的条目用「未指定」标注不要编造 4. 输出格式如下 ## 输出模板 ### 待办事项 - [ ] 事项描述责任人XXX截止YYYY-MM-DD ### 风险提醒 - 列出所有截止时间在3天内的任务把这个文件放到~/.openclaw/skills/meeting-actions/SKILL.md然后执行claw skills scan再开一个对话随便粘贴一段会议纪要你会发现Clawdbot能自动调起这个技能输出结构化的待办清单。整个过程不需要写任何业务代码只靠指令模板。如果你想写带脚本的Skill也只需要在Skill目录里放一个script.py或run.sh在SKILL.md里用命令调用它即可。答案核心是让模型能通过描述找到技能并用指令模板约束它的输出行为。3.5 Skills调试的两个实用办法第一强制触发。调试某个Skill时不要等模型自己判断直接输入claw run 使用 meeting-actions 技能处理以下内容...第二看日志。OpenClaw在~/.openclaw/logs/目录下会记录每次技能调用的状态码和执行结果。如果技能没被触发或执行出错先从日志里搜skill关键词基本能定位到是“描述不匹配导致未被触发”还是“脚本报错导致执行失败”。4. 云上部署让Clawdbot变成7x24小时在线员工本地部署适合开发和调试但想让Clawdbot稳定挂在飞书、Slack、Discord上还是得上云。这一章讲完整云端部署流程以Ubuntu服务器为例。4.1 上云之前的三个决策点决策一服务器规格。我实测下来如果只是跑Agent调度加上调用云端API的模型2核4G的服务器完全够用如果你想在云端同时跑Ollama或MiniMax本地模型那至少要4核16G起步还得有GPU成本会高很多。我的建议是先小后大把Agent跑稳了再加本地模型。决策二Docker还是systemd。两种方式各有优势。Docker隔离性好、迁移方便、升级简单systemd更贴近操作系统原生管理日志查看直接journalctl -u clawbot。我个人更推荐Docker尤其是服务器上还有其他服务时。决策三Channel选哪个。如果只是自己用选Telegram或Discord比较方便如果是团队内部用国内团队优先飞书海外团队优先Slack。这个选择会影响后面的回调地址配置。4.2 Docker部署Clawdbot的完整流程先装好Docker和Compose插件curl -fsSL https://get.docker.com | sh systemctl enable docker systemctl start docker然后准备一个docker-compose.ymlservices: clawbot: image: ghcr.io/openclaw/openclaw:latest container_name: clawbot restart: always volumes: - ~/.openclaw:/root/.openclaw environment: - OPENCLAW_API_KEY${OPENCLAW_API_KEY} - DASHSCOPE_API_KEY${DASHSCOPE_API_KEY} - CLAWBOT_CHANNELfeishu ports: - 8080:8080启动之前在同一个目录创建.env文件把所有密钥放进去OPENCLAW_API_KEYsk-ant-xxxx DASHSCOPE_API_KEYsk-xxxx注意一定不要把这些密钥写进docker-compose.yml本身否则一旦上传到Git仓库就相当于泄漏了全部凭证。启动服务docker compose up -d docker compose logs -f clawbot看到日志输出“Bot started successfully”就说明Clawdbot已经在云端跑起来了。4.3 systemd方式适合不喜欢容器的人如果你更习惯传统方式用systemd管理也没问题。创建/etc/systemd/system/clawbot.service[Unit] DescriptionOpenClaw Clawdbot Service Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Userclaw WorkingDirectory/home/claw/.openclaw ExecStart/usr/local/bin/claw bot run Restartalways RestartSec10 EnvironmentFile/etc/clawbot.env [Install] WantedBymulti-user.target然后systemctl daemon-reload systemctl enable --now clawbot systemctl status clawbotsystemd方式的好处是开机自启、崩溃自动拉起都是系统级保障不需要额外维护容器。4.4 接入飞书、Slack、Discord的完整配置Channel配置是所有步骤里最容易被卡住的一环。核心原理都差不多你在对应平台创建一个应用/机器人拿到凭证再把接收消息的地址指到OpenClaw。飞书接入步骤打开飞书开放平台创建企业自建应用。在「应用能力」中开启机器人能力。在「凭证与基础信息」中拿到App ID和App Secret。在「事件订阅」中配置请求地址。如果你用的是Docker方式地址就是https://你的域名/feishu/event如果是本地测试可以用内网穿透工具把本地端口映射成公网URL。订阅接收消息事件并添加加密验证密钥Encrypt Key。然后在OpenClaw配置里增加channel: feishu: app_id: ${FEISHU_APP_ID} app_secret: ${FEISHU_APP_SECRET} encrypt_key: ${FEISHU_ENCRYPT_KEY}重启Clawdbot后在飞书里给机器人发一条“你好”正常回复就说明接入成功。Slack接入步骤在Slack API页面创建一个新App选择“From scratch”。添加Bots权限配置Bot Token Scopes通常需要chat:write和commands。如果使用Socket Mode直接开启并拷贝App-Level Token不需要公网回调地址对没有公网IP的部署场景最友好。如果不用Socket Mode则配置Event Subscriptions的Request URL指向https://你的域名/slack/events。Discord接入步骤Discord更简单在开发者平台创建应用、添加Bot、拿到Bot Token后配置到OpenClaw即可。Discord的Bot Token直接作为凭证使用不需要回调URL。4.5 Channel路由多个平台同时挂载时的消息调度如果同时接了飞书、Slack、Discord你需要告诉Clawdbot优先接哪个渠道的消息。配置里可以指定channel: primary: feishu routing: allow: - feishu - slack deny: - discordprimary决定Agent的默认输出渠道比如定时任务推送、后台通知都会走这个渠道。routing里的allow和deny控制哪些渠道的消息能触发Agent。这个设计很实用比如你只想在飞书和Slack里启用AgentDiscord只做通知接收就可以用deny把它屏蔽掉。还有一个细节如果同一个用户同时绑定了多个平台Agent会基于配置去重避免在多个窗口重复回答同一句话。这点在团队使用时特别重要不然飞书和Slack会同时刷出两条一样的回复。4.6 云服务器加HTTPS反代与安全配置直接裸奔用IP访问飞书回调地址很不安全而且飞书要求回调地址必须是HTTPS。我推荐用Caddy做反代因为它自动申请和续期证书配置几乎零成本。# 安装 Caddy apt install caddy创建/etc/caddy/Caddyfilebot.example.com { reverse_proxy localhost:8080 }启动Caddy后它会自动为你申请Lets Encrypt证书然后你就可以用https://bot.example.com/feishu/event配置飞书回调了。安全配置还有三条底线一是SSH端口不要用默认22二是用ufw放行必要端口一般就80、443、22、8080三是所有密钥放进环境变量文件并设置chmod 600权限。5. 我在实际部署中踩过的坑完整排查链路与解法这一章写我自己的实战排错过程不直接给结论重点教你排查思路。5.1 “Could not safely verify the WSL2 environment”的完整定位过程这个报错我在Windows环境部署时印象很深。当时的情况是Windows 11系统已经装了WSL2和Ubuntu 22.04但在运行claw setup时弹出了“could not safely verify the wsl2 environment”直接中断安装。我第一反应是检查WSL本身是否正常于是执行wsl --status wsl -l -v结果发现Ubuntu确实运行在WSL2版本上内核版本也正常所以问题不在虚拟化平台本身。第二步我检查了OpenClaw的安装日志发现它报错前先尝试读取/etc/resolv.conf和Windows侧的注册表信息。这时才想到问题出在WSL发行版不是从默认位置挂载的或者系统中存在多个WSL发行版导致路径判断异常。解决方法是修复默认发行版wsl --set-default Ubuntu-22.04 wsl --shutdown重启WSL之后重新运行claw setup问题就消失了。如果你也遇到这个报错按这个顺序排查先确认WSL版本是2再确认默认发行版唯一最后把OpenClaw的安装日志打开看它具体卡在哪个系统调用上。不要去网上随便找脚本改注册表很多时候只是多发行版冲突的问题。5.2 飞书消息输出被截断的深层原因与解法搜索热词里“openclaw在飞书输出容易被截断”出现频率很高我也被这个问题坑过。飞书机器人单条文本消息有大小限制而Clawdbot输出长内容时经常直接超限用户看到的就是后半段消息莫名其妙不见了。排查时先在OpenClaw日志里找到了飞书API返回的“invalid message size”错误确认是长度限制导致。解决思路有两个方向。第一配置消息分片。在飞书Channel配置里增加channel: feishu: message_chunk_size: 4000 chunk_strategy: split_by_newlinesplit_by_newline会让Agent优先按换行符切分消息而不是硬生生按字符截断可读性会好很多。第二把长内容转成文件发送。对于超长报告或日志直接发文本体验很差我后来让Skill把长输出落盘并上传为飞书云文档或图片阅读体验提升非常明显。5.3 本地小模型在长任务中频繁掉链子的处理思路用Ollama跑本地模型时我最开始图省事拉了一个7B量级的模型结果Clawdbot在长对话里频繁出现“生成不完整”“上下文超限”的情况。原因很简单小模型上下文窗口有限、长文本生成稳定性差不是OpenClaw的问题是模型本身能力瓶颈。处理方式有三种按推荐程度排序换更大参数量的模型。我的经验是本地部署至少用32B级别比如Qwen3:32B并用量化版本控制显存占用。开启上下文裁剪。OpenClaw配置里的max_entries可以控制短期记忆条数设置成合理值可以防止上下文无限膨胀memory: enabled: true max_entries: 50复杂任务拆成多步子任务不要让Agent一次性处理超长文本。比如一个PDF解读任务先用pdf-tools提取章节再逐章总结最后合并成全文摘要。5.4 云服务端口占用和容器重启循环的处理Docker部署时我遇到过Clawdbot容器无限重启的情况。docker compose logs里只重复出现“Address already in use”排查一看是服务器上另一个服务占用了8080端口。这是新手最容易忽略的问题——云服务器上往往跑了很多东西端口冲突概率比本地高得多。解决起来很简单执行ss -tlnp | grep 8080找到占用进程然后决定停掉占用进程或者修改Clawdbot的端口映射。我最后把Clawdbot改到了9180端口ports: - 9180:8080这个坑提醒我一点上云之前先梳理服务器上已有的服务端口别假设端口一定空闲。5.5 多实例冲突同时跑本地和云端Clawdbot的注意事项我自己有段时间同时在本机和云服务器上跑了两个Clawdbot实例结果本机测试时收到的消息被云端实例抢答了。原因是两边的配置里用了同一个飞书App凭证导致飞书同时向两个地址推送事件。解决办法很简单开发机用一套测试应用凭证生产环境用另一套正式应用凭证两套凭证隔离。如果你确实只用一个凭证那就只能跑一个Clawdbot实例不要在多个环境同时连到同一个Channel应用。最后再分享一点我自己在实际操作中的体会OpenClaw这套体系真正难的不是安装命令而是把“模型、Skills、Channel”这三件事想清楚再动手。我第一次部署时急着把飞书、Slack、Ollama全部配上结果报错后排查范围太大花了大半天才定位到是飞书回调地址的问题。后来学乖了按这个顺序来先本地终端跑通对话再装Skill验证工具调用最后才接Channel。每加一个环节就完整测试一轮整个流程反而顺畅很多。另一个体会是Skills不要贪多。我知道有人一口气装了上百个技能结果Agent在判断时经常选中不合适的那个。我现在只保留高频使用的大约十五个技能并且会为每个私有场景手写专用的SKILL.md模板使用效果比装一大堆通用技能好得多。如果你想把Clawdbot变成真正的“团队数字员工”建议第一步先选定一个核心场景做深。比如先让它处理周报汇总、PDF解析和飞书通知推送稳定运行一个月之后再逐步加图片生成、前端开发这些更重的技能。一步一步来这套系统能折腾出非常多花样。
