OpenClaw本地AI智能体部署与实战：从Docker安装到技能开发全指南

1. 从“小龙虾”到生产力工具：OpenClaw初印象

最近在本地AI智能体这个圈子里，OpenClaw这个名字被提到的频率越来越高。它不像ChatGPT那样家喻户晓，但在开发者、技术爱好者和那些希望用AI自动化处理日常重复性工作的人群中，它正迅速成为一个热门选择。很多人亲切地称它为“小龙虾”，这大概源于其名字的直译，但它的“钳子”可一点都不小，能帮你夹住并处理各种繁琐任务。

简单来说，OpenClaw是一个开源的、可本地化部署的AI智能体框架。它的核心魅力在于，你可以把它理解为一个“AI调度中心”。你不再需要手动打开不同的AI模型或应用去完成不同任务，而是可以通过OpenClaw，用自然语言或预设指令，让它去协调调用背后的大语言模型（LLM）、工具（Tools）和技能（Skills），自动完成一系列操作。比如，让它读取你的邮件摘要、自动回复客服消息、整理会议纪要，甚至是根据你的描述生成一张图片。它的目标是成为你电脑上一个24小时待命的AI助手，而且是完全运行在你本地环境或私有服务器上的，数据安全和隐私性有很好的保障。

我最初接触OpenClaw，是因为受够了在不同AI工具间来回切换的麻烦。一个模型负责对话，另一个负责写代码，再找一个来处理文档，效率很低。OpenClaw的出现，让我看到了统一调度的可能性。它支持接入多种开源大模型，如通过Ollama部署的Llama、Qwen、DeepSeek等，也支持Skill（技能）的扩展，这让它的能力边界可以不断延伸。无论你是想自动化办公流程、搭建一个智能客服原型，还是单纯想折腾一个属于自己的AI管家，OpenClaw都提供了一个相当不错的起点。

这份指南，就是基于我近期的实操经验整理而成。我不会讲太多空洞的理论，而是聚焦于“怎么做”。从最基础的安装部署，到核心的命令操作，再到常见问题的排查和进阶配置，我会把我踩过的坑、验证有效的步骤都列出来。目标只有一个：让你拿到这份手册，就能在自己的机器上把这只“小龙虾”跑起来，并开始指挥它为你工作。

2. 环境准备与部署：选对路子，事半功倍

部署OpenClaw的第一步，不是急着敲命令，而是搞清楚你的战场在哪里。不同的操作系统和环境，部署路径有细微差别，选错了开局就会很痛苦。主流的部署方式有两种：裸机直接安装和Docker容器化部署。我个人强烈推荐后者，尤其是对于新手或者希望在多台机器上保持环境一致的用户。

2.1 系统与环境检查

无论选择哪种方式，先确保你的系统满足基本要求。OpenClaw主要面向Linux和macOS，Windows用户可以通过WSL2获得接近Linux的体验，这是目前最稳妥的Windows方案。

• Linux (Ubuntu/Debian为例)：这是最原生的环境。确保你的系统是较新的版本（如Ubuntu 20.04 LTS或以上），并拥有sudo权限。需要预先安装git,curl,python3-pip等基础工具。
• macOS：需要确保已安装Homebrew包管理器，用于安装一些依赖。
• Windows：强烈建议配置WSL2（Windows Subsystem for Linux 2），并安装一个Ubuntu发行版。在纯Windows环境下部署会遇到更多依赖库问题，社区支持也相对较少。

接下来是关键依赖：Python和Docker。

• Python：OpenClaw通常需要Python 3.8或更高版本。通过python3 --version检查。
• Docker：如果你选择Docker部署，这是必需品。访问Docker官网下载并安装Docker Desktop（Mac/Windows）或Docker Engine（Linux）。安装后，在终端运行docker --version和docker run hello-world来验证安装成功且服务已启动。

2.2 部署方案详解：Docker vs 裸机安装

方案一：Docker部署（推荐首选）

