先讲一个特别有画面感的场景：上周我在某个技术讨论区闲逛，有人发了一条动态，晒了一张终端截图——一个叫 OpenClaw 的项目跑起来了，正在自动整理他电脑里的文档。底下评论区有人问："这跟网页版 AI 有啥区别？"博主回了一句："网页版是替我聊天，这个是替我干活儿，而且是自己养的那种。"紧接着就有个热评："小龙虾自由了。"我当时就被"龙虾自由"这个词逗笑了。后来仔细琢磨了一下，这个梗还挺贴切：Claw 就是钳子，龙虾最显眼的就是那对钳子；而"龙虾自由"说的就是——不花订阅费、不依赖闭源服务，自己也养一只开源 AI 助手，想怎么折腾就怎么折腾。今天我把完整流程整理出来，从零开始到跑通，全程不需要你懂算法、不需要你写代码、也不需要你花钱买什么高级设备。只要你会复制粘贴命令，照着我这篇来，就能把 OpenClaw 免费部署起来。先说清楚一件事：标题说"10秒部署"，实际指的是核心启动命令只要几秒钟；从零准备环境到完全跑通，小白第一次操作大约需要二十到三十分钟。但一旦环境就绪，第二台机器上再部署就真的是十秒级别了。下面我按实际踩坑顺序来写，尽量让你的半小时不白费。1. 先说清楚 OpenClaw 是什么，以及"龙虾自由"到底在说什么如果你之前只接触过网页版对话 AI，可能会以为所有 AI 工具都长一个样：打开页面、输入问题、等回复。OpenClaw 不太一样，它更像是一个住在你电脑里的智能体。简单说，它不仅会"聊天"，还能以聊天的方式指挥它去操作：读取本地文件、执行命令行脚本、调用其他工具、定时完成任务、把结果整理成报告。你可以把它理解成"一个带着钳子帮你干活的助手"——这就是 Claw 的含义。我自己第一次跑通后的感觉是：这东西的爽点不在于"答得有多好"，而在于"它真能动手做事"。举个例子，我电脑里堆了几百个从网上下载的 PDF 和网页截图，以前想整理成读书笔记，得自己一一点开、复制、粘贴。部署 OpenClaw 之后，我告诉它"把 downloads 文件夹里所有 PDF 的第一页内容提取出来，按主题归个类，生成一份 Markdown 索引"，它大概跑了五分钟，把这件事做完了，虽然分类不算特别精准，但第一版草稿已经能省掉我大半天的重复劳动。"龙虾自由"的另一层含义是自治权。网页版服务通常有配额限制，对话次数多了要排队或者收费；OpenClaw 本身是开源项目，运行在你自己的机器上，模型也可以选择本地开源模型，断网时照样能干活。数据也是存在本地的，对于经常处理私人笔记、合同文稿的人，这一点特别重要。你自己的文件、你的对话记录，不需要上传到别人的服务器里。那它适不适合你？我认为只要满足下面任何一条，都值得装一个试试：经常有重复性文件处理任务，比如批量重命名、批量格式转换、文档摘要。想要一个能"动手执行"的 AI 助手，而不只是陪聊工具。对数据隐私敏感，希望 AI 操作本地文件而不经过第三方服务器。纯粹想折腾，喜欢研究开源工具，享受自己把系统跑起来的成就感。当然它也不是万能的。第一，它对命令行的依赖比网页版高，前期配置多少要碰一点终端，不过照抄命令就行。第二，本地小模型的理解能力确实不如大厂旗舰模型，遇到特别复杂的逻辑，需要你把任务拆得更细。第三，它更像一个工具集而不是保姆，你得告诉它步骤，它才能干活。后面我会专门讲怎么更好地"吩咐"它。2. 环境准备与方案选型：把"10秒"可能踩的坑都提前排掉很多人部署失败，不是项目本身难，而是环境没准备好就急着跑命令。OpenClaw 官方提供了两种主流部署方式：Docker 容器部署和 Node.js 源码部署。我建议你先花两分钟做个选择题，别上来就复制别人的命令，因为两种方式的依赖完全不同。先看看硬件要求。OpenClaw 本体是一个 Node.js 服务，内存占用其实不高，运行起来大约占用 200～400MB 内存。真正的资源大头是模型推理——如果你用纯本地模型，建议 16GB 内存起步，8GB 也能跑但会很吃力；如果你决定用云端模型 API，电脑只需要能流畅打开浏览器即可，4GB 内存都够用。磁盘方面预留 20GB 左右比较安心，因为本地模型文件动不动就是 4～7GB 一个。操作系统方面，Windows、macOS、Linux 都支持，区别只在于 Docker 的安装方式。2.1 环境自检清单：动手前先花五分钟验货不管选择哪种方案，你都先打开终端（Windows 用 PowerShell，macOS 用 Terminal），逐条跑一下下面的命令看是否已装好。# 查看系统基本信息 systeminfo | findstr /C:"OS Name" /C:"System Type" # 查看内存 wmic OS get TotalVisibleMemorySize # 查看磁盘剩余空间 df -hmacOS 和 Linux 上把第一条命令换成uname -a就行。重点检查两件事：内存是否大于等于 8GB，磁盘剩余是否大于 20GB。都满足的话，接着检查有没有安装 Docker 或者 Node.js。# 检查 Docker docker --version # 检查 Node.js node -v npm -v如果你的终端提示"command not found"或者版本号显示为 Node.js 版本低于 18，后面安装依赖的时候一定会报错。这里我给小白一个经验：Node.js 优先装 LTS（长期支持）版本，不要追最新版；Docker 优先装 Docker Desktop，安装完一定要启动一次，让它把底层虚拟机初始化好，否则后面拉镜像会莫名其妙失败。2.2 两种部署方案怎么选：Docker 还是源码跑我先把两个方案的核心差异做成一张表，你看完再选。对比项Docker 部署Node.js 源码部署环境隔离好，依赖不会污染系统一般，依赖装在系统里安装复杂度需要先装 Docker，再拉镜像需要先装 Node.js，再 npm install启动速度首次拉镜像慢，之后启动快首次装依赖慢，之后启动较快卸载干净程度容器删除即一切消失残留目录和进程需要手动清理改代码调试不友好，需重建镜像友好，改完重启即可适合人群不想折腾系统环境的小白想二次开发、改源码的进阶玩家我自己第一轮用的是 Docker，因为省心。你不需要关心 Node 版本、Python 环境、系统动态库这些乱七八糟的东西，一个容器全部搞定。第二轮为了改源码方便，我换成了源码部署，自此没再换回去。如果你现在不确定以后要不要二次开发，我建议第一轮先用 Docker 跑通，找找感觉，以后再迁移也不难，配置和数据都放在宿主机目录下，复制过去就能继续用。2.3 目录规划：给你的"龙虾"安排一个固定住所部署前我强烈建议规划一个干净的文件夹，比如用户主目录下新建 openclaw 目录，里面分三个子目录：app 放程序文件，data 放运行数据，config 放配置文件。这样做的最大好处是升级和卸载都很清晰，所有东西都圈在一个院子里，不会散落得到处都是。mkdir -p ~/openclaw/app mkdir -p ~/openclaw/data mkdir -p ~/openclaw/config在 Windows 上没有~这个写法，直接打开文件资源管理器，进入 C 盘或者 D 盘，新建 openclaw 文件夹，里面再建 app、data、config 三个子文件夹即可。这个小动作看似啰嗦，实际上是我踩过一次坑后长记性了——早期我随手在用户目录根目录下跑项目，后来配置、日志、缓存文件跟其他项目的混在一起，清理时根本分不清谁是谁。3. 核心实操：从拉取项目到跑通 AI 助手的完整过程环境准备好以后，真正的部署操作其实可以压缩到三步：拿代码、填配置、启动服务。下面我按照 Docker 方案为主线来演示，源码方案的区别点我会在对应位置单独标注。3.1 第一步：把项目代码拿到本地先进入你规划的 openclaw/app 目录，然后从代码托管平台克隆项目。以 Docker 版本为例，项目提供了 docker-compose.yml 文件，直接把它下载到本地即可。cd ~/openclaw/app git clone https://example.com/openclaw-project.git .如果你机器上没装 git，也可以直接去托管平台页面下载项目的 ZIP 压缩包，解压到当前目录。注意一个细节：解压后确认 docker-compose.yml 文件确实在 app 目录根下，而不是嵌套在下一级子目录里，不然后面docker compose up会提示找不到配置文件。3.2 第二步：编辑配置，告诉它用哪个模型进入 config 目录，新建一个 .env 文件（Windows 用户在资源管理器里新建文件然后重命名为 .env 即可，注意它没有名字前缀，只有后缀）。这个文件里保存的是运行时读取的参数。我贴一个最小可用的配置模板：# 服务端口，不改的话默认 8080 PORT=8080 # 数据存储目录 DATA_DIR=/app/data # 模型接口地址，本地模型留空则使用内置默认 MODEL_BASE_URL=http://127.0.0.1:11434/v1 # 模型接口密钥，本地模型可以填任意非空字符串 API_KEY=local-test-key # 使用的模型名称，需要和模型服务端已有的模型名一致 MODEL_NAME=your-model-name如果你完全不想付费，走本地模型路线，把 MODEL_BASE_URL 填成你本地模型服务的地址，API_KEY 随便填一个非空值，MODEL_NAME 填成你本地实际有的模型名。如果暂时不想折腾本地模型，又愿意花一点点钱用云端模型接口，就把 MODEL_BASE_URL 填成对应云服务商提供的接口地址，API_KEY 填你自己的密钥。我推荐新手第一轮先用本地模型，成本为零，环境闭环，彻底跑通了再考虑要不要上云端大模型。3.3 第三步：启动服务并观察日志配置写完，回到终端，确认当前在 app 目录，执行：docker compose up -d第一次执行会拉取镜像，时间取决于网络情况，一般是几分钟到十几分钟。看到 "Started" 或者 "Running" 字样就说明容器已经跑起来了。接着查看实时日志：docker compose logs -f日志里出现service is listening on port 8080之类的行，说明启动成功。源码方案在这个步骤的区别是先执行npm install装依赖，再执行npm run dev或node src/index.js启动，看到监听日志即为成功。3.4 验证部署：发第一条消息，别急着配花活服务启动后，打开浏览器访问 http://localhost:8080 ，能看到 OpenClaw 的对话界面。在那里面输入"你好，简单介绍一下你自己"，观察终端日志里是否出现了对应的请求处理记录。这一步的目的是确认从网页到服务再到模型的全链路是通的，而不是只看界面画出来就觉得成功了。我当时第一次部署完，看到界面高兴坏了，结果连发三条消息石沉大海，界面一直转圈，最后查日志才发现模型服务地址填错了。所以这里一定要做一次端到端验证。如果你走的是本地模型，这时候可能还要等模型文件加载，第一次加载可能持续几十秒，CPU 风扇会明显转起来，这是正常的。4. 启动失败、超时、配置不生效：我踩过的坑全记录跑通以后，我继续折腾了两三天，把几个高频问题都轮了一遍。每一个都是真实发生的，我直接把排查链路写出来，你遇到同款问题能少走弯路。4.1 端口被占用：启动报错后的正确排查姿势启动时如果看到Address already in use或者port is already allocated，说明 8080 端口已经被别的程序占用了。错误提示会直接告诉你哪个端口出问题，但不会告诉你谁占的。在终端执行：# macOS / Linux lsof -i :8080 # Windows netstat -ano | findstr :8080查到占用端口的进程 PID 后，如果确认不是你想保留的服务，就把它结束掉，或者直接改 OpenClaw 配置里的 PORT 为 8081，重新启动。这里有个教训：不要因为端口被占用就去重装 Docker 或者重装项目。端口问题只是配置层面的小摩擦，重装不会解决任何问题，只会浪费更多时间。用lsof或者netstat定位占用者才是正道。4.2 模型请求一直转圈或秒回错误：三步锁定问题源头我遇到的最难排查的问题是所有对话都回复"请求失败"。界面没给出任何具体信息，日志里只有一行failed to fetch model response。这时候不要看日志猜，直接从外到内逐层验证。第一，先用 curl 直接测试模型服务是否健康。curl http://127.0.0.1:11434/v1/models如果这条命令返回了一长串 JSON，说明模型服务没问题，问题出在 OpenClaw 配置或者网络链路。如果返回 connection refused，说明模型服务没启动，先启动模型服务再说。第二，确认模型名称。# 查看本地模型列表 ollama list你配置里的 MODEL_NAME 必须和模型列表里的名字一模一样，差一个冒号都会报错。云端接口同理，去服务商控制台确认你开通的模型名。第三，检查你的 API_KEY 是否正确。本地模型可以随便填，云端接口则必须真实有效，填错会返回 401 Unauthorized，日志里会有明确状态码。按这三步走，大多数"请求失败"都能在五分钟内定位。4.3 依赖安装 vendor 报错与 Node 版本不匹配源码部署时，npm install报各种红色警告甚至 error 的情况很常见。最常见的是The engine "node" is incompatible with this module. Expected version ">=18.0.0"。这行信息已经说得很明白了：你的 Node 版本太老。解决方案不是硬装，而是升级 Node。我当时的做法是装一个 Node 版本管理工具，用它切换到某个新版本，再重新安装依赖。版本切换完成后，记得先清理旧依赖再重装：npm cache clean --force rm -rf node_modules package-lock.json npm install如果是在 Windows 上，第三条命令里的rm -rf改成在资源管理器里手动删除 node_modules 文件夹。这个"清理三连"是解决依赖安装问题的一个通用手段，很多看似诡异的报错，清理干净后重来一次就好了。4.4 改了配置不生效：大部分人是忘了重启这个问题我犯过不止一次：改了 .env 里的配置，然后刷新网页，发现还是旧配置在生效，于是怀疑配置没写对，反复改来改去。原因其实特别简单——进程还是旧进程，配置文件只在启动时读取一次，不会热加载。正确做法是修改配置后重启服务。Docker 方式：docker compose restart源码方式：在终端按 Ctrl+C 停掉进程，重新执行启动命令。有个更容易被忽略的细节：Docker 的 Compose 文件里如果改了环境变量映射，或者改了端口映射，光 restart 不生效，要执行docker compose down && docker compose up -d重新创建容器。我的习惯是每次改配置后都直接 down 再 up，从源头上避免"重启了个寂寞"。4.5 日志里刷满红色，真的全是致命错误吗新手看到日志里一堆红色或者 Level: ERROR 的条目，容易心里发慌。我的经验是不要被颜色吓住，要去看具体文本。很多日志只是警告，比如deprecated、fallback to default config，这些不影响运行。真正需要在意的是：一，有没有出现 "fatal"、"panic"、"crash" 字样；二，服务监听端口有没有打印；三，发一条测试消息后有没有新的报错。如果服务监听成功，测试消息也有响应，那日志里的红色大多属于"看得吓人但没事"的噪音。5. 进阶玩法：本地知识库、定时任务、自定义工具三个实战场景部署跑通只是开始。下面这三个场景是我用 OpenClaw 实际做过且觉得价值很高的玩法，你可以根据自己的需求改。5.1 场景一：把 OpenClaw 变成你的本地知识库问答助手OpenClaw 支持把本地文件目录作为上下文提供给模型。我把自己的几百篇技术笔记统一放到 data/knowledge 目录下，然后告诉它："请在 data/knowledge 目录中查找与'数据迁移'有关的内容，按照主题整理成一份简要报告，并标注出处的文件名。"实际效果是，它能够读取文件内容并给出一个带出处的汇总。当然，开源小模型在长文本理解上有个上限，单次能处理的文件数量和大小都有限。我的应对办法是把大文件拆成小块，一次让它读十几篇，分批整理，最后让它合并成一篇总报告。这个过程并不复杂，但能把"我的资料库"变成"可对话的助手"，这个体验很值。5.2 场景二：定时任务，每天早上自动生成一份简报OpenClaw 支持配置定时任务，配合系统调度器使用。我在本机写了一个脚本，每天早上 8 点调用 OpenClaw 的接口，让它汇总我指定的 RSS 源和本地待办清单，生成一份日报推送到我常用的即时通讯软件里。配置大概分三步：第一，在 OpenClaw 中定义一个任务，描述清楚"每天要做什么事、输入源在哪、输出格式是什么"；第二，确认 OpenClaw 的接口地址和鉴权方式；第三，在系统计划任务里添加一条定时触发命令。用 macOS 的话是 launchd 或 crontab，Windows 是任务计划程序。这套组合的妙处在于，OpenClaw 本身不用一直开着界面，只要服务进程在，定时任务就能自动跑。5.3 场景三：写个小脚本，让它帮你干更多的活OpenClaw 允许通过配置文件注册自定义工具。我写了一个 Python 脚本，作用是从指定网页提取正文并转成 Markdown，注册之后，OpenClaw 就获得了"抓网页"的能力。这个扩展思路特别适合程序员使用，也适合愿意去查资料把脚本"抄"明白的新手。注册方式不复杂：在 config 目录下的 tools 配置里增加一条条目，声明工具名称、调用命令、参数列表即可。注册完重启服务，然后在对话里直接说"用网页抓取工具把某某网址的正文保存下来"，它就会自动调用脚本。注意自定义工具的调用需要模型有工具调用的能力，如果模型太弱也可能不触发，所以对工具类项目，选模型时优先看它支不支持 function calling。最后再分享一个使用习惯上的建议：把它当作一个需要被清晰指挥的实习生，而不是一个全知全能的老师。刚开始使用时，任务描述越具体，它表现越好。如果你给它一句"整理一下我的文件"，它可能不知道该做哪一步；但你告诉它"把 downloads 目录下所有 PDF 的文件名提取出来，按修改时间排序，输出为 CSV 文件到 data/result.csv"，它基本一次就能做对。这就像养一只龙虾，你把喂食的位置和钳子往哪伸都安排明白，它才会按你的节奏干活。现在我把这套流程跑顺了，朋友问起"龙虾自由"是什么意思，我都会直接指指终端：就是自己动手，丰衣足食，再也不求着订阅服务过日子了。
先讲一个特别有画面感的场景：上周我在某个技术讨论区闲逛，有人发了一条动态，晒了一张终端截图——一个叫 OpenClaw 的项目跑起来了，正在自动整理他电脑里的文档。底下评论区有人问："这跟网页版 AI 有啥区别？"博主回了一句："网页版是替我聊天，这个是替我干活儿，而且是自己养的那种。"紧接着就有个热评："小龙虾自由了。"我当时就被"龙虾自由"这个词逗笑了。后来仔细琢磨了一下，这个梗还挺贴切：Claw 就是钳子，龙虾最显眼的就是那对钳子；而"龙虾自由"说的就是——不花订阅费、不依赖闭源服务，自己也养一只开源 AI 助手，想怎么折腾就怎么折腾。今天我把完整流程整理出来，从零开始到跑通，全程不需要你懂算法、不需要你写代码、也不需要你花钱买什么高级设备。只要你会复制粘贴命令，照着我这篇来，就能把 OpenClaw 免费部署起来。先说清楚一件事：标题说"10秒部署"，实际指的是核心启动命令只要几秒钟；从零准备环境到完全跑通，小白第一次操作大约需要二十到三十分钟。但一旦环境就绪，第二台机器上再部署就真的是十秒级别了。下面我按实际踩坑顺序来写，尽量让你的半小时不白费。1. 先说清楚 OpenClaw 是什么，以及"龙虾自由"到底在说什么如果你之前只接触过网页版对话 AI，可能会以为所有 AI 工具都长一个样：打开页面、输入问题、等回复。OpenClaw 不太一样，它更像是一个住在你电脑里的智能体。简单说，它不仅会"聊天"，还能以聊天的方式指挥它去操作：读取本地文件、执行命令行脚本、调用其他工具、定时完成任务、把结果整理成报告。你可以把它理解成"一个带着钳子帮你干活的助手"——这就是 Claw 的含义。我自己第一次跑通后的感觉是：这东西的爽点不在于"答得有多好"，而在于"它真能动手做事"。举个例子，我电脑里堆了几百个从网上下载的 PDF 和网页截图，以前想整理成读书笔记，得自己一一点开、复制、粘贴。部署 OpenClaw 之后，我告诉它"把 downloads 文件夹里所有 PDF 的第一页内容提取出来，按主题归个类，生成一份 Markdown 索引"，它大概跑了五分钟，把这件事做完了，虽然分类不算特别精准，但第一版草稿已经能省掉我大半天的重复劳动。"龙虾自由"的另一层含义是自治权。网页版服务通常有配额限制，对话次数多了要排队或者收费；OpenClaw 本身是开源项目，运行在你自己的机器上，模型也可以选择本地开源模型，断网时照样能干活。数据也是存在本地的，对于经常处理私人笔记、合同文稿的人，这一点特别重要。你自己的文件、你的对话记录，不需要上传到别人的服务器里。那它适不适合你？我认为只要满足下面任何一条，都值得装一个试试：经常有重复性文件处理任务，比如批量重命名、批量格式转换、文档摘要。想要一个能"动手执行"的 AI 助手，而不只是陪聊工具。对数据隐私敏感，希望 AI 操作本地文件而不经过第三方服务器。纯粹想折腾，喜欢研究开源工具，享受自己把系统跑起来的成就感。当然它也不是万能的。第一，它对命令行的依赖比网页版高，前期配置多少要碰一点终端，不过照抄命令就行。第二，本地小模型的理解能力确实不如大厂旗舰模型，遇到特别复杂的逻辑，需要你把任务拆得更细。第三，它更像一个工具集而不是保姆，你得告诉它步骤，它才能干活。后面我会专门讲怎么更好地"吩咐"它。2. 环境准备与方案选型：把"10秒"可能踩的坑都提前排掉很多人部署失败，不是项目本身难，而是环境没准备好就急着跑命令。OpenClaw 官方提供了两种主流部署方式：Docker 容器部署和 Node.js 源码部署。我建议你先花两分钟做个选择题，别上来就复制别人的命令，因为两种方式的依赖完全不同。先看看硬件要求。OpenClaw 本体是一个 Node.js 服务，内存占用其实不高，运行起来大约占用 200～400MB 内存。真正的资源大头是模型推理——如果你用纯本地模型，建议 16GB 内存起步，8GB 也能跑但会很吃力；如果你决定用云端模型 API，电脑只需要能流畅打开浏览器即可，4GB 内存都够用。磁盘方面预留 20GB 左右比较安心，因为本地模型文件动不动就是 4～7GB 一个。操作系统方面，Windows、macOS、Linux 都支持，区别只在于 Docker 的安装方式。2.1 环境自检清单：动手前先花五分钟验货不管选择哪种方案，你都先打开终端（Windows 用 PowerShell，macOS 用 Terminal），逐条跑一下下面的命令看是否已装好。# 查看系统基本信息 systeminfo | findstr /C:"OS Name" /C:"System Type" # 查看内存 wmic OS get TotalVisibleMemorySize # 查看磁盘剩余空间 df -hmacOS 和 Linux 上把第一条命令换成uname -a就行。重点检查两件事：内存是否大于等于 8GB，磁盘剩余是否大于 20GB。都满足的话，接着检查有没有安装 Docker 或者 Node.js。# 检查 Docker docker --version # 检查 Node.js node -v npm -v如果你的终端提示"command not found"或者版本号显示为 Node.js 版本低于 18，后面安装依赖的时候一定会报错。这里我给小白一个经验：Node.js 优先装 LTS（长期支持）版本，不要追最新版；Docker 优先装 Docker Desktop，安装完一定要启动一次，让它把底层虚拟机初始化好，否则后面拉镜像会莫名其妙失败。2.2 两种部署方案怎么选：Docker 还是源码跑我先把两个方案的核心差异做成一张表，你看完再选。对比项Docker 部署Node.js 源码部署环境隔离好，依赖不会污染系统一般，依赖装在系统里安装复杂度需要先装 Docker，再拉镜像需要先装 Node.js，再 npm install启动速度首次拉镜像慢，之后启动快首次装依赖慢，之后启动较快卸载干净程度容器删除即一切消失残留目录和进程需要手动清理改代码调试不友好，需重建镜像友好，改完重启即可适合人群不想折腾系统环境的小白想二次开发、改源码的进阶玩家我自己第一轮用的是 Docker，因为省心。你不需要关心 Node 版本、Python 环境、系统动态库这些乱七八糟的东西，一个容器全部搞定。第二轮为了改源码方便，我换成了源码部署，自此没再换回去。如果你现在不确定以后要不要二次开发，我建议第一轮先用 Docker 跑通，找找感觉，以后再迁移也不难，配置和数据都放在宿主机目录下，复制过去就能继续用。2.3 目录规划：给你的"龙虾"安排一个固定住所部署前我强烈建议规划一个干净的文件夹，比如用户主目录下新建 openclaw 目录，里面分三个子目录：app 放程序文件，data 放运行数据，config 放配置文件。这样做的最大好处是升级和卸载都很清晰，所有东西都圈在一个院子里，不会散落得到处都是。mkdir -p ~/openclaw/app mkdir -p ~/openclaw/data mkdir -p ~/openclaw/config在 Windows 上没有~这个写法，直接打开文件资源管理器，进入 C 盘或者 D 盘，新建 openclaw 文件夹，里面再建 app、data、config 三个子文件夹即可。这个小动作看似啰嗦，实际上是我踩过一次坑后长记性了——早期我随手在用户目录根目录下跑项目，后来配置、日志、缓存文件跟其他项目的混在一起，清理时根本分不清谁是谁。3. 核心实操：从拉取项目到跑通 AI 助手的完整过程环境准备好以后，真正的部署操作其实可以压缩到三步：拿代码、填配置、启动服务。下面我按照 Docker 方案为主线来演示，源码方案的区别点我会在对应位置单独标注。3.1 第一步：把项目代码拿到本地先进入你规划的 openclaw/app 目录，然后从代码托管平台克隆项目。以 Docker 版本为例，项目提供了 docker-compose.yml 文件，直接把它下载到本地即可。cd ~/openclaw/app git clone https://example.com/openclaw-project.git .如果你机器上没装 git，也可以直接去托管平台页面下载项目的 ZIP 压缩包，解压到当前目录。注意一个细节：解压后确认 docker-compose.yml 文件确实在 app 目录根下，而不是嵌套在下一级子目录里，不然后面docker compose up会提示找不到配置文件。3.2 第二步：编辑配置，告诉它用哪个模型进入 config 目录，新建一个 .env 文件（Windows 用户在资源管理器里新建文件然后重命名为 .env 即可，注意它没有名字前缀，只有后缀）。这个文件里保存的是运行时读取的参数。我贴一个最小可用的配置模板：# 服务端口，不改的话默认 8080 PORT=8080 # 数据存储目录 DATA_DIR=/app/data # 模型接口地址，本地模型留空则使用内置默认 MODEL_BASE_URL=http://127.0.0.1:11434/v1 # 模型接口密钥，本地模型可以填任意非空字符串 API_KEY=local-test-key # 使用的模型名称，需要和模型服务端已有的模型名一致 MODEL_NAME=your-model-name如果你完全不想付费，走本地模型路线，把 MODEL_BASE_URL 填成你本地模型服务的地址，API_KEY 随便填一个非空值，MODEL_NAME 填成你本地实际有的模型名。如果暂时不想折腾本地模型，又愿意花一点点钱用云端模型接口，就把 MODEL_BASE_URL 填成对应云服务商提供的接口地址，API_KEY 填你自己的密钥。我推荐新手第一轮先用本地模型，成本为零，环境闭环，彻底跑通了再考虑要不要上云端大模型。3.3 第三步：启动服务并观察日志配置写完，回到终端，确认当前在 app 目录，执行：docker compose up -d第一次执行会拉取镜像，时间取决于网络情况，一般是几分钟到十几分钟。看到 "Started" 或者 "Running" 字样就说明容器已经跑起来了。接着查看实时日志：docker compose logs -f日志里出现service is listening on port 8080之类的行，说明启动成功。源码方案在这个步骤的区别是先执行npm install装依赖，再执行npm run dev或node src/index.js启动，看到监听日志即为成功。3.4 验证部署：发第一条消息，别急着配花活服务启动后，打开浏览器访问 http://localhost:8080 ，能看到 OpenClaw 的对话界面。在那里面输入"你好，简单介绍一下你自己"，观察终端日志里是否出现了对应的请求处理记录。这一步的目的是确认从网页到服务再到模型的全链路是通的，而不是只看界面画出来就觉得成功了。我当时第一次部署完，看到界面高兴坏了，结果连发三条消息石沉大海，界面一直转圈，最后查日志才发现模型服务地址填错了。所以这里一定要做一次端到端验证。如果你走的是本地模型，这时候可能还要等模型文件加载，第一次加载可能持续几十秒，CPU 风扇会明显转起来，这是正常的。4. 启动失败、超时、配置不生效：我踩过的坑全记录跑通以后，我继续折腾了两三天，把几个高频问题都轮了一遍。每一个都是真实发生的，我直接把排查链路写出来，你遇到同款问题能少走弯路。4.1 端口被占用：启动报错后的正确排查姿势启动时如果看到Address already in use或者port is already allocated，说明 8080 端口已经被别的程序占用了。错误提示会直接告诉你哪个端口出问题，但不会告诉你谁占的。在终端执行：# macOS / Linux lsof -i :8080 # Windows netstat -ano | findstr :8080查到占用端口的进程 PID 后，如果确认不是你想保留的服务，就把它结束掉，或者直接改 OpenClaw 配置里的 PORT 为 8081，重新启动。这里有个教训：不要因为端口被占用就去重装 Docker 或者重装项目。端口问题只是配置层面的小摩擦，重装不会解决任何问题，只会浪费更多时间。用lsof或者netstat定位占用者才是正道。4.2 模型请求一直转圈或秒回错误：三步锁定问题源头我遇到的最难排查的问题是所有对话都回复"请求失败"。界面没给出任何具体信息，日志里只有一行failed to fetch model response。这时候不要看日志猜，直接从外到内逐层验证。第一，先用 curl 直接测试模型服务是否健康。curl http://127.0.0.1:11434/v1/models如果这条命令返回了一长串 JSON，说明模型服务没问题，问题出在 OpenClaw 配置或者网络链路。如果返回 connection refused，说明模型服务没启动，先启动模型服务再说。第二，确认模型名称。# 查看本地模型列表 ollama list你配置里的 MODEL_NAME 必须和模型列表里的名字一模一样，差一个冒号都会报错。云端接口同理，去服务商控制台确认你开通的模型名。第三，检查你的 API_KEY 是否正确。本地模型可以随便填，云端接口则必须真实有效，填错会返回 401 Unauthorized，日志里会有明确状态码。按这三步走，大多数"请求失败"都能在五分钟内定位。4.3 依赖安装 vendor 报错与 Node 版本不匹配源码部署时，npm install报各种红色警告甚至 error 的情况很常见。最常见的是The engine "node" is incompatible with this module. Expected version ">=18.0.0"。这行信息已经说得很明白了：你的 Node 版本太老。解决方案不是硬装，而是升级 Node。我当时的做法是装一个 Node 版本管理工具，用它切换到某个新版本，再重新安装依赖。版本切换完成后，记得先清理旧依赖再重装：npm cache clean --force rm -rf node_modules package-lock.json npm install如果是在 Windows 上，第三条命令里的rm -rf改成在资源管理器里手动删除 node_modules 文件夹。这个"清理三连"是解决依赖安装问题的一个通用手段，很多看似诡异的报错，清理干净后重来一次就好了。4.4 改了配置不生效：大部分人是忘了重启这个问题我犯过不止一次：改了 .env 里的配置，然后刷新网页，发现还是旧配置在生效，于是怀疑配置没写对，反复改来改去。原因其实特别简单——进程还是旧进程，配置文件只在启动时读取一次，不会热加载。正确做法是修改配置后重启服务。Docker 方式：docker compose restart源码方式：在终端按 Ctrl+C 停掉进程，重新执行启动命令。有个更容易被忽略的细节：Docker 的 Compose 文件里如果改了环境变量映射，或者改了端口映射，光 restart 不生效，要执行docker compose down && docker compose up -d重新创建容器。我的习惯是每次改配置后都直接 down 再 up，从源头上避免"重启了个寂寞"。4.5 日志里刷满红色，真的全是致命错误吗新手看到日志里一堆红色或者 Level: ERROR 的条目，容易心里发慌。我的经验是不要被颜色吓住，要去看具体文本。很多日志只是警告，比如deprecated、fallback to default config，这些不影响运行。真正需要在意的是：一，有没有出现 "fatal"、"panic"、"crash" 字样；二，服务监听端口有没有打印；三，发一条测试消息后有没有新的报错。如果服务监听成功，测试消息也有响应，那日志里的红色大多属于"看得吓人但没事"的噪音。5. 进阶玩法：本地知识库、定时任务、自定义工具三个实战场景部署跑通只是开始。下面这三个场景是我用 OpenClaw 实际做过且觉得价值很高的玩法，你可以根据自己的需求改。5.1 场景一：把 OpenClaw 变成你的本地知识库问答助手OpenClaw 支持把本地文件目录作为上下文提供给模型。我把自己的几百篇技术笔记统一放到 data/knowledge 目录下，然后告诉它："请在 data/knowledge 目录中查找与'数据迁移'有关的内容，按照主题整理成一份简要报告，并标注出处的文件名。"实际效果是，它能够读取文件内容并给出一个带出处的汇总。当然，开源小模型在长文本理解上有个上限，单次能处理的文件数量和大小都有限。我的应对办法是把大文件拆成小块，一次让它读十几篇，分批整理，最后让它合并成一篇总报告。这个过程并不复杂，但能把"我的资料库"变成"可对话的助手"，这个体验很值。5.2 场景二：定时任务，每天早上自动生成一份简报OpenClaw 支持配置定时任务，配合系统调度器使用。我在本机写了一个脚本，每天早上 8 点调用 OpenClaw 的接口，让它汇总我指定的 RSS 源和本地待办清单，生成一份日报推送到我常用的即时通讯软件里。配置大概分三步：第一，在 OpenClaw 中定义一个任务，描述清楚"每天要做什么事、输入源在哪、输出格式是什么"；第二，确认 OpenClaw 的接口地址和鉴权方式；第三，在系统计划任务里添加一条定时触发命令。用 macOS 的话是 launchd 或 crontab，Windows 是任务计划程序。这套组合的妙处在于，OpenClaw 本身不用一直开着界面，只要服务进程在，定时任务就能自动跑。5.3 场景三：写个小脚本，让它帮你干更多的活OpenClaw 允许通过配置文件注册自定义工具。我写了一个 Python 脚本，作用是从指定网页提取正文并转成 Markdown，注册之后，OpenClaw 就获得了"抓网页"的能力。这个扩展思路特别适合程序员使用，也适合愿意去查资料把脚本"抄"明白的新手。注册方式不复杂：在 config 目录下的 tools 配置里增加一条条目，声明工具名称、调用命令、参数列表即可。注册完重启服务，然后在对话里直接说"用网页抓取工具把某某网址的正文保存下来"，它就会自动调用脚本。注意自定义工具的调用需要模型有工具调用的能力，如果模型太弱也可能不触发，所以对工具类项目，选模型时优先看它支不支持 function calling。最后再分享一个使用习惯上的建议：把它当作一个需要被清晰指挥的实习生，而不是一个全知全能的老师。刚开始使用时，任务描述越具体，它表现越好。如果你给它一句"整理一下我的文件"，它可能不知道该做哪一步；但你告诉它"把 downloads 目录下所有 PDF 的文件名提取出来，按修改时间排序，输出为 CSV 文件到 data/result.csv"，它基本一次就能做对。这就像养一只龙虾，你把喂食的位置和钳子往哪伸都安排明白，它才会按你的节奏干活。现在我把这套流程跑顺了，朋友问起"龙虾自由"是什么意思，我都会直接指指终端：就是自己动手，丰衣足食，再也不求着订阅服务过日子了。