1. 项目概述：OpenClaw是什么，以及为什么你需要它

如果你最近在AI圈子里混，大概率已经不止一次听到“OpenClaw”这个名字了。它不是什么新的编程语言，也不是某个大厂刚发布的闭源模型，而是一个开源的、旨在连接你本地AI模型与外部世界（比如微信、飞书、邮件、网页）的智能体（Agent）框架。简单来说，它就像一个“万能接线员”，让你部署在本地电脑或服务器上的大语言模型（比如通过Ollama运行的Llama、Qwen等）不再是一个只会回答问题的“书呆子”，而是能帮你自动回复消息、处理文档、甚至执行一些自动化任务的“智能助手”。

我第一次接触OpenClaw，是因为厌倦了在不同聊天工具和AI对话窗口之间反复横跳。我想，既然我本地跑着一个7B参数的模型，回答一些日常问题绰绰有余，为什么不能让它直接替我处理微信里那些重复性的咨询呢？OpenClaw正好解决了这个痛点。它通过一套称为“Skill”（技能）的插件机制，让AI模型具备了“动手能力”。一个配置好的OpenClaw实例，可以监听微信消息，理解用户意图，调用相应的Skill（比如查询天气、搜索资料、生成图片），然后将结果回复回去，整个过程完全自动化。

它的核心价值在于“开箱即用”和“高度可定制”。你不需要从零开始写一个机器人框架，OpenClaw已经提供了消息路由、会话管理、技能调度等基础能力。你只需要关心两件事：第一，提供一个AI模型（本地或云端API均可）；第二，配置你需要用到的Skill。这对于开发者、运维人员、甚至是技术爱好者来说，门槛大大降低。你可以用它来搭建一个24小时在线的智能客服，一个自动整理会议纪要的助手，或者一个帮你监控服务器状态的告警机器人。随着AI模型能力的平民化，像OpenClaw这样的“胶水”框架，其重要性会越来越凸显。

接下来，我将基于最新的实践，为你带来一份从零开始的OpenClaw安装与部署指南。这份指南会覆盖Docker部署和裸机安装两种主流方式，并详细讲解如何配置它连接到Ollama本地模型以及接入微信等常见通讯工具。过程中我会穿插我踩过的坑和总结的经验，目标是让你一次部署成功，快速体验到AI智能体的魅力。

2. 部署方式选型：Docker还是裸机安装？

在真正动手之前，我们先花点时间聊聊部署方式的选择。这决定了你后续的维护成本和遇到问题时的排查难度。OpenClaw官方推荐使用Docker Compose进行部署，这也是目前最主流、最省心的方式。但理解“裸机安装”的过程，有助于你更深入地理解OpenClaw的组件构成和工作原理。

2.1 Docker Compose部署：推荐大多数人的首选方案

Docker部署的核心优势是环境隔离和一键启动。OpenClaw依赖Python环境、一系列Python包、以及可能的后端服务（如数据库）。用Docker，你可以确保这些依赖在一个纯净、可控的容器内运行，不会污染你的主机系统。更新版本时，也只需要拉取新的镜像并重启容器，非常方便。

对于绝大多数想要快速上手体验的用户，我强烈建议使用Docker方式。你只需要确保你的机器上已经安装了Docker和Docker Compose。你可以通过运行docker --version和docker-compose --version（或docker compose version）来检查。如果没有安装，请先根据你的操作系统（Ubuntu/Debian, CentOS, macOS, Windows）去官方文档安装，这个过程网上教程很多，这里不再赘述。

使用Docker部署，你基本上只需要和一个docker-compose.yml配置文件打交道。这个文件定义了OpenClaw服务、其依赖的网络、卷挂载等。后续的配置，比如修改模型连接地址、添加Skill，大多通过修改环境变量或挂载配置文件来实现，无需进入容器内部进行复杂的操作。

2.2 裸机（源码）安装：适合深度定制和开发者

如果你计划深度定制OpenClaw，比如修改其核心代码、开发自己的Skill，或者你的生产环境由于安全策略无法使用Docker，那么就需要进行裸机安装。

裸机安装意味着你要在宿主机上直接准备Python环境、安装所有依赖包、并手动处理服务的启动和守护进程。这个过程相对繁琐，但能让你对项目的结构有更清晰的认识。你需要：

1. 克隆OpenClaw的GitHub仓库。
2. 创建一个Python虚拟环境（强烈建议，避免包冲突）。
3. 使用pip安装requirements.txt中的依赖。
4. 手动配置数据库（如果需要）。
5. 通过命令行启动各个服务组件。