Docker方案的最大优势是隔离性和一致性。它将OpenClaw及其所有依赖打包在一个容器里，你不需要关心系统里错综复杂的Python包版本冲突问题。这也是社区最活跃、问题最少的部署方式。

1. 获取镜像与运行容器： 通常，OpenClaw会提供官方或社区维护的Docker镜像。假设镜像名为openclaw/openclaw:latest。一个最基础的运行命令如下：

   docker run -d \ --name openclaw \ -p 7860:7860 \ -v /path/to/your/data:/app/data \ openclaw/openclaw:latest

   • -d：后台运行。
   • --name：给容器起个名字，方便管理。
   • -p 7860:7860：将容器内的7860端口映射到宿主机的7860端口。OpenClaw的Web界面通常在这个端口。
   • -v /path/to/your/data:/app/data：这是极其重要的一步。它将宿主机的某个目录挂载到容器的/app/data目录。OpenClaw的配置文件、对话记录、技能数据都会保存在这里。即使容器被删除，只要这个目录还在，你的数据就不会丢失。请将/path/to/your/data替换为你本地真实的目录路径，例如/home/yourname/openclaw_data。

2. 关键配置：连接大模型容器跑起来后，你需要告诉OpenClaw用什么AI大脑。最常见的是连接本地通过Ollama运行的模型。这需要在启动容器时，或者通过修改容器内的配置文件来设置环境变量。

   docker run -d \ --name openclaw \ -p 7860:7860 \ -v /path/to/your/data:/app/data \ -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \ -e DEFAULT_MODEL=llama3.2:1b \ openclaw/openclaw:latest

   • -e OLLAMA_BASE_URL=...：这个环境变量指向Ollama服务。如果你在宿主机（而不是容器内）运行Ollama，在Mac/Windows的Docker Desktop环境下，可以使用host.docker.internal这个特殊域名指向宿主机。Linux环境下可能需要使用宿主机的实际IP（如-e OLLAMA_BASE_URL=http://192.168.1.100:11434）。
   • -e DEFAULT_MODEL=...：设置默认使用的模型名称，需要与Ollama中拉取的模型名称一致。

注意：host.docker.internal在Linux原生Docker环境中可能不生效。此时，你需要创建自定义的Docker网络，或者使用--network=host模式（但这会牺牲一些隔离性）。更通用的做法是使用宿主机的局域网IP地址。

方案二：裸机（源码）安装

适合喜欢折腾、需要深度定制或开发Skill的用户。步骤相对繁琐。

1. 克隆代码库：

   git clone https://github.com/openclaw/openclaw.git cd openclaw

2. 创建Python虚拟环境（强烈建议）：

   python3 -m venv venv source venv/bin/activate # Linux/macOS # 对于Windows WSL，同样使用 source venv/bin/activate # 对于Windows CMD，使用 venv\Scripts\activate.bat

3. 安装依赖：

   pip install -r requirements.txt

   这一步最容易出问题，可能会因为系统缺失某些底层开发库（如python3-dev,build-essential）而失败。如果遇到编译错误，需要根据错误信息安装相应的系统包。

4. 配置与运行： 复制或修改配置文件（如config.example.yaml为config.yaml），在其中填入你的模型配置（如Ollama地址、API密钥等）。然后运行启动脚本：

   python app.py # 或者根据项目说明使用 uvicorn、gunicorn 等ASGI服务器启动

两种方案如何选？

• 求稳、快速上手、避免环境问题：无脑选Docker。
• 需要修改源码、调试、或系统资源极其紧张：考虑裸机安装。
• 对于Windows用户，通过WSL2 + Docker是最平滑的路径。

2.3 验证部署：第一次“唤醒”小龙虾

部署完成后，打开浏览器，访问http://localhost:7860（如果你映射的是其他端口，则替换7860）。如果看到OpenClaw的Web用户界面，恭喜你，部署成功了。

不过，这时候它可能还是个“哑巴”，因为还没给它连接上大脑（LLM）。你需要在Web界面的设置（Settings）里，或者通过修改配置文件，正确配置模型后端。最常用的就是指向你本地运行的Ollama服务地址（如http://localhost:11434）并选择模型。

