1. 项目认知OpenClaw 到底解决了什么问题为什么2026年大家都在折腾它先把一个容易混淆的点说清楚。很多人看到 OpenClaw 这个名字会以为它是某个新出的聊天机器人或者套壳应用。实际上OpenClaw 是一个以Clawdbot为核心形态的个人 AI 代理框架核心能力是让一个数字分身帮你去操作电脑、调用工具、处理文件、对接各种应用而不仅仅是在对话框里跟你聊天。它之所以在 2026 年突然火起来是因为过去一年里代理式 AIAgentic AI从一个概念变成了实实在在能跑的东西而 OpenClaw 恰恰把代理该怎么写、怎么跑、怎么接 Skills这整套流程给标准化了。那 Skills 又是什么你可以把它理解成给 AI 代理装上的技能插件。OpenClaw 本身只提供一套运行环境和调度逻辑真正让它能干活的是挂载在它身上的一个个 Skills。比如你有写文案的需求装一个文案协作 Skill你有本地知识库检索的需求装一个RAG 检索 Skill甚至你想让它帮你操作 Obsidian 笔记库也有现成的 Skill 可用。这个设计很像手机上的应用商店——系统是底座Skills 才是真正让用户觉得值了的部分。这篇内容适合谁来参考我觉得是三类人。第一类是刚接触 AI 代理、想在自己的电脑上跑通一个能干活的 AI 助手的开发者第二类是有云服务器资源比如阿里云、腾讯云的轻量应用服务器但一直没想好拿来干什么的个人站长第三类是已经在用 Claude Code、Codex 这类工具、想进阶到自定义 Skills 开发的玩家。无论你是哪一类按照这篇文章的流程走一遍应该都能在半天内把 OpenClaw 跑起来并且理解它背后的设计逻辑。2. 部署方案选型云上和本地到底怎么选各自的坑在哪里2.1 两条路线的本质差异模型在哪、数据在哪、调度中心在哪先别急着照着教程敲命令选型这一步如果不打好底子后面很容易浪费时间。OpenClaw 的部署本质上要解决三件事模型推理放哪、代理控制进程跑在哪、Skills 和配置数据存哪。本地方案里这三样通常都在你的一台电脑上。模型的推理靠本地 Ollama 或者 LM Studio 拉起的大模型完成代理控制进程在后台常驻Skills 直接放到指定的目录里。这种方案的优点是隐私性好、不依赖公网、不产生推理费用电费另算缺点是需要一台配置还过得去的机器。比如你要跑 7B 参数级别的模型做日常任务16GB 内存起步、显存 6GB 以上会比较舒服如果你非要跑 70B 级别的模型那基本就进入工作站级别了。云上方案恰恰相反模型的推理一般跑在云端 API 或者云服务器自带的 GPU 上代理控制进程跑在一台 24 小时开机的云服务器上Skills 也存放在云端。这样你出门在外、手机随手连一下代理照样能干活这是本地方案做不到的。缺点是要花钱、要考虑数据出网的合规性。但如果你是拿个人服务器做实验、跑内部工具云上方案的便利性会远超本地方案。我的建议是这样的如果你只是想在办公室或者家里自己用优先做本地部署如果你希望这个代理变成一个永不下线的服务或者你手头已经有一台闲置的云服务器那直接做云上部署。2.2 为什么优先选 Docker 而不是裸机安装在正式讲操作流程之前我想先强调一个贯穿全程的原则OpenClaw 的部署强烈建议用Docker而不是在宿主机里裸装。原因有三点。第一是隔离性。OpenClaw 的依赖链条很长涉及到 Node.js 运行时、特定版本的 Python 环境、各种二进制工具比如浏览器自动化依赖、文件解析依赖等。裸机安装时这些依赖很容易跟你机器上现有的环境串版本最常见的就是 Node 版本不对导致编译失败或者 Python 包冲突导致某个 Skill 无法加载。Docker 镜像把整套运行时环境打包好了你拉下来就能跑不会污染宿主机。第二是可移植性。你在本地调通的整个环境拿到云服务器上用同一套 Docker Compose 文件直接起来几乎不会出差错。这里说的几乎是我实测后的结论因为云服务器的 CPU 架构x86_64跟本地的苹果芯片ARM64在镜像拉取时会自动选择对应平台版本OpenClaw 官方镜像对这两个平台都做支持。第三是易清理。玩 AI 代理的人很容易三天两头改配置、换模型、试新 Skill时间久了系统里就会残留一堆不知道能不能删的文件。Docker 的方案下你只要把容器删掉环境就干干净净了。3. 云上部署实操从零开始把 OpenClaw 跑在一台 24 小时在线的服务器上3.1 云服务器选型与初始配置要点踏上云上部署这条路第一步是搞一台服务器。拿我亲身实践过的配置来说2核4G 的轻量应用服务器足够跑起 OpenClaw 控制进程和一个 7B 级别的量化模型。如果你打算用国内云厂商的 GPU 实例去跑大模型那配置另说但大多数人做云上部署是为了代理常驻 接云端推理 API并不需要自己扛模型的推理所以 2核4G 是性价比最高的起点。服务器操作系统建议选Ubuntu 22.04 LTS或者Debian 12这两个系统的软件源最全遇到问题搜索到的解决方案也最多。拿到服务器后先做三件基础的事情更新系统软件源apt update apt upgrade -y这一步能避免后续装 Docker 时遇到过期的系统依赖。创建非 root 用户强烈建议OpenClaw 的容器如果以 root 权限运行一旦文件挂载目录被写坏排查起来会非常痛苦。创建一个claw用户后续所有操作都在这下面执行。调整 Swap 分区4GB 内存的服务器跑 Node.js 进程加上偶尔启动的模型调度内存可能会吃紧。建议创建一个 4GB 的 Swap 文件防止 OOM内存溢出导致进程被杀。3.2 Docker 安装与 OpenClaw 容器启动全流程系统基础准备好后开始安装 Docker。这里我推荐用 Docker 官方一键脚本省心且不易出错curl -fsSL https://get.docker.com | sh systemctl enable --now docker装好 Docker 后确认一下服务状态是 active (running)然后创建一个工作目录来存放 OpenClaw 的配置和数据mkdir -p /opt/openclaw/{config,skills,data}接下来是核心部分写一份 Docker Compose 文件。下面是我在云上部署时实际使用并验证通过的docker-compose.ymlversion: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 8080:8080 environment: OPENCLAW_API_KEY: your-api-key-here OPENCLAW_MODEL_PROVIDER: anthropic OPENCLAW_MODEL_ID: claude-sonnet-4-5 OPENCLAW_CHANNEL: web OPENCLAW_STORAGE_DIR: /data TZ: Asia/Shanghai volumes: - ./config:/root/.openclaw - ./data:/data - ./skills:/root/.openclaw/skills说明一下几个关键环境变量的作用。OPENCLAW_API_KEY是 OpenClaw 服务对外暴露的访问凭证相当于你这台代理服务的大门钥匙一定要用足够复杂的随机字符串。OPENCLAW_MODEL_PROVIDER和OPENCLAW_MODEL_ID决定了代理大脑用谁家的模型如果接的是 Anthropic 官方 API 就填上面的值如果你要接国内可直连的接口这一块的配置差异我会在后面的常见问题章节专门展开。启动命令非常简单cd /opt/openclaw docker compose up -d日志文件可以用docker logs -f openclaw查阅。如果看到类似Server started at http://0.0.0.0:8080的输出说明代理控制进程已经起来了。这时候访问http://服务器公网IP:8080再加上你在环境中配置的 API Key就能看到 OpenClaw 的 Web 管理界面。3.3 云上部署成功的关键安全组、端口与反向代理很多人在云上部署卡在容器明明起来了但浏览器就是打不开十有八九是安全组忘了放行端口。无论你用的是阿里云、腾讯云还是华为云都需要在服务器的安全组规则里放行 8080 端口如果只做 API 调用只对自家 IP 放行更安全如果有 Web 界面需求就配合 API Key 使用。放行端口后我建议再加一层Caddy 反向代理这样可以通过域名访问而不用记 IP 加端口。Caddy 的配置很简单核心就几句话your-domain.com { reverse_proxy 127.0.0.1:8080 }Caddy 会自动申请和续期 HTTPS 证书比起手工配 Nginx 加证书要省心得多。这一步做完你的 OpenClaw 服务就有了一个安全、稳定的对外入口。4. 本地部署实操用自己的电脑跑起 OpenClaw 全栈环境4.1 安装前准备Windows、macOS、Linux 三种系统的注意点本地部署跟云上部署最大的不同在于你有机会接触到完整的 Skills 开发与调试环境也有可能在本地把模型推理一起跑起来。我先分开说三种系统的注意点再给出一套跨平台通用的方案。Windows 用户要额外留意两个东西一是 Docker Desktop 需要开启 WSL 2 后端二是在 PowerShell 里跑docker命令时需要注意执行策略。我踩过的一个坑是 Docker Desktop 装好后容器起不来最后发现是 Windows 的 Hyper-V 没有被正确启用。如果你遇到类似问题先去启用或关闭 Windows 功能里勾选虚拟机平台和适用于 Linux 的 Windows 子系统然后再重装 Docker Desktop。macOS 用户相对省心装好 Docker DesktopApple Silicon 芯片的就选对应版本之后唯一要留意的是性能分配。默认给 Docker 分配的 CPU 和内存可能不够跑模型调度建议在 Docker Desktop 的设置里手动给到 CPU 4 核、内存 8GB 以上。Linux 用户直接走上一节讲的 Docker 安装脚本就行区别不大。4.2 一键部署脚本解读本地开发环境的标准姿态OpenClaw 社区里有一个很流行的本地一键部署项目我自己也在用。它的核心思路是把 Docker Compose 文件、模型拉取脚本和 Skills 安装脚本整合在一起通过一个入口命令完成所有初始化。这里我不贴整段脚本版本迭代较快但把它的关键步骤拆出来讲清楚这样即使官方脚本更新了你也能理解它做了什么。第一步是拉取镜像docker pull openclaw/openclaw:latest这个没什么好说的。第二步是拉起基础服务包括 OpenClaw 主容器和一个可选的 Ollama 容器用于本地模型推理。第三步是初始化 Skills 目录。脚本会在你的用户目录下创建一个.openclaw/skills文件夹并把官方默认的几个基础 Skills 克隆进去。这一步做的事你在手工部署时也需要自己完成。第四步是生成配置文件脚本会根据你的操作系统自动生成一个环境变量文件里面填好了默认的 API Key 和模型设置。这套一键脚本的价值不在于省去了几行命令而在于它把**环境准备、服务编排、配置生成、Skills 安装**这四个环节做了标准化。对于新手来说直接面对四五个配置文件的压力很大有了脚本打底你至少能先跑起来再逐步理解各部分的作用。4.3 本地模型接入让 OpenClaw 用上 Ollama 托管的开源模型如果你是冲着不花钱、不把数据发到云端来的那本地部署 OpenClaw 之后接上 Ollama 托管的开源模型是必做的一步。Ollama 是目前最主流的本地模型运行工具安装后拉取模型、启动服务都是几行命令的事。先装 OllamaLinux/macOS 直接执行脚本Windows 有安装包然后拉一个适合做代理任务的模型。以我实测的体验来说Qwen2.5-7B-Instruct 和 DeepSeek-R1-Distill-Qwen-7B这两个模型在 OpenClaw 场景下表现比较平衡既能完成多轮工具调用又不至于让普通电脑跑不动。ollama pull qwen2.5:7b ollama serve接着在 OpenClaw 的配置里把模型 Provider 指向本地 Ollama。关键的环境变量大致如下OPENCLAW_MODEL_PROVIDER: ollama OPENCLAW_OLLAMA_BASE_URL: http://host.docker.internal:11434 OPENCLAW_MODEL_ID: qwen2.5:7b这里有个小细节要特别强调在 Docker 容器里访问宿主机上的 Ollama 服务不能直接写127.0.0.1而是要用host.docker.internal这个特殊域名Windows/macOS 的 Docker Desktop 默认支持Linux 需要额外加extra_hosts: - host.docker.internal:host-gateway到 Compose 文件里。我第一次部署时在这上面卡了半个多小时容器日志一直报连接拒绝后来才发现是地址写错了。接入完成后你可以在 OpenClaw 的对话界面问它一个问题同时在终端里观察 Ollama 的日志输出如果看到模型推理的 token 数据在滚动就说明整条链路已经打通了。5. Skills 机制深度拆解如何让 OpenClaw 真正变成你的专属数字员工5.1 理解 Skills 的本质一个带说明书的小工具包OpenClaw 的 Skills 机制说穿了就是一个约定好格式的工具包。每个 Skill 占用一个目录目录里必须有一个SKILL.md文件作为说明书Agent 会根据这份说明书判断什么时候该用这个技能、怎么用、应该注意什么。一个最简单的 Skill 目录长这样my-skill/ └── SKILL.mdSKILL.md的文件格式很关键它需要包含 YAML 格式的 frontmatter 和 Markdown 格式的正文。我见过社区里很多讨论为什么我的 Skill 不生效最终排查下来十有八九是 frontmatter 格式写错了比如字段拼写不对、冒号后面少了空格、或者没有缩进好。下面是一个能直接跑通的最小示例--- name: web_search description: 当用户需要查找最新信息、确定某个事实或需要当前事件的答案时使用此技能。 version: 1.0.0 --- ## 使用场景 - 用户询问最近发布的新闻。 - 用户想了解某个产品的最新版本信息。 - 需要确认某个实时数据。 ## 操作步骤 1. 调用内置的搜索接口输入用户提供的查询词。 2. 整理前5条搜索结果每条保留标题和摘要。 3. 返回结构化列表并注明信息来源。 ## 注意事项 - 如果搜索词太宽泛先通过追问帮助用户缩小范围。 - 永远不要捏造搜索结果。看到没有这个 Skill 的核心不是代码而是一段让 Agent读懂的操作说明。OpenClaw 的调度器会读这段说明然后在合适的时机调用 Skill 目录里附带的脚本如果有的话。这就是为什么社区里会说Skills 开发不需要会写代码但需要会描述流程。5.2 常用 Skills 来源开源社区、官方仓库、自建Skills 的获取渠道目前有三种主流方式。第一种是官方/社区仓库。OpenClaw 官方维护了一个 Skills 集合仓库里面包含 Web 搜索、文档解析、RSS 订阅、Obsidian 笔记操作等常用技能直接克隆到本地 Skills 目录即可生效git clone https://github.com/openclaw/skills-official.git ~/.openclaw/skills/official第二种是第三方源站。GitHub 上有不少开发者把自己积累的 Skills 公开出来常见的搜索关键词就是superpower skills、awesom-openclaw-skills这类。下载第三方的 Skills 时要特别留意两点一是看仓库的更新时间和 issue 区长期没人维护的基本可以跳过二是仔细阅读SKILL.md里的权限声明有些 Skill 会要求访问你的文件系统或者网络这个要心里有数。第三种是自己写。从模仿一个现有 Skill 修改成自己的需求是学习成本最低的路径。你先花半小时看明白一个官方 Skill 的目录结构再照葫芦画瓢改一个属于自己的这个过程获得的收获比直接抄十个 Skill 都大。5.3 让 Skills 挂载生效目录、缓存和重启的细节很多人装完 Skill 后发现代理的表现没有任何变化最经典的原因有三个目录位置不对、缓存没清、社区版不支持某个写法。先说目录位置。OpenClaw 在容器里默认读取的 Skills 路径是/root/.openclaw/skills但你是通过 Docker volume 挂载的所以最终生效路径取决于你 volume 映射到了宿主机哪里。如果发现新装的 Skill 没被识别先确认容器里的实际路径docker exec -it openclaw ls /root/.openclaw/skills再看宿主机挂载目录里的情况两边对不上那就说明挂载路径出问题了。其次是缓存问题。OpenClaw 会把已经加载的 Skills 列表缓存在内存和磁盘上我遇到过一次替换了 SKILL.md 内容后不生效的情况重启容器解决docker restart openclaw如果重启还不行试试清掉缓存目录容器里对应路径一般是/root/.openclaw/cache宿主机挂载目录对应位置删掉即可。5.4 手把手开发一个自己的 Skill 案例纸上得来终觉浅我拿一个具体需求来演示一遍完整的 Skill 开发流程。假设我要做一个本地文件检索的 Skill实现的效果是当用户说要找哪个文件时代理能自动在指定的目录里搜索。第一步建立目录结构。我在本地~/.openclaw/skills/file-search/下创建两个文件SKILL.md和search.py。第二步写SKILL.md--- name: file_search description: 当用户需要查找本地目录里的文件时使用此技能。可按照文件名关键词、扩展名或修改时间进行搜索。 version: 1.0.0 --- ## 使用场景 - 帮我找到上周的会议记录 - 我的下载目录里有没有 PDF 文件 - 查询 /opt/data 下所有包含 report 的文件 ## 操作步骤 1. 确认搜索路径默认是当前工作区也可以由用户指定。 2. 调用 search.py传入关键词和路径参数。 3. 返回文件列表包括完整路径、文件大小和修改时间。 ## 注意事项 - 禁止递归搜索系统目录如 /etc、/proc。 - 搜索不到结果时建议用户扩大关键词范围。第三步写search.py。这里用 Python 标准库就够了不需要额外依赖#!/usr/bin/env python3 import os import sys import argparse from datetime import datetime def search_files(root, keyword, extension): results [] for dirpath, dirnames, filenames in os.walk(root): # 跳过隐藏目录和系统目录 dirnames[:] [d for d in dirnames if not d.startswith(.)] for fname in filenames: if keyword and keyword not in fname: continue if extension and not fname.endswith(extension): continue full_path os.path.join(dirpath, fname) stat os.stat(full_path) results.append({ path: full_path, size: stat.st_size, mtime: datetime.fromtimestamp(stat.st_mtime).isoformat(), }) return results if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--path, default.) parser.add_argument(--keyword, default) parser.add_argument(--ext, default) args parser.parse_args() hits search_files(args.path, args.keyword, args.ext) for hit in hits[:50]: print(f{hit[mtime]} | {hit[size]:10} | {hit[path]}) if len(hits) 50: print(f... (共 {len(hits)} 个结果仅展示前 50 个))第四步在 OpenClaw 的对话里测试。你输入帮我在工作目录里找一个名字带 openclaw 的文件然后观察代理的表现。我的经验是第一次调用不一定成功原因通常是 Agent 不知道怎么把用户的话转成具体的路径参数。这时候你要回去改SKILL.md把步骤里搜索路径的说明写得再直白一些比如直接写默认使用 /opt/projects 作为搜索根目录。这个例子同时说明了另一个重要的观点Skills 开发的本质是写一个小工具 使用说明书的组合工具部分甚至可以用最朴素的脚本实现说明书部分反而是决定体验的关键。6. 常见故障排查与避坑实录6.1 高频报错session file locked (timeout 60000ms) 及其背后逻辑这个报错可能是你在部署和运行 OpenClaw 时接触到最多的一个异常信息是agent failed before reply: session file locked (timeout 60000ms)。我第一次看到它时第一反应是配置文件写坏了后来深入排查才发现这句报错的根源在于 OpenClaw 的会话管理机制。OpenClaw 会把当前会话的状态包括对话历史、临时变量、正在执行的工具调用上下文写入一个 session 文件。正常情况下下一个请求会等待上一个请求的会话文件释放锁。但如果上一个调用一直没有正常结束——比如某个 Skill 脚本卡住了、模型推理超时了、或者代理进程被强制中断——这个锁就不会被正常释放后续的请求就会等待直到 60 秒超时后抛出上面的错。排查步骤我整理成了三条先看完整日志docker logs --tail 100 openclaw重点找locked之前发生了什么。绝大多数情况你会发现前面卡着一个 Skill 调用。定位到是哪个 Skill 卡住后单独手动跑一遍这个 Skill 的脚本确认脚本本身能不能在合理时间内执行完。如果只是偶发情况直接重启容器恢复docker restart openclaw。如果是高频复现那就是某个 Skill 有 bug建议暂时把它从 Skills 目录移走再观察。这个报错让我明白了一件事OpenClaw 的并发能力是受会话锁限制的同一时间一个会话只能处理一个请求所以不要试图让它同时处理多个并行任务那不是它当前的设计目标。6.2 Channel 选择问题Web、CLI、API、Microsoft Teams 怎么配OpenClaw 支持的 Channel 是指代理的接入入口。常见的 Channel 有webWeb 界面、cli命令行、api对外 API 调用、teams接入 Microsoft Teams。不少人在配置这里栽了跟头症状是启动日志里报类似channel xxx not found或failed to connect channel的错误。根因通常是你在环境变量里设了一个 Channel但对应的依赖服务没有启起来。比如OPENCLAW_CHANNELteams这需要额外的配置Bot 注册信息、权限验证代码等不是填一个变量就能用的。所以我建议新手阶段只开一个 Channel先用web模式验证整个链路等熟悉了再去折腾多渠道接入。如果你确实要用 Microsoft Teams官方文档的流程我简单概括下你先要在 Teams 开发者平台建一个 Bot 应用拿到 App ID 和密码然后在 OpenClaw 的环境变量里配置对应的连接参数最后启动后还要在 Teams 里登录一次授权让代理能代表你的身份收发消息。整个过程走下来半天到一天是正常的别指望十分钟配完。6.3 国内网络环境下的模型接入问题Qwen、DeepSeek 怎么配在本地部署里很多人想接入国内可以直接访问的模型比如通义千问Qwen的 API或者用本地的 DeepSeek 蒸馏模型。配置思路是一样的改 Provider、改 Base URL、改 Model ID。以接入阿里云百炼平台的 Qwen API 为例关键环境变量是这样OPENCLAW_MODEL_PROVIDER: dashscope OPENCLAW_MODEL_ID: qwen-plus OPENCLAW_API_KEY: 你的百炼平台API Key OPENCLAW_BASE_URL: https://dashscope.aliyuncs.com/compatible-mode/v1注意dashscope这个 Provider 走的是OpenAI 兼容协议所以如果你的 Provider 名填成了openai也可以但那样就要自己拼 Base URL容易出错。用官方现成的 Provider 映射是最省事的。跑本地 DeepSeek 模型时思路一样只是 Provider 要改成ollamaModel ID 改成你在 Ollama 里拉取的模型名比如deepseek-r1:7b。这里有个经验不要在生产环境里把本地模型和云端模型混在一个配置里宁可多开两个容器、端口分开。否则你调试某一个模型的时候另一个模型的错误日志会干扰你的判断。7. 实际使用心得与效率建议7.1 我推荐的目录组织和配置管理方式OpenClaw 玩到后面最怕的就是目录越来越乱、配置改来改去忘了改了什么。我目前用的方案是用 Git 管理整个/opt/openclaw或者本地~/.openclaw下的配置目录每次改完配置和 Skills 都提交一个 commit。这样一旦新配置出了问题git diff能直观地告诉你改了什么git checkout -- .能快速回滚。另一个值得养成的习惯是永远不要把生产环境的 API Key 写在 docker-compose.yml 里。哪怕文件只是在服务器本机也要用环境变量文件的方式加载。具体来说创建一个.env文件里面写好所有敏感变量然后在 Compose 里用${VAR_NAME}引用。.env文件加入.gitignore防止误传远程仓库。7.2 从部署到日常维护的时间投入预期最后给大家一个真实的时间预期。如果你是第一次接触 OpenClaw纯新手走完云上部署选服务器、装 Docker、拉容器、打开 Web 界面大概需要两到三个小时本地部署则取决于你的电脑环境Windows 用户可能需要预留一个下午因为 Docker Desktop 和 WSL 的组合容易出些幺蛾子。真正花时间的不是部署本身而是调通一个能实际使用的工作流把自己常用的几个场景比如文件检索、网页搜索、笔记整理逐个配成 Skill然后根据实际效果反复修改说明书。这个过程我建议你放一个周末的时间去琢磨。我第一次搭好 OpenClaw 的时候觉得它不过是一个能调工具的大模型聊天框而已。但当我花一天半写完了三个顺手的小 Skills、并把它们组合成一个从收集资料到生成日报的自动流程之后我开始意识到OpenClaw 真正值钱的不是框架本身而是你愿意为它定制的那一层个人化能力。这套东西的扩展性极好你越用越会发现原来很多重复的、需要 PC 上操作的事务性工作是可以交给这个数字分身去做的。如果你在部署过程中遇到了我这里没提到的怪问题建议先去翻一下官方仓库的 issue 区输入你的报错关键词大多数情况下都能找到解决方案。折腾过一轮之后你会比任何教程都更懂你自己的这套代理体系。