裸机安装的挑战主要在于依赖冲突和环境配置。不同的Linux发行版、不同的Python版本，都可能导致某些包安装失败。你需要有一定的Linux和Python排错能力。但它的好处是，调试时你可以直接使用pdb等工具，代码修改也能即时生效，非常适合开发阶段。

注意：无论选择哪种方式，请确保你的机器有足够的资源。运行一个轻量级模型（如Qwen2.5-7B）可能需要4-8GB的可用内存。如果同时运行多个服务或更大模型，需求会相应增加。

为了兼顾大多数读者的需求，本教程将以Docker Compose部署作为主线进行详细讲解，并在关键环节指出裸机安装的差异点和注意事项。这样，你可以用最快捷的方式搭起来，同时也能理解背后的原理。

3. 实战：通过Docker Compose一键部署OpenClaw

好了，理论部分结束，我们开始动手。假设你已经在Ubuntu 22.04 LTS系统上准备好了Docker和Docker Compose。其他Linux发行版或macOS步骤类似，Windows用户建议使用WSL2以获得最佳体验。

3.1 第一步：获取部署配置文件

OpenClaw的官方仓库通常会提供一个示例的docker-compose.yml文件。我们的第一步就是获取它并放到一个独立的工作目录。

# 创建一个专门用于OpenClaw的目录 mkdir -p ~/openclaw && cd ~/openclaw # 从官方仓库拉取最新的docker-compose示例文件 # 请注意，仓库地址可能更新，请以OpenClaw官方GitHub仓库为准。 # 这里假设我们从一个稳定的示例源获取。 curl -o docker-compose.yml https://raw.githubusercontent.com/openclaw/OpenClaw/main/docker-compose.example.yml

如果curl无法获取，你也可以直接访问OpenClaw的GitHub仓库，找到docker-compose.yml或docker-compose.example.yml文件，将其内容复制到你本地新建的docker-compose.yml文件中。

3.2 第二步：解读与修改docker-compose.yml

拿到配置文件后，先别急着启动，花几分钟理解一下它定义了哪些服务。一个典型的OpenClaw Docker Compose配置可能包含以下服务：

1. openclaw-core: 核心服务，处理消息流、技能调度、与AI模型交互。
2. openclaw-webui(可选): 基于Web的用户界面，用于监控和管理。
3. postgres(可选): PostgreSQL数据库，用于存储会话历史、技能配置等持久化数据。
4. redis(可选): Redis缓存，用于提升会话状态管理等性能。

你需要重点关注openclaw-core服务的环境变量部分。这里是与你的AI模型连接相关的关键配置。用文本编辑器（如nano或vim）打开docker-compose.yml：

nano docker-compose.yml

找到openclaw-core服务的environment部分。你最可能需要修改的是OLLAMA_BASE_URL和DEFAULT_MODEL。

environment: - OLLAMA_BASE_URL=http://host.docker.internal:11434 - DEFAULT_MODEL=llama3.2:1b - DATABASE_URL=postgresql://postgres:password@postgres:5432/openclaw - REDIS_URL=redis://redis:6379/0

• OLLAMA_BASE_URL: 这是OpenClaw连接Ollama服务的地址。如果你在宿主机（而不是Docker容器内）运行Ollama，那么host.docker.internal是一个特殊的DNS名称，指向宿主机的网络。确保你的Ollama服务在宿主机11434端口正常运行。如果你的部署结构不同（例如Ollama也在另一个容器中），则需要修改为对应的容器服务名和端口。
• DEFAULT_MODEL: 指定默认使用哪个模型。这个模型名必须与你在Ollama中拉取（pull）和运行的模型名称完全一致。例如，如果你运行的是ollama run qwen2.5:7b，那么这里就应该是qwen2.5:7b。

重要提示：host.docker.internal在Linux原生Docker环境下可能无法直接使用。对于Linux，一个更可靠的方式是使用宿主机的真实IP地址（如172.17.0.1，这是Docker默认网桥的网关），或者将网络模式改为host。但改为host模式会失去部分网络隔离性。我个人的做法是，在Linux下，先使用ip addr show docker0查看Docker网桥IP，然后替换掉host.docker.internal。例如，如果docker0的IP是172.17.0.1，则配置为- OLLAMA_BASE_URL=http://172.17.0.1:11434。

3.3 第三步：启动OpenClaw服务

配置修改保存后，就可以启动服务了。在docker-compose.yml所在目录执行：

docker-compose up -d

-d参数代表“后台运行”。命令执行后，Docker会开始拉取所需的镜像（如果本地没有），然后创建并启动所有定义的服务容器。

你可以使用以下命令查看容器状态和日志：