配置成功后，在聊天框里输入一句“你好”，你应该能收到AI模型的回复。至此，你的OpenClaw就正式上线了。

3. 核心命令与日常操作手册

OpenClaw一旦运行起来，与它的交互主要可以通过两种方式：Web图形界面（GUI）和命令行接口（CLI）。Web界面适合日常对话和任务触发，而CLI则在管理、调试和自动化集成时更为强大。这里我们重点梳理那些你必须掌握的CLI命令和核心操作逻辑。

3.1 容器生命周期管理命令（Docker部署）

如果你用Docker部署，以下命令将成为你的日常：

• 启动容器：如果容器已存在但处于停止状态。

  docker start openclaw

• 停止容器：

  docker stop openclaw

• 重启容器（在修改配置或更新后常用）：

  docker restart openclaw

• 查看容器日志（排错神器）：

  docker logs openclaw # 实时跟踪日志 docker logs -f openclaw

• 进入容器内部shell（用于直接修改容器内文件或调试）：

  docker exec -it openclaw /bin/bash

  退出容器shell时，输入exit。

• 更新OpenClaw镜像和容器： 这是一个需要谨慎操作但必要的流程。

  1. 拉取最新镜像：docker pull openclaw/openclaw:latest
  2. 停止并删除旧容器：docker stop openclaw && docker rm openclaw
  3. 重要：确保你的数据卷（-v参数挂载的目录）路径不变，然后用新的镜像重新运行docker run命令。这样数据得以保留。