# 查看所有容器状态 docker-compose ps # 查看openclaw-core容器的实时日志，用于排查启动问题 docker-compose logs -f openclaw-core

如果一切顺利，你应该在日志中看到OpenClaw核心服务启动成功的信息，可能包括数据库连接成功、加载了哪些Skill等。如果看到错误，最常见的通常是网络连接问题（连不上Ollama或数据库）或者模型名称错误。

3.4 第四步：验证基础功能

服务启动后，如何验证它是否正常工作呢？OpenClaw通常会提供一些验证方式：

1. 检查Web UI（如果已部署）：如果配置中包含了openclaw-webui服务，你可以通过浏览器访问http://你的服务器IP:指定的端口（端口号在docker-compose中定义），查看管理界面。
2. 通过API测试：OpenClaw核心服务会暴露HTTP API。你可以使用curl命令发送一个简单的测试请求。首先，需要知道API的端口映射。查看docker-compose.yml中openclaw-core服务的ports部分，例如- "3000:3000"，那么宿主机3000端口就映射到了容器的3000端口。

# 假设API端口是3000，发送一个简单的对话请求 curl -X POST http://localhost:3000/api/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "你配置的DEFAULT_MODEL", "messages": [{"role": "user", "content": "你好，请介绍一下你自己。"}] }'

如果返回了AI模型的回复，恭喜你，OpenClaw的核心服务已经成功连接到了你的本地模型，基础部署完成！

4. 核心配置详解：连接模型与添加技能（Skill）

基础服务跑起来只是第一步，让OpenClaw变得有用，关键在于配置——告诉它用什么模型，以及赋予它什么能力。

4.1 配置AI模型后端

OpenClaw并不局限于Ollama，它支持多种AI模型后端，通过环境变量进行配置。除了前面提到的OLLAMA_BASE_URL，你可能还需要关注：

• OPENAI_API_BASE与OPENAI_API_KEY：如果你想使用OpenAI的API（如GPT-4）或兼容OpenAI API格式的本地模型服务（如FastChat、LocalAI），就需要设置这两个变量。将OPENAI_API_BASE设置为你的API端点，OPENAI_API_KEY设置为你的密钥。同时，将DEFAULT_MODEL设置为该后端支持的模型名。
• 多模型支持：你可以在配置中定义多个模型后端。一些高级配置可能允许你通过某种方式（如Web UI或API参数）动态选择本次对话使用的模型。

在Docker部署中，修改模型配置最方便的方式就是更新docker-compose.yml中的环境变量，然后重启服务：

docker-compose down docker-compose up -d

4.2 理解与安装Skill

Skill是OpenClaw的灵魂。一个Skill就是一个独立的功能模块，例如：

• weather_skill: 查询天气。
• web_search_skill: 进行网络搜索。
• calculator_skill: 执行数学计算。
• filesystem_skill: 读写本地文件（需谨慎配置权限！）。

OpenClaw在启动时会自动加载其skills目录下的所有合法Skill。在Docker部署中，通常有两种方式添加Skill：

1. 使用预构建的Skill镜像：有些Skill可能被做成了独立的Docker服务，你只需要在docker-compose.yml中添加这个服务，并确保它与openclaw-core在同一个网络中，核心服务就能自动发现它。
2. 挂载本地Skill目录：这是更灵活的方式。你可以在宿主机上开发或存放Skill代码，然后通过Docker的卷（volumes）挂载到容器的指定目录（如/app/skills）。

例如，在docker-compose.yml中为openclaw-core服务添加一个卷挂载：

services: openclaw-core: # ... 其他配置 ... volumes: - ./my_custom_skills:/app/skills/custom # 将宿主机的./my_custom_skills目录挂载到容器内

然后，在./my_custom_skills目录下，按照OpenClaw的Skill规范（通常是一个包含__init__.py和skill.py的Python包）放置你的Skill。重启服务后，OpenClaw就会加载这个自定义Skill。

实操心得：刚开始不建议自己写Skill。先去官方仓库或社区寻找现成的、常用的Skill。先让系统跑起来，理解Skill是如何被调用和工作的。之后，再尝试修改或创建简单的Skill，例如一个返回固定文本的Skill，来验证整个流程。

4.3 配置技能参数与权限

许多Skill需要额外的配置才能工作。比如web_search_skill可能需要配置Serper或Google Search API的密钥；filesystem_skill必须严格限制其可访问的目录路径，以防安全风险。

这些配置通常通过环境变量或单独的配置文件（如config.yaml）来管理。在Docker中，可以通过环境变量传入。你需要查阅具体Skill的文档，了解它需要哪些配置项，然后将它们添加到docker-compose.yml中openclaw-core的environment部分。

例如，为某个Skill配置API密钥：

environment: - OLLAMA_BASE_URL=http://host.docker.internal:11434 - DEFAULT_MODEL=llama3.2:1b - MY_WEB_SEARCH_API_KEY=your_super_secret_key_here

安全是重中之重。对于涉及外部API、文件系统、网络访问的Skill，一定要遵循最小权限原则，只授予其完成功能所必需的最低权限。

5. 连接现实世界：接入微信与飞书等平台

OpenClaw本身是一个“大脑”，它需要“感官”和“手脚”来与外界交互。接入微信、飞书、Slack、Discord等通讯平台，就是为它安装“感官”。这些功能通常通过特定的“Adapter”（适配器）或“Gateway”（网关）来实现。

5.1 接入微信：使用现成适配器

微信个人号的自动化接入是一个复杂且动态对抗的过程，因为微信官方不鼓励自动化。社区中常见的方案是基于逆向工程实现的协议库，如wechaty、itchat等。OpenClaw生态中可能有集成了这些库的微信适配器。

部署流程通常如下：

1. 寻找适配器：在OpenClaw社区或GitHub上搜索 “openclaw wechat adapter” 或类似关键词。找到对应的Docker镜像或源码。
2. 作为独立服务添加：在现有的docker-compose.yml中，添加一个新的服务，比如叫openclaw-wechat-adapter。
3. 配置桥梁：这个适配器服务需要能够与openclaw-core通信。通常它们会通过HTTP API或消息队列（如Redis）进行交互。你需要配置适配器，将收到的微信消息转发到OpenClaw核心的API，并将核心的回复消息取回、发送给微信用户。
4. 登录微信：启动适配器服务后，查看其日志。通常首次运行会要求你扫码登录微信。登录成功后，适配器会维护这个会话。

重要警告：使用微信个人号进行自动化存在账号被封的风险。请谨慎使用，不要用于营销、刷屏等行为，并遵守平台规则。建议使用小号进行测试。

5.2 接入飞书：更友好的企业级方案

相比微信，飞书等企业协作平台通常提供了官方、开放的机器人API，接入起来更稳定、更合规。OpenClaw接入飞书的流程更为标准：

1. 创建飞书机器人：在飞书开放平台创建一个企业自建应用，并添加“机器人”能力。获取到app_id和app_secret。
2. 配置事件订阅与权限：在飞书应用后台，配置事件订阅的请求网址（URL），这个URL将是你的OpenClaw飞书适配器对外的公网访问地址。同时，为机器人申请必要的权限，如“获取用户发给机器人的单聊消息”、“获取用户在群聊中@机器人的消息”等。
3. 部署飞书适配器：与微信类似，你需要一个飞书适配器服务。将其添加到docker-compose.yml，并配置从飞书开放平台获取的app_id、app_secret、encryption_key等，同时配置其与openclaw-core通信的地址。
4. 配置网络：最关键的一步是让飞书服务器能够访问到你的适配器。这意味着你部署OpenClaw的服务器需要有公网IP，或者使用内网穿透工具（如ngrok、frp）将本地端口暴露到公网。将穿透后得到的公网URL配置到飞书事件订阅的请求网址中。
5. 验证与发布：保存配置后，飞书平台会向你配置的URL发送一个验证请求，适配器需要正确处理并返回特定的挑战码（challenge）以完成验证。验证通过后，发布应用版本，即可在飞书中邀请机器人进行测试。

踩坑实录：飞书适配器部署中最常见的坑就是网络连通性和加密验证。务必确保你的公网URL是HTTPS（飞书要求），并且适配器正确配置了加密密钥以验证飞书请求的签名。日志是排查问题的关键，仔细查看适配器服务的日志，里面通常会明确提示验证失败或消息处理错误的原因。

5.3 通用接入逻辑与消息流

无论接入哪个平台，其核心逻辑都是一致的，理解这个流程有助于你调试任何适配器：

[外部平台] (如微信/飞书) -> [消息事件] -> [OpenClaw平台适配器] (接收、解码) -> [HTTP Post / Redis PubSub] -> [OpenClaw核心服务] (理解意图、调用Skill) -> [生成回复] -> [反向路径] -> [平台适配器] (编码、发送) -> [外部平台] -> [最终用户]

适配器的作用就是做“翻译官”，将不同平台的消息协议，转换成OpenClaw核心能理解的内部格式，反之亦然。

6. 故障排查与日常维护指南

即使按照教程一步步来，也难免会遇到问题。这里我总结了一些常见的错误和排查思路。