实操心得：养成用docker logs看日志的习惯。很多问题，比如模型连接失败、技能加载错误，日志里都有第一手信息。错误信息openclaw llamap svr operator(): got exception: { "error": { "code": 400, ...这类，通常就是模型API调用出了问题，首先检查OLLAMA_BASE_URL和DEFAULT_MODEL这两个环境变量或配置项是否正确。

3.2 OpenClaw核心CLI命令与技能管理

OpenClaw通常也提供项目自身的CLI工具，用于管理技能、任务等。这些命令需要在项目根目录（裸机安装）或进入容器后执行。

• 技能(Skill)管理：Skill是OpenClaw扩展能力的核心。

  • 列出已安装技能：

    openclaw skill list # 或在容器内：docker exec openclaw openclaw skill list

  • 安装新技能（通常从Git仓库）：

    openclaw skill install https://github.com/someuser/awesome-skill.git

  • 卸载技能：

    openclaw skill uninstall awesome-skill

• 任务与代理操作：你可以通过CLI直接触发一个预定义的任务或与代理交互。

  openclaw run --task “总结文档” --input “/path/to/doc.txt”

  这条命令会调用配置了“总结文档”能力的代理来执行任务。

3.3 配置文件详解：让小龙虾按你的规矩办事

OpenClaw的行为主要由配置文件控制（通常是config.yaml或.env文件）。理解关键配置项，是解锁其高级功能的基础。配置文件可能位于挂载的数据卷目录下（Docker部署）或项目根目录（裸机部署）。

几个最关键的配置区域：

1. 模型设置 (LLM Configuration)：

   llm: provider: "ollama" # 或 openai, anthropic 等 base_url: "http://host.docker.internal:11434" # Ollama服务地址 model: "qwen2.5:7b" # 默认模型名 api_key: "" # 如果使用云端API，则需要密钥

   • provider：指定模型提供商。本地部署首选ollama。
   • base_url：指向你的模型服务。这是错误高发区，务必确保地址可从OpenClaw所在环境访问。
   • model：模型名称，必须与Ollama中ollama list列出的名称完全一致。

2. 技能路径 (Skill Paths)：

   skills: directories: - "/app/data/skills" # 自定义技能安装目录 - "/app/skills" # 系统内置技能目录

   这决定了OpenClaw从哪里加载技能。你可以将自定义技能安装到挂载的卷目录，方便持久化和管理。

3. 记忆与持久化 (Memory & Persistence)： OpenClaw默认可能只保存在内存中的会话。要解决“第二天就不知道昨天会话内容”的问题，需要配置持久化存储。

   memory: type: "file" # 或 database file_path: "/app/data/memory/conversations.json" # 或者使用SQLite database: url: "sqlite:////app/data/openclaw.db"

   配置后，对话历史和上下文就能跨会话保留了。

配置修改后的生效：修改配置文件后，必须重启OpenClaw容器或进程才能使新配置生效。

4. 进阶集成与典型应用场景

让OpenClaw单独运行只是一个开始，它的威力在于与外部系统的集成，形成自动化工作流。这里介绍两个最实用的集成场景：接入飞书和自动化客服。

4.1 接入飞书/微信等办公平台

将OpenClaw作为机器人接入飞书或微信，可以让你的团队直接通过熟悉的聊天工具与AI交互。这里以飞书为例，核心步骤是创建一个“自定义机器人”。

1. 在飞书开放平台创建机器人：

   • 登录飞书开发者后台，创建企业自建应用，并启用“机器人”能力。
   • 获取两个关键凭证：app_id和app_secret，以及后续的verification_token。
   • 配置“事件订阅”，设置请求网址URL为你的OpenClaw服务器的公网可访问地址（如https://your-domain.com/feishu/webhook）。你需要有公网IP或使用内网穿透工具（如ngrok、frp）让本地服务能被飞书服务器访问到。
   • 配置“权限”，给机器人添加消息接收与发送等权限。

2. 在OpenClaw中配置飞书Skill/Adapter： OpenClaw社区通常有现成的飞书适配器或Skill。你需要安装它，并在配置文件中填写从飞书平台获取的凭证。

   feishu: app_id: "cli_xxxxxx" app_secret: "xxxxxxxx" verification_token: "xxxxxx" encrypt_key: "" # 如果启用了加密则填写 endpoint: "/feishu/webhook" # 与飞书后台配置的URL路径对应

3. 处理与转发消息： 该Skill会负责验证飞书的请求，并将接收到的消息转发给OpenClaw的核心处理引擎，由引擎调用LLM生成回复，再通过Skill发回飞书。你需要确保网络连通，并且OpenClaw服务能够处理并发的Webhook请求。

踩坑记录：接入第三方平台最大的坑就是网络和验证。1)公网访问：本地开发必须用内网穿透，否则飞书服务器无法回调你的接口。2)验证令牌：飞书首次发送的请求是验证，你的服务必须能正确响应verification_token，否则无法通过。很多开源适配器的文档会忽略这一点，务必仔细阅读代码逻辑。3)消息格式：飞书的消息体是特定的JSON格式，Skill需要正确解析content字段，并组装回符合飞书要求的响应格式。

4.2 构建自动化电商客服原型

用OpenClaw自动化处理80%的电商客服咨询，是一个极具价值的场景。这不仅仅是接上一个模型那么简单，需要一套设计。

1. 技能链设计：

   • 意图识别Skill：首先判断用户问题是“查订单”、“退换货”、“咨询商品”还是“投诉”。可以用一个专门的分类模型，或者通过Prompt工程让主LLM判断。
   • 知识库查询Skill：对于产品规格、物流政策等结构化问题，不应完全依赖LLM生成，而应该从商品数据库、FAQ文档中检索准确信息。可以集成向量数据库（如Chroma、Qdrant）实现语义检索。
   • 订单操作Skill：在验证用户身份（通过订单号、手机号后几位）后，调用内部API查询订单状态。注意：涉及真实数据操作，必须做好权限校验和沙箱隔离。
   • 话术管理Skill：针对常见问题，配置标准、亲切的回复话术模板，LLM负责填充变量（如用户姓名、订单号、预计时间），保证回复风格统一且专业。

2. 工作流编排： OpenClaw的Agent可以按顺序或条件触发这些Skill。例如：

   用户输入 -> 意图识别 -> 如果是“查订单” -> 提取订单号 -> 调用订单查询API -> 格式化结果 -> 发送回复。

   这个过程可以通过编写一个专用的“客服Agent”来编排。