6.1 服务启动失败：容器无法运行

• 现象：docker-compose up -d后，docker-compose ps显示某个容器状态是Exited (1)。
• 排查：
  1. 查看日志：docker-compose logs <service_name>。这是最直接有效的方法。错误信息通常会明确指出问题，例如“无法连接到数据库”、“某个环境变量未设置”、“端口已被占用”。
  2. 检查端口冲突：确保docker-compose.yml中映射的宿主机端口（如3000、5432）没有被其他程序占用。使用netstat -tulpn | grep :端口号命令检查。
  3. 检查镜像拉取：网络问题可能导致镜像拉取失败。可以尝试手动拉取：docker pull 镜像名:标签。
  4. 检查卷挂载权限：如果你挂载了本地目录，确保容器内的进程（通常以非root用户运行）有权限读写该目录。

6.2 核心服务报错：llama.cpp server或模型连接错误

• 现象：日志中出现类似Failed to connect to Ollama server、Model not found或got exception: { "error": { "code": 400, ...的错误。
• 排查：
  1. 确认Ollama服务状态：在宿主机运行curl http://localhost:11434/api/tags，看是否能返回已拉取的模型列表。如果不能，说明Ollama没启动或没在11434端口监听。
  2. 确认网络连通性：从OpenClaw容器内部测试是否能访问到Ollama。首先进入容器：docker-compose exec openclaw-core sh，然后在容器内运行curl http://host.docker.internal:11434/api/tags。如果失败，说明容器网络配置有问题。对于Linux宿主机，尝试将host.docker.internal替换为宿主机的Docker网桥IP（如172.17.0.1）。
  3. 确认模型名称：确保DEFAULT_MODEL的环境变量值与Ollama中存在的模型名完全一致，包括大小写和标签（如qwen2.5:7b和qwen2.5:7b-instruct是不同的）。

6.3 技能（Skill）加载或执行失败

• 现象：日志显示某个Skill加载失败，或者用户请求触发Skill时返回错误。
• 排查：
  1. 检查Skill目录结构：确保自定义Skill的目录结构符合规范，并且已正确挂载到容器内。
  2. 检查Skill依赖：有些Skill可能需要额外的Python包。如果Skill加载时报导入错误，你可能需要修改OpenClaw核心的Dockerfile，在构建时安装这些依赖，或者将Skill及其依赖打包成自己的镜像。
  3. 检查Skill配置：确认Skill所需的环境变量或配置文件已正确设置。查看该Skill的文档或源码，了解其需要的配置项。
  4. 查看Skill自身日志：一些复杂的Skill可能会有自己的日志输出。查看OpenClaw核心日志中关于该Skill的部分，或者如果Skill以独立服务运行，查看其容器日志。

6.4 适配器无法接收或发送消息

• 现象：微信/飞书机器人无响应，适配器日志没有错误，或者有连接错误。
• 排查：
  1. 网络连通性（双向）：这是企业级应用接入最常见的问题。确保：
     • 你的服务器/穿透服务能被公网访问。用手机4G网络浏览器访问你的适配器URL试试。
     • 你的适配器服务能访问到OpenClaw核心服务。在适配器容器内，用curl测试核心服务的API端点。
  2. 配置验证：仔细核对平台（飞书/微信）后台和应用配置的每一个参数：AppID、Secret、Token、加密Key、请求URL。一个字符错误都会导致失败。
  3. 查看平台事件：飞书开放平台有“事件日志”功能，可以查看发送给机器人的事件是否成功，以及机器人的响应状态码。这是判断问题出在飞书侧还是你服务侧的关键。

6.5 日常维护与更新

• 更新OpenClaw：关注官方GitHub仓库的Release。更新时，拉取最新的docker-compose.yml和镜像，然后执行docker-compose pull拉取新镜像，再docker-compose up -d重启服务。注意新版配置可能变化，需要对比合并。
• 备份数据：如果你使用了Postgres数据库，定期备份数据库卷的数据至关重要。可以使用docker-compose exec postgres pg_dump -U username openclaw > backup.sql进行导出。
• 监控资源：使用docker stats或htop监控容器和系统的CPU、内存使用情况。AI模型推理是内存消耗大户，确保系统有足够的Swap空间或在内存不足时能优雅降级。

部署和运维一个像OpenClaw这样的AI智能体系统，是一个典型的“ DevOps + AI ”工程。它考验的不仅仅是对AI模型的理解，更是对网络、容器、服务编排、故障排查等综合能力的掌握。希望这份详细的指南能帮你绕过我踩过的那些坑，顺利开启你的本地AI智能体之旅。