3. 上下文与记忆： 客服对话常有上下文关联。必须启用持久化记忆，让OpenClaw记住当前会话中用户已经提供的信息（如订单号），避免用户重复陈述。

4. 人工接管机制： 必须设置“ escalation ”（升级）规则。当AI置信度低、用户情绪负面或问题超出预设范围时，自动转接给人工客服，并提供完整的对话历史。

实现这个场景，OpenClaw更像是一个“大脑”和“调度中心”，它协调不同的技能模块和外部API，共同完成复杂的客服任务。初期可以从处理最简单的FAQ开始，逐步增加技能链的复杂度。

5. 故障排查与性能调优指南

即使按照指南操作，也难免会遇到问题。本章节集中梳理一些常见错误和解决方案，并提供一些调优思路。

5.1 常见错误与解决方案

• 错误：openclaw llamap svr operator(): got exception: { "error": { "code": 400, "message": "...

  • 问题本质：这是大模型服务（如Ollama）返回的HTTP 400错误，表示客户端请求有问题。
  • 排查步骤：
    1. 检查模型服务状态：首先确保Ollama服务正在运行。curl http://localhost:11434/api/tags应该能返回模型列表。
    2. 检查配置连接：确认OpenClaw配置中的base_url完全正确。在Docker容器内，localhost指向容器自身，因此需用host.docker.internal或宿主机IP。
    3. 检查模型名称：确认DEFAULT_MODEL或配置中的model名称与Ollama中存在的模型完全一致，包括大小写和版本标签。
    4. 检查网络连通：从OpenClaw运行环境（如果是容器，就进入容器内部）执行curl <你的base_url>/api/tags，看是否能通。
    5. 查看Ollama日志：运行ollama serve的终端或查看Ollama服务日志，看是否有更详细的错误输出。

• 错误：Web界面能打开，但发送消息无反应或一直“思考”

  • 排查步骤：
    1. 查看后端日志：这是最重要的手段。通过docker logs -f openclaw或直接查看裸机运行的终端输出。
    2. 检查模型负载：可能是模型太大，硬件（尤其是GPU内存）不足，导致推理超时。尝试换一个更小的模型（如llama3.2:1b）。
    3. 检查技能加载：日志中可能会有某个Skill加载失败，导致整个处理链卡住。尝试暂时禁用非核心Skill。

• 问题：对话没有记忆，每次都是新会话

  • 解决方案：这是未配置持久化记忆导致的。参考第3.3节，配置memory为file或database类型，并确保存储路径有写权限。

• 问题：Docker容器启动后立即退出

  • 排查步骤：
    1. docker logs openclaw查看退出前的日志，通常会有启动错误信息。
    2. 常见原因：配置文件格式错误（YAML缩进问题）、环境变量缺失（如未设置必需的OLLAMA_BASE_URL）、挂载卷路径权限不足。

5.2 性能优化与资源管理

• 模型选择：在本地部署，模型大小直接决定响应速度和硬件需求。从较小的模型（如1B、3B参数）开始测试，平衡速度与智能。7B模型在16GB内存的机器上通常可以运行，但响应会慢一些。
• Ollama调优：运行Ollama时，可以指定GPU层数或CPU线程数来优化性能。

  OLLAMA_NUM_GPU=100 ollama run llama3.1:8b # 指定100% GPU负载 OLLAMA_NUM_PARALLEL=4 ollama run qwen2.5:7b # 指定并行线程数

• OpenClaw并发设置：如果通过Web界面有多人同时使用，需要调整OpenClaw后端服务器的Worker数量（如果使用Uvicorn/Gunicorn）。这通常在启动命令或配置文件中设置。
• 使用更轻量的技能：只安装和启用你真正需要的Skill。每个Skill都会增加加载时间和内存开销。

5.3 数据备份与迁移

你的核心资产是配置和记忆数据。对于Docker部署，这些都在你通过-v参数挂载的宿主机目录里（例如/home/yourname/openclaw_data）。定期备份这个目录即可。

迁移到新机器时，只需要：

1. 在新机器上安装好Docker和Ollama。
2. 将备份的整个数据目录拷贝到新机器。
3. 使用相同的docker run命令（确保镜像版本兼容），并将-v参数指向新机器上的这个目录路径。
4. 启动容器，所有配置、技能、对话历史都会恢复。

6. 技能生态与自定义开发入门

OpenClaw的真正潜力在于其可扩展的Skill系统。官方和社区提供了许多现成Skill，但当你需要解决特定问题时，自己开发一个Skill是必经之路。

6.1 发现与安装社区技能

在尝试自己造轮子前，先去看看社区有什么。GitHub上搜索“openclaw skill”能找到不少项目。安装方式如前所述，通常是通过Git仓库URL。

安装社区Skill时要注意：

• 兼容性：查看Skill的README，确认其支持的OpenClaw版本。
• 依赖：有些Skill可能需要额外的Python包，安装后可能需要重启OpenClaw。
• 配置：大部分Skill都需要在OpenClaw的配置文件中进行相应配置，如API密钥、服务地址等。

6.2 自定义Skill开发基础框架

一个最简单的Skill结构如下：

my_custom_skill/ ├── __init__.py ├── skill.py # 技能核心逻辑 ├── config.yaml # (可选) 技能专属配置 └── README.md

skill.py的核心是定义一个类，继承自基础的Skill类，并实现几个关键方法：

from openclaw.skills.base import Skill class MyCustomSkill(Skill): name = "my_custom_skill" description = "这是一个演示技能，用于处理特定任务。" version = "0.1.0" def __init__(self, config=None): super().__init__(config) # 初始化你的技能，如加载模型、连接数据库等 self.prefix = self.config.get("prefix", "默认前缀: ") async def execute(self, input_text: str, **kwargs) -> str: """ 这是技能的执行入口。 input_text: 用户输入或上游传递的文本。 kwargs: 可能包含上下文、会话ID等其他信息。 返回处理后的结果字符串。 """ # 你的核心处理逻辑 result = f"{self.prefix}我收到了：{input_text}" # 可以在这里调用外部API、查询数据库等 return result def get_config_schema(self): """ 定义技能需要的配置项，用于在OpenClaw主配置中填写。 """ return { "prefix": {"type": "string", "default": "默认前缀: ", "description": "输出前缀"} }

开发流程：

1. 在OpenClaw的技能目录（如挂载卷的/app/data/skills）下创建你的技能文件夹。
2. 编写上述代码。
3. 在OpenClaw的主配置文件config.yaml中，添加你的技能配置：

   skills: my_custom_skill: enabled: true prefix: "【我的技能】: "

4. 重启OpenClaw服务。它会在启动时自动加载并注册这个技能。

6.3 让Skill被Agent调用：意图匹配与触发

技能写好了，如何让OpenClaw在合适的时候调用它？有两种主要方式：

1. 显式调用：在创建自定义Agent（工作流）时，在你的工作流代码中直接调用await self.use_skill("my_custom_skill", input_text)。
2. 意图自动路由：这是更智能的方式。你需要定义一个“意图识别”机制。可以：
   • 基于关键词：在Skill中定义一组关键词，OpenClaw核心会匹配用户输入中的关键词，然后路由到该技能。
   • 基于分类模型：训练或使用一个轻量级文本分类模型，来判断用户意图并分配给对应技能。
   • 利用LLM进行路由：在Agent的Prompt中设计规则，让LLM判断“是否需要调用某个Skill来处理”，如果需要，则生成一个结构化调用指令。

对于简单的技能，从关键词匹配开始就足够了。例如，你的MyCustomSkill可以声明：当用户输入包含“演示”这个词时，才触发本技能的执行。这通常在Skill类的某个方法或元数据中定义。

开发自定义技能是深入理解OpenClaw架构的最佳方式。从一个简单的回声技能开始，逐步增加复杂功能，如调用天气API、查询本地文件、控制智能家居等，你会逐渐感受到将想法变为自动化现实的乐趣。