1. 项目概述为什么要在本地部署 OpenClaw最近和几个做企业服务的朋友聊天大家普遍有个痛点市面上的通用AI助手比如ChatGPT、Claude虽然好用但一涉及到企业内部数据比如客户工单、产品文档、销售合同就完全使不上劲了。要么是数据安全不敢往上放要么是回答得牛头不对马嘴因为模型根本不了解你公司的业务上下文。这时候一个能“吃”进你自己知识库、在你自己服务器上跑、还能集成到日常办公软件里的AI智能体就成了刚需。OpenClaw 就是冲着这个需求来的。它不是一个单一的模型而是一个开源的、可本地化部署的AI智能体框架。你可以把它理解为一个“大脑”这个大脑可以连接你本地的各种“感官”也就是你的私有数据源和“手脚”比如飞书、钉钉这样的协作工具。它的核心价值在于你完全掌控数据和流程无需依赖任何外部云服务就能打造一个专属于你企业的、7x24小时在线的智能业务助手。我花了差不多一周时间从零在Linux服务器上把OpenClaw搭了起来并且成功接入了飞书。整个过程踩了不少坑也总结出了一套最顺滑的部署流程。这篇文章我就把我从环境准备、源码部署、模型配置到飞书机器人集成的完整过程以及那些官方文档里没写的“坑点”和调试技巧毫无保留地分享出来。无论你是企业的运维工程师、对AI应用感兴趣的开发者还是想为团队提效的技术负责人这篇手把手的指南都能让你少走弯路快速拥有一个属于自己的企业级AI智能体。2. 核心需求解析与方案选型在动手之前我们得先想清楚部署OpenClaw到底要满足哪些核心需求以及为什么选择当前的方案。2.1 企业级AI智能体的核心需求首先一个合格的企业级AI智能体绝不仅仅是一个聊天机器人。它需要具备以下几个关键能力私有化部署与数据安全这是企业的生命线。所有数据包括知识库文档、用户对话记录、模型本身都必须留在企业内网或可控的私有服务器上杜绝数据泄露风险。OpenClaw作为开源框架完美满足这一点。知识库问答RAG能力智能体需要能够读取和理解企业内部的非结构化数据如PDF、Word、Excel、PPT、TXT以及Confluence、Notion等网页内容。这依赖于RAG检索增强生成技术OpenClaw内置了相关的处理流水线。多模型支持与成本控制企业场景多样有的任务需要大模型的强大推理能力如GPT-4、Claude-3有的则只需小模型快速响应如ChatGLM3、Qwen。OpenClaw支持对接多种开源和闭源模型API允许我们根据场景灵活选用有效控制API调用成本。本地部署时我们主要聚焦于开源模型。无缝集成现有工作流AI能力必须嵌入员工日常使用的工具里才能产生最大价值。飞书、钉钉、企业微信是国内企业最常用的协作平台因此与它们的集成是重中之重。可扩展性与可维护性随着业务发展可能需要增加新的数据源、新的工具Tool或对接新的模型。框架本身需要有清晰的架构和良好的代码规范方便二次开发。2.2 为什么选择 OpenClaw 飞书的组合市面上类似的框架还有LangChain、LlamaIndex等为什么我最终选择了OpenClaw呢主要是基于以下几点考量开箱即用程度高相比需要大量组装工作的LangChainOpenClaw提供了更完整的、产品化的体验。它自带Web管理界面对知识库管理、对话界面、Agent工作流都有现成的模块部署后很快就能用起来更适合追求效率的团队。对中文和国内生态友好项目由国内团队主导文档、社区支持以中文为主并且对国内常用的模型如智谱AI、月之暗面、深度求索等和协作工具飞书、钉钉有原生、深度的集成支持省去了自己造轮子的麻烦。架构清晰易于定制虽然开箱即用但它的模块化设计做得不错。如果你需要自定义数据解析逻辑、添加新的工具或者修改Agent的推理逻辑都能找到清晰的入口不会陷入黑盒。活跃的社区与迭代一个开源项目能否长期用下去社区活跃度是关键。OpenClaw在GitHub上更新频繁Issues和Discussions里的问题响应也比较及时这给了我们长期使用的信心。而选择飞书作为集成入口是因为它集成了IM、日历、文档、审批、机器人等功能于一体用户粘性高。将AI智能体以“飞书机器人”的形式呈现员工无需切换应用在熟悉的聊天窗口就能获得智能辅助落地阻力最小。2.3 技术栈与部署环境规划我们的部署将基于以下技术栈操作系统Ubuntu 22.04 LTS。这是目前云服务器最主流、社区支持最完善的Linux发行版能避免很多依赖库的兼容性问题。容器化Docker Docker Compose。这是现代应用部署的黄金标准。使用容器可以完美解决环境依赖问题保证开发、测试、生产环境的一致性也让后续的升级和维护变得异常简单。OpenClaw官方也推荐这种方式。AI模型考虑到完全本地部署我们将使用开源模型。这里我选择ChatGLM3-6B作为核心语言模型。它由智谱AI开源中英文能力均衡对硬件要求相对友好至少需要16GB GPU显存或32GB内存进行量化部署并且在中文场景下表现优异。同时我们还需要一个嵌入模型Embedding Model来处理文本向量化这里选择同样轻量高效的BGE-M3模型。向量数据库用于存储和快速检索知识库文档转换后的向量。OpenClaw支持多种向量库如Milvus、PGVector等。为了简化部署我们选用与OpenClaw集成度最高、也足够轻量的ChromaDB它可以直接运行在内存或本地文件中。飞书开放平台用于创建和配置机器人获取必要的凭证App ID, App Secret, Verification Token等实现消息接收与发送。整个系统的架构可以简单理解为用户通过飞书向机器人发送消息 - 飞书服务器将消息转发给我们部署的OpenClaw服务 - OpenClaw调用本地ChatGLM3模型理解意图并从ChromaDB知识库中检索相关信息 - 模型结合检索结果生成回答 - 回答通过OpenClaw返回给飞书机器人 - 用户收到回复。3. 基础环境准备与依赖安装万事开头难一个干净、稳定的基础环境是后续所有步骤成功的基石。这一部分我会详细说明服务器选型、系统配置以及核心依赖的安装并附上每一步的验证命令。3.1 服务器规格选择与系统配置OpenClaw的运行资源消耗主要来自大语言模型。如果你希望获得较快的响应速度拥有GPU的服务器是首选。最低配置纯CPU推理速度较慢CPU: 8核以上内存: 32GB磁盘: 100GB SSD网络: 公网IP用于飞书回调推荐配置GPU加速CPU: 8核GPU: NVIDIA RTX 4090 (24GB) 或 A100 (40GB/80GB)。对于ChatGLM3-6B使用量化技术后RTX 4090可以流畅运行。内存: 32GB磁盘: 200GB SSD我本次演示使用的是阿里云的一台ecs.gn7i-c8g1.2xlarge实例配置为8核32GB内存搭载一张NVIDIA T4 GPU16GB显存完全够用。系统初始化步骤更新系统与安装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y vim curl wget git net-tools htop配置SSH免密登录与安全组重要确保你的本地机器可以通过SSH密钥连接到服务器并关闭密码登录以提升安全。同时在云服务商控制台开放服务器安全组中你需要用到的端口例如22(SSH), 80(HTTP), 443(HTTPS)以及OpenClaw应用端口默认为3000。3.2 Docker与NVIDIA容器工具包安装由于我们要在GPU上运行模型必须安装NVIDIA Container Toolkit让Docker容器能够调用宿主机的GPU。卸载旧版本Docker如有sudo apt remove docker docker-engine docker.io containerd runc安装Docker官方仓库和最新版本# 安装依赖包 sudo apt install -y ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 设置稳定版仓库 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker引擎 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin验证Docker安装sudo docker run hello-world如果看到“Hello from Docker!”的输出说明安装成功。安装NVIDIA Container Toolkit# 添加仓库和GPG密钥 distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \ sed s#deb https://#deb [signed-by/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g | \ sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list # 安装工具包 sudo apt update sudo apt install -y nvidia-container-toolkit # 配置Docker使用nvidia作为默认运行时 sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker验证GPU在Docker中可用sudo docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi这个命令会启动一个带有CUDA基础的容器并运行nvidia-smi。如果成功输出GPU信息表格恭喜你最关键的一步已经完成。实操心得在这一步最常见的坑是nvidia-smi在宿主机上运行正常但在容器内报错“Failed to initialize NVML: Driver/library version mismatch”。这通常是因为宿主机重启后内核版本更新导致NVIDIA驱动内核模块版本与用户态库版本不匹配。解决方法很简单重启宿主机。重启后驱动会自动重新编译内核模块使其匹配。3.3 获取OpenClaw项目源码我们直接从GitHub拉取最新的OpenClaw代码。建议创建一个专门的目录来管理所有相关文件。# 创建项目目录 mkdir -p /opt/openclaw cd /opt/openclaw # 克隆仓库 (请替换为官方仓库地址此处为示例) git clone https://github.com/open-claw/openclaw.git . # 切换到稳定版本分支避免使用可能不稳定的main分支 git checkout release/v1.0.0 # 请查看仓库的最新稳定版标签拉取代码后你会看到项目目录结构其中docker-compose.yml和.env.example是我们需要重点关注的文件。4. 配置文件详解与关键参数调优OpenClaw通过环境变量和配置文件来驱动整个应用。直接使用默认配置很可能无法运行我们必须根据自身环境进行定制。4.1 环境变量文件 (.env) 配置项目根目录下通常有一个.env.example文件我们需要复制它并修改为.env。cp .env.example .env vim .env下面我逐行解释关键配置项及其填写方法# ############################### # 应用基础配置 # ############################### NODE_ENVproduction # 设置为生产环境 PORT3000 # OpenClaw Web服务端口确保防火墙已开放此端口 API_KEYsk-your-secret-key-here # 用于调用OpenClaw API的密钥务必修改为复杂字符串 # ############################### # 数据库配置 (PostgreSQL) # ############################### # 使用Docker Compose时通常用服务名作为主机名 DB_HOSTpostgres # 对应docker-compose.yml中的PostgreSQL服务名 DB_PORT5432 DB_USERpostgres # 数据库用户名 DB_PASSWORDyour_strong_password_here # 数据库密码必须修改 DB_DATABASEopenclaw # 数据库名 DB_SSLfalse # 内网部署通常关闭SSL # ############################### # 向量数据库配置 (ChromaDB) # ############################### VECTOR_DB_TYPEchromadb # 指定使用ChromaDB CHROMADB_PERSIST_PATH/app/data/chromadb # 容器内向量数据持久化路径 # 注意此路径会在容器内我们需要通过卷(volume)映射到宿主机 # ############################### # 大语言模型 (LLM) 配置 # ############################### # 这里配置我们本地部署的ChatGLM3 LLM_TYPEopenai # OpenClaw使用OpenAI API兼容的接口许多本地模型服务也提供此兼容接口 OPENAI_API_KEYEMPTY # 因为用本地模型这里可以填空或任意值但键名需要保留 OPENAI_API_BASE_URLhttp://localhost:8000/v1 # 指向本地启动的ChatGLM3 API服务地址 OPENAI_API_MODEL_NAMEchatglm3-6b # 模型名称与API服务返回的一致即可 # ############################### # 嵌入模型 (Embedding) 配置 # ############################### # 配置本地部署的BGE-M3嵌入模型 EMBEDDING_TYPEopenai # 同样使用OpenAI兼容接口 EMBEDDING_OPENAI_API_KEYEMPTY EMBEDDING_OPENAI_API_BASE_URLhttp://localhost:6006/v1 # 指向本地BGE-M3 API服务 EMBEDDING_OPENAI_API_MODEL_NAMEBAAI/bge-m3 # 模型名称 # ############################### # 飞书机器人配置 (暂留空后续获取后填写) # ############################### FEISHU_APP_ID FEISHU_APP_SECRET FEISHU_VERIFICATION_TOKEN FEISHU_ENCRYPT_KEY # 如果飞书应用开启了“启用加密”则需要填写注意事项DB_PASSWORD、API_KEY务必替换为高强度密码。OPENAI_API_BASE_URL和EMBEDDING_OPENAI_API_BASE_URL是关键。它们指向我们后续将要启动的本地模型服务。localhost在Docker Compose网络内指向的是每个容器自己。因此如果模型服务与OpenClaw主应用不在同一个Docker容器内就不能用localhost。我们需要使用Docker Compose的服务名作为主机名。假设我们在docker-compose.yml里定义了一个叫llm-api的服务来提供ChatGLM3那么这里就应该填http://llm-api:8000/v1。这是部署中最容易出错的地方之一。先保留飞书配置为空我们完成基础部署后再去飞书开放平台申请。4.2 Docker Compose 文件调整默认的docker-compose.yml可能只包含了OpenClaw主应用和PostgreSQL。我们需要修改它把ChatGLM3和BGE-M3的模型服务也集成进来并配置正确的网络和卷映射。version: 3.8 services: # 1. PostgreSQL 数据库 postgres: image: postgres:15-alpine container_name: openclaw-postgres restart: unless-stopped environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: your_strong_password_here # 与.env中DB_PASSWORD一致 POSTGRES_DB: openclaw volumes: - postgres_data:/var/lib/postgresql/data networks: - openclaw-network # 2. OpenClaw 主应用 openclaw: image: openclaw/openclaw:latest # 使用官方镜像或自己构建 container_name: openclaw-app restart: unless-stopped ports: - 3000:3000 # 将宿主机的3000端口映射到容器的3000端口 depends_on: - postgres - chatglm3-api # 依赖模型服务 - bge-embedding-api environment: - NODE_ENVproduction # 其他环境变量通过.env文件传入 env_file: - .env volumes: # 映射上传文件目录 - ./storage/uploads:/app/storage/uploads # 映射日志目录 - ./logs:/app/logs # 映射向量数据库持久化目录 (确保与.env中CHROMADB_PERSIST_PATH的父目录对应) - ./data/chromadb:/app/data/chromadb networks: - openclaw-network # 3. ChatGLM3-6B API 服务 (使用开源项目 fastchat 或 vllm 部署) chatglm3-api: image: ghcr.io/huggingface/text-generation-inference:latest # 或使用其他镜像如chatglm3-6b-api:latest container_name: openclaw-chatglm3 restart: unless-stopped # 部署GPU资源非常重要 deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] # 另一种简单的GPU声明方式与deploy二选一 # runtime: nvidia # environment: # - NVIDIA_VISIBLE_DEVICESall ports: - 8000:8000 command: --model-id THUDM/chatglm3-6b --hostname 0.0.0.0 --port 8000 --max-input-length 4096 --max-total-tokens 8192 --quantize bitsandbytes # 启用量化以减少显存占用 volumes: # 映射模型缓存目录避免每次下载 - ./models:/data networks: - openclaw-network # 4. BGE-M3 Embedding API 服务 bge-embedding-api: image: sentence-transformers/sentence-transformers:latest container_name: openclaw-bge-embedding restart: unless-stopped ports: - 6006:6006 command: python -m sentence_transformers.serving --model_name BAAI/bge-m3 --port 6006 --host 0.0.0.0 volumes: - ./embedding_models:/root/.cache/sentence_transformers networks: - openclaw-network networks: openclaw-network: driver: bridge volumes: postgres_data: driver: local关键修改点解释网络所有服务postgres, openclaw, chatglm3-api, bge-embedding-api都加入了同一个自定义网络openclaw-network。在这个网络里容器之间可以使用服务名作为主机名互相访问。这就是为什么之前.env文件里我们可以把OPENAI_API_BASE_URL写成http://chatglm3-api:8000/v1的原因。GPU支持在chatglm3-api服务中我们通过deploy.resources或runtime: nvidia来声明需要GPU。这是让容器内模型推理能用上GPU的关键。模型数据持久化通过volumes将宿主机的./models目录映射到容器内的/data。这样第一次下载的模型文件会保存在宿主机上以后重启容器就不需要重新下载了。端口映射我们将ChatGLM3 API的8000端口和BGE-M3 API的6006端口也映射到了宿主机。这方便我们单独测试这些模型服务是否正常工作。修改完docker-compose.yml后必须同步更新.env文件中的模型地址# 在 .env 文件中修改 OPENAI_API_BASE_URLhttp://chatglm3-api:8000/v1 EMBEDDING_OPENAI_API_BASE_URLhttp://bge-embedding-api:6006/v15. 启动服务与初始化验证配置完成后我们就可以启动整个服务栈了。5.1 使用 Docker Compose 启动所有服务在项目根目录/opt/openclaw下执行sudo docker-compose up -d-d参数表示在后台运行。这个命令会依次拉取镜像如果本地没有、创建网络和卷并启动所有定义的服务。使用以下命令查看服务状态和日志# 查看所有容器状态 sudo docker-compose ps # 查看某个服务的日志例如查看模型服务是否正常加载 sudo docker-compose logs -f chatglm3-api重点观察chatglm3-api的日志你会看到它开始从Hugging Face下载THUDM/chatglm3-6b模型。这是一个数GB的文件下载速度取决于你的网络。首次启动可能需要较长时间。当看到类似Connected或Model loaded successfully的日志时说明模型服务就绪了。5.2 验证各服务健康状况验证PostgreSQLsudo docker-compose exec postgres pg_isready -U postgres输出postgres:5432 - accepting connections即表示正常。验证ChatGLM3 API服务curl http://localhost:8000/health或者使用更详细的v1接口检查curl http://localhost:8000/v1/models应该返回一个包含chatglm3-6b模型的JSON响应。验证BGE-M3 Embedding服务curl -X POST http://localhost:6006/embed \ -H Content-Type: application/json \ -d {inputs: [Hello world]}应该返回一个包含向量数组的JSON响应。验证OpenClaw主应用 打开浏览器访问http://你的服务器IP:3000。如果看到OpenClaw的登录或注册界面说明前端服务已启动。但此时可能因为数据库未初始化而无法登录我们需要进行数据迁移。5.3 初始化数据库与管理员账户OpenClaw应用启动后需要执行数据库迁移来创建表结构。通常官方镜像的启动脚本会包含这一步但为了保险我们可以手动触发或检查。# 进入openclaw应用容器 sudo docker-compose exec openclaw bash # 在容器内部执行数据库迁移如果项目使用Prisma等ORM # 具体命令需参考OpenClaw官方文档例如 # npx prisma migrate deploy # 或 # npm run db:migrate # 退出容器 exit更常见的情况是首次访问Web界面 (http://IP:3000) 时会引导你创建一个管理员账户。按照页面提示设置管理员邮箱和密码即可。创建成功后你就能登录到OpenClaw的管理后台了。踩坑实录在这一步我遇到了“502 Bad Gateway”错误。排查发现是chatglm3-api服务启动太慢OpenClaw应用在启动时尝试连接模型服务超时导致自身启动失败。解决方法是在docker-compose.yml中为openclaw服务添加restart: unless-stopped策略并增加健康检查或依赖等待。更简单的办法是先单独启动模型服务并确认其就绪后再启动OpenClaw应用。# 先启动模型和数据库 sudo docker-compose up -d postgres chatglm3-api bge-embedding-api # 等待模型服务日志显示加载完成 sudo docker-compose logs -f chatglm3-api # 看到模型加载成功后再启动主应用 sudo docker-compose up -d openclaw6. 飞书机器人创建与配置现在我们的OpenClaw已经在本地跑起来了。接下来要让它“活”起来能够接收和回复飞书消息。这需要在飞书开放平台创建一个企业自建应用机器人。6.1 在飞书开放平台创建应用访问 飞书开放平台 使用你的飞书管理员账号登录。点击顶部导航栏的“创建企业自建应用”。填写应用名称如“公司AI助手”、描述并上传应用图标。创建成功后进入应用详情页。在“凭证与基础信息”页面你可以找到至关重要的App ID和App Secret。记录下来填入我们之前的.env文件。FEISHU_APP_IDcli_xxxxxx FEISHU_APP_SECRETxxxxxxxxxxxxxxxxxxxxxxxx6.2 配置应用权限与事件订阅机器人要能收发消息需要获取相应权限并让飞书知道把消息推送到哪里。添加权限在应用详情页进入“权限管理”。添加以下权限im:message发送和接收单聊、群聊消息im:message.p2p_msg接收用户发送给机器人的单聊消息im:message.group_msg接收群聊中机器人的消息根据你的需求可能还需要contact:user.id:readonly读取用户信息等。 添加后记得点击“申请线上发布”或“版本管理与发布”来创建新版本并申请审核。对于测试你可以直接添加到“测试企业与人员”中进行体验无需审核。配置事件订阅这是最关键的一步。进入“事件订阅”页面。请求地址 URL填写你的OpenClaw服务的公网可访问地址并加上飞书回调路径。例如https://your-server-domain.com/api/v1/feishu/event。注意飞书要求必须是HTTPS地址。如果你没有域名和SSL证书在测试阶段可以使用内网穿透工具如ngrok、localtunnel生成一个临时的HTTPS地址。生产环境务必配置正式的域名和SSL证书。加密密钥飞书会生成一个Encrypt Key记录下来填入.env的FEISHU_ENCRYPT_KEY。如果不需要加密可以不启用此功能。Verification Token飞书同样会生成一个校验令牌记录下来填入.env的FEISHU_VERIFICATION_TOKEN。订阅事件点击“添加事件”在“消息与群组”分类下找到“接收消息 v2.0”并勾选“机器人接收消息事件”。保存配置。发布应用与添加到群聊完成权限和事件配置后在“版本管理与发布”中将应用发布到“测试环境”或“企业可用环境”。发布后你可以在飞书客户端中通过搜索应用名称找到你的机器人并将其添加到任意群聊或直接与它发起单聊。6.3 在OpenClaw中配置飞书连接更新.env文件后需要重启OpenClaw服务以使配置生效。sudo docker-compose restart openclaw重启后登录OpenClaw的管理后台。通常在“系统设置”、“集成”或“渠道管理”的菜单里可以找到飞书或其他平台的配置界面。将你在飞书开放平台获取的App ID,App Secret,Verification Token,Encrypt Key填写进去并保存。保存成功后OpenClaw后端会验证这些凭证并可能要求你回到飞书开放平台的“事件订阅”页面完成URL验证飞书会向你填写的URL发送一个带特定参数的GET请求你的服务需要正确响应。如果OpenClaw代码实现了验证逻辑这一步通常是自动完成的。6.4 验证消息互通在飞书客户端找到你添加的机器人发送一条消息比如“你好”。查看OpenClaw容器的日志看是否收到了飞书的事件推送sudo docker-compose logs -f openclaw你应该能看到处理im.message.receive_v1事件的日志。同时查看chatglm3-api容器的日志看是否收到了推理请求sudo docker-compose logs -f chatglm3-api如果一切正常几秒后你会在飞书中收到机器人的回复。避坑指南飞书事件订阅失败十有八九是URL验证没通过。常见原因有1) 你的服务器3000端口没有在安全组/防火墙中对外开放2) 你的回调地址不是HTTPS飞书强制要求3) OpenClaw服务中飞书回调的路由路径不对需要检查代码或文档确认正确的路径4) 网络延迟导致飞书验证超时。最有效的调试方法是查看OpenClaw应用的日志里面会明确记录飞书POST/GET请求的详情和错误信息。7. 知识库构建与智能体能力测试核心服务连通后我们要赋予AI智能体“专业知识”即构建知识库。7.1 在OpenClaw中创建知识库登录OpenClaw管理后台 (http://IP:3000)。导航到“知识库”或“知识管理”模块。点击“新建知识库”输入名称如“产品手册”、描述并选择嵌入模型这里应该能看到我们配置的BAAI/bge-m3。创建后进入知识库详情页。7.2 上传文档与处理OpenClaw支持多种文档上传方式本地上传直接上传PDF、Word、Excel、PPT、TXT等文件。批量上传可以打包成ZIP上传。网络抓取输入Confluence、Notion、普通网页的URL系统会自动爬取内容。上传一份你的产品说明书或公司内部FAQ文档进行测试。上传后系统会自动执行以下流水线文档解析将PDF等格式转换为纯文本。文本分割将长文本按语义切割成大小合适的片段Chunk。向量化调用我们部署的BGE-M3嵌入模型将每个文本片段转换为高维向量。存储索引将向量和对应的原文片段存储到ChromaDB中。你可以在界面上看到处理进度。处理完成后知识库会显示文档中的段落数量。7.3 测试问答效果现在我们可以通过两种方式测试在OpenClaw Web界面测试管理后台通常有一个“对话”或“测试”界面。选择你刚创建的知识库然后提问。例如上传了一份空调维修手册你可以问“空调不制冷可能是什么原因”。系统会先从知识库中检索相关段落再结合ChatGLM3模型生成回答。通过飞书机器人测试在飞书中向机器人提问。为了触发知识库检索你需要在问题中明确指向某个知识库或者提前在OpenClaw后台配置机器人的默认知识库。首次回答可能会比较慢因为需要同时进行检索和生成。后续相同知识的回答会快一些。7.4 优化检索效果高级技巧如果发现机器人回答不准确可能是检索环节出了问题。可以尝试以下优化调整文本分割策略在知识库设置中尝试不同的chunk size文本块大小和chunk overlap重叠长度。对于技术文档较小的块如256字和一定的重叠如50字可能效果更好。优化提问方式鼓励用户提出更具体、包含关键实体的问题。检查嵌入模型确保BGE-M3服务运行正常并且为中文文本提供了高质量的向量表示。混合检索OpenClaw可能支持同时使用向量检索和关键词BM25检索然后将结果融合可以提高召回率。8. 常见问题排查与性能优化在实际部署和运行中你肯定会遇到各种问题。这里我整理了从部署到运营全周期可能遇到的典型问题及其解决方案。8.1 部署阶段问题Q1: Docker Compose up 时chatglm3-api服务一直重启日志显示CUDA error: out of memory。原因GPU显存不足。ChatGLM3-6B即使量化后也需要数GB显存。T4显卡16GB通常够用但如果同时运行其他任务或者模型未成功量化就可能爆显存。解决检查docker-compose.yml中模型的启动命令确保包含了量化参数如--quantize bitsandbytes(对于text-generation-inference) 或--load-8bit(对于其他加载方式)。运行nvidia-smi命令查看是否有其他进程占用了大量显存。尝试使用更小的量化等级如4-bit量化如果模型和库支持。如果显存实在太小可以考虑使用CPU推理但速度会慢很多。修改chatglm3-api服务的配置移除GPU声明并添加环境变量DEVICEcpu。Q2: 访问OpenClaw Web界面 (http://IP:3000) 时页面空白或报错。原因前端资源加载失败或后端API未启动。解决检查OpenClaw容器是否正常运行sudo docker-compose ps。查看OpenClaw容器日志sudo docker-compose logs openclaw寻找错误信息。检查浏览器开发者工具F12的“网络(Network)”选项卡看是否有JS/CSS文件加载失败或API请求通常是/api/开头的返回错误如502, 503。这通常指向后端服务如模型服务不可用。逐一验证PostgreSQL、模型API服务是否健康方法见5.2节。Q3: 飞书机器人收不到消息回复OpenClaw日志显示Failed to connect to LLM API。原因OpenClaw无法连接到我们配置的模型API地址 (http://chatglm3-api:8000/v1)。解决进入OpenClaw容器内部测试网络连通性sudo docker-compose exec openclaw bash curl http://chatglm3-api:8000/v1/models如果报错Connection refused或Host not found说明Docker网络配置有问题。确认所有服务都在同一个Docker网络 (openclaw-network) 中sudo docker network inspect openclaw_openclaw-network。确认chatglm3-api服务名拼写正确且容器正在运行。8.2 运行阶段问题Q4: 机器人回复速度非常慢超过30秒。原因可能是模型推理速度慢或知识库检索耗时过长。解决模型侧确保使用了GPU推理。查看nvidia-smi确认GPU利用率。考虑升级为更强大的GPU或使用推理速度更快的库如vLLM。检索侧知识库文档过多向量检索可能变慢。确保ChromaDB运行在内存模式以获得最佳性能。对于超大规模知识库百万级片段考虑迁移到专业的向量数据库如Milvus或Qdrant。优化策略在OpenClaw中设置回答的“超时时间”并为用户设置等待提示。对于复杂问题可以拆分成多个步骤。Q5: 机器人回答的内容与知识库无关经常“胡言乱语”。原因检索到的相关段落太少或质量不高导致模型缺乏有效上下文从而开始“幻觉”。解决检查检索结果在OpenClaw的测试界面通常可以勾选“显示检索来源”或类似选项。看看你提问时系统到底检索到了哪些文本片段。如果检索到的片段不相关就需要优化知识库构建见7.4节。调整检索数量增加每次检索返回的文本片段数量如从3个增加到5个给模型更多上下文。优化提示词在OpenClaw的Agent或模型配置中可以修改系统提示词System Prompt明确要求模型“严格基于提供的上下文回答如果上下文没有相关信息就回答‘我不知道’”。Q6: 知识库文档更新后机器人的回答没有同步更新。原因向量数据库的索引没有更新。仅仅在OpenClaw界面上传新文档或删除旧文档可能不会立即触发向量库的重建。解决在知识库管理界面找到“重建索引”或“同步向量库”的按钮手动触发一次。如果是定时增量更新需要研究OpenClaw是否支持webhook或API以便在源文档变更时自动触发更新流程。8.3 性能与成本优化建议模型量化对于本地部署量化是节省显存和提升推理速度的关键。除了8-bit可以尝试4-bit量化如GPTQ、AWQ能在几乎不损失精度的情况下大幅降低资源消耗。使用更小的模型对于垂直领域知识问答不一定需要ChatGLM3-6B这样规模的模型。可以尝试更小的模型如Qwen1.5-1.8B、ChatGLM3-1.5B它们在特定任务上经过微调后效果可能接近大模型但推理速度快数倍。缓存机制对于常见、重复的问题可以在应用层引入缓存如Redis将“问题-答案”对缓存起来下次相同问题直接返回极大减轻模型负担。异步处理对于飞书的非即时性提问如文档总结、报告生成可以设计为异步模式。机器人先回复“正在处理”然后在后台调用模型完成后通过飞书消息卡片主动推送结果。监控与告警使用PrometheusGrafana监控Docker容器资源CPU、内存、GPU显存、模型API的响应延迟和错误率。设置告警在服务异常时及时通知。走到这一步一个功能完整、私有部署、并集成到飞书的企业级AI智能体就已经搭建完成了。从我的经验来看最大的挑战往往不是步骤本身而是各个环节的联调与排错。尤其是网络配置、模型服务依赖和飞书回调验证这几个环节需要耐心和细致的排查。一旦跑通你会发现它为团队带来的效率提升是显而易见的——无论是新员工快速查询公司制度还是技术支持人员从海量手册中精准定位解决方案这个24小时在线的智能助手都能成为业务的强力赋能者。 企业级AI智能体本地化部署指南：基于OpenClaw与飞书集成
1. 项目概述为什么要在本地部署 OpenClaw最近和几个做企业服务的朋友聊天大家普遍有个痛点市面上的通用AI助手比如ChatGPT、Claude虽然好用但一涉及到企业内部数据比如客户工单、产品文档、销售合同就完全使不上劲了。要么是数据安全不敢往上放要么是回答得牛头不对马嘴因为模型根本不了解你公司的业务上下文。这时候一个能“吃”进你自己知识库、在你自己服务器上跑、还能集成到日常办公软件里的AI智能体就成了刚需。OpenClaw 就是冲着这个需求来的。它不是一个单一的模型而是一个开源的、可本地化部署的AI智能体框架。你可以把它理解为一个“大脑”这个大脑可以连接你本地的各种“感官”也就是你的私有数据源和“手脚”比如飞书、钉钉这样的协作工具。它的核心价值在于你完全掌控数据和流程无需依赖任何外部云服务就能打造一个专属于你企业的、7x24小时在线的智能业务助手。我花了差不多一周时间从零在Linux服务器上把OpenClaw搭了起来并且成功接入了飞书。整个过程踩了不少坑也总结出了一套最顺滑的部署流程。这篇文章我就把我从环境准备、源码部署、模型配置到飞书机器人集成的完整过程以及那些官方文档里没写的“坑点”和调试技巧毫无保留地分享出来。无论你是企业的运维工程师、对AI应用感兴趣的开发者还是想为团队提效的技术负责人这篇手把手的指南都能让你少走弯路快速拥有一个属于自己的企业级AI智能体。2. 核心需求解析与方案选型在动手之前我们得先想清楚部署OpenClaw到底要满足哪些核心需求以及为什么选择当前的方案。2.1 企业级AI智能体的核心需求首先一个合格的企业级AI智能体绝不仅仅是一个聊天机器人。它需要具备以下几个关键能力私有化部署与数据安全这是企业的生命线。所有数据包括知识库文档、用户对话记录、模型本身都必须留在企业内网或可控的私有服务器上杜绝数据泄露风险。OpenClaw作为开源框架完美满足这一点。知识库问答RAG能力智能体需要能够读取和理解企业内部的非结构化数据如PDF、Word、Excel、PPT、TXT以及Confluence、Notion等网页内容。这依赖于RAG检索增强生成技术OpenClaw内置了相关的处理流水线。多模型支持与成本控制企业场景多样有的任务需要大模型的强大推理能力如GPT-4、Claude-3有的则只需小模型快速响应如ChatGLM3、Qwen。OpenClaw支持对接多种开源和闭源模型API允许我们根据场景灵活选用有效控制API调用成本。本地部署时我们主要聚焦于开源模型。无缝集成现有工作流AI能力必须嵌入员工日常使用的工具里才能产生最大价值。飞书、钉钉、企业微信是国内企业最常用的协作平台因此与它们的集成是重中之重。可扩展性与可维护性随着业务发展可能需要增加新的数据源、新的工具Tool或对接新的模型。框架本身需要有清晰的架构和良好的代码规范方便二次开发。2.2 为什么选择 OpenClaw 飞书的组合市面上类似的框架还有LangChain、LlamaIndex等为什么我最终选择了OpenClaw呢主要是基于以下几点考量开箱即用程度高相比需要大量组装工作的LangChainOpenClaw提供了更完整的、产品化的体验。它自带Web管理界面对知识库管理、对话界面、Agent工作流都有现成的模块部署后很快就能用起来更适合追求效率的团队。对中文和国内生态友好项目由国内团队主导文档、社区支持以中文为主并且对国内常用的模型如智谱AI、月之暗面、深度求索等和协作工具飞书、钉钉有原生、深度的集成支持省去了自己造轮子的麻烦。架构清晰易于定制虽然开箱即用但它的模块化设计做得不错。如果你需要自定义数据解析逻辑、添加新的工具或者修改Agent的推理逻辑都能找到清晰的入口不会陷入黑盒。活跃的社区与迭代一个开源项目能否长期用下去社区活跃度是关键。OpenClaw在GitHub上更新频繁Issues和Discussions里的问题响应也比较及时这给了我们长期使用的信心。而选择飞书作为集成入口是因为它集成了IM、日历、文档、审批、机器人等功能于一体用户粘性高。将AI智能体以“飞书机器人”的形式呈现员工无需切换应用在熟悉的聊天窗口就能获得智能辅助落地阻力最小。2.3 技术栈与部署环境规划我们的部署将基于以下技术栈操作系统Ubuntu 22.04 LTS。这是目前云服务器最主流、社区支持最完善的Linux发行版能避免很多依赖库的兼容性问题。容器化Docker Docker Compose。这是现代应用部署的黄金标准。使用容器可以完美解决环境依赖问题保证开发、测试、生产环境的一致性也让后续的升级和维护变得异常简单。OpenClaw官方也推荐这种方式。AI模型考虑到完全本地部署我们将使用开源模型。这里我选择ChatGLM3-6B作为核心语言模型。它由智谱AI开源中英文能力均衡对硬件要求相对友好至少需要16GB GPU显存或32GB内存进行量化部署并且在中文场景下表现优异。同时我们还需要一个嵌入模型Embedding Model来处理文本向量化这里选择同样轻量高效的BGE-M3模型。向量数据库用于存储和快速检索知识库文档转换后的向量。OpenClaw支持多种向量库如Milvus、PGVector等。为了简化部署我们选用与OpenClaw集成度最高、也足够轻量的ChromaDB它可以直接运行在内存或本地文件中。飞书开放平台用于创建和配置机器人获取必要的凭证App ID, App Secret, Verification Token等实现消息接收与发送。整个系统的架构可以简单理解为用户通过飞书向机器人发送消息 - 飞书服务器将消息转发给我们部署的OpenClaw服务 - OpenClaw调用本地ChatGLM3模型理解意图并从ChromaDB知识库中检索相关信息 - 模型结合检索结果生成回答 - 回答通过OpenClaw返回给飞书机器人 - 用户收到回复。3. 基础环境准备与依赖安装万事开头难一个干净、稳定的基础环境是后续所有步骤成功的基石。这一部分我会详细说明服务器选型、系统配置以及核心依赖的安装并附上每一步的验证命令。3.1 服务器规格选择与系统配置OpenClaw的运行资源消耗主要来自大语言模型。如果你希望获得较快的响应速度拥有GPU的服务器是首选。最低配置纯CPU推理速度较慢CPU: 8核以上内存: 32GB磁盘: 100GB SSD网络: 公网IP用于飞书回调推荐配置GPU加速CPU: 8核GPU: NVIDIA RTX 4090 (24GB) 或 A100 (40GB/80GB)。对于ChatGLM3-6B使用量化技术后RTX 4090可以流畅运行。内存: 32GB磁盘: 200GB SSD我本次演示使用的是阿里云的一台ecs.gn7i-c8g1.2xlarge实例配置为8核32GB内存搭载一张NVIDIA T4 GPU16GB显存完全够用。系统初始化步骤更新系统与安装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y vim curl wget git net-tools htop配置SSH免密登录与安全组重要确保你的本地机器可以通过SSH密钥连接到服务器并关闭密码登录以提升安全。同时在云服务商控制台开放服务器安全组中你需要用到的端口例如22(SSH), 80(HTTP), 443(HTTPS)以及OpenClaw应用端口默认为3000。3.2 Docker与NVIDIA容器工具包安装由于我们要在GPU上运行模型必须安装NVIDIA Container Toolkit让Docker容器能够调用宿主机的GPU。卸载旧版本Docker如有sudo apt remove docker docker-engine docker.io containerd runc安装Docker官方仓库和最新版本# 安装依赖包 sudo apt install -y ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 设置稳定版仓库 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker引擎 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin验证Docker安装sudo docker run hello-world如果看到“Hello from Docker!”的输出说明安装成功。安装NVIDIA Container Toolkit# 添加仓库和GPG密钥 distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \ sed s#deb https://#deb [signed-by/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g | \ sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list # 安装工具包 sudo apt update sudo apt install -y nvidia-container-toolkit # 配置Docker使用nvidia作为默认运行时 sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker验证GPU在Docker中可用sudo docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi这个命令会启动一个带有CUDA基础的容器并运行nvidia-smi。如果成功输出GPU信息表格恭喜你最关键的一步已经完成。实操心得在这一步最常见的坑是nvidia-smi在宿主机上运行正常但在容器内报错“Failed to initialize NVML: Driver/library version mismatch”。这通常是因为宿主机重启后内核版本更新导致NVIDIA驱动内核模块版本与用户态库版本不匹配。解决方法很简单重启宿主机。重启后驱动会自动重新编译内核模块使其匹配。3.3 获取OpenClaw项目源码我们直接从GitHub拉取最新的OpenClaw代码。建议创建一个专门的目录来管理所有相关文件。# 创建项目目录 mkdir -p /opt/openclaw cd /opt/openclaw # 克隆仓库 (请替换为官方仓库地址此处为示例) git clone https://github.com/open-claw/openclaw.git . # 切换到稳定版本分支避免使用可能不稳定的main分支 git checkout release/v1.0.0 # 请查看仓库的最新稳定版标签拉取代码后你会看到项目目录结构其中docker-compose.yml和.env.example是我们需要重点关注的文件。4. 配置文件详解与关键参数调优OpenClaw通过环境变量和配置文件来驱动整个应用。直接使用默认配置很可能无法运行我们必须根据自身环境进行定制。4.1 环境变量文件 (.env) 配置项目根目录下通常有一个.env.example文件我们需要复制它并修改为.env。cp .env.example .env vim .env下面我逐行解释关键配置项及其填写方法# ############################### # 应用基础配置 # ############################### NODE_ENVproduction # 设置为生产环境 PORT3000 # OpenClaw Web服务端口确保防火墙已开放此端口 API_KEYsk-your-secret-key-here # 用于调用OpenClaw API的密钥务必修改为复杂字符串 # ############################### # 数据库配置 (PostgreSQL) # ############################### # 使用Docker Compose时通常用服务名作为主机名 DB_HOSTpostgres # 对应docker-compose.yml中的PostgreSQL服务名 DB_PORT5432 DB_USERpostgres # 数据库用户名 DB_PASSWORDyour_strong_password_here # 数据库密码必须修改 DB_DATABASEopenclaw # 数据库名 DB_SSLfalse # 内网部署通常关闭SSL # ############################### # 向量数据库配置 (ChromaDB) # ############################### VECTOR_DB_TYPEchromadb # 指定使用ChromaDB CHROMADB_PERSIST_PATH/app/data/chromadb # 容器内向量数据持久化路径 # 注意此路径会在容器内我们需要通过卷(volume)映射到宿主机 # ############################### # 大语言模型 (LLM) 配置 # ############################### # 这里配置我们本地部署的ChatGLM3 LLM_TYPEopenai # OpenClaw使用OpenAI API兼容的接口许多本地模型服务也提供此兼容接口 OPENAI_API_KEYEMPTY # 因为用本地模型这里可以填空或任意值但键名需要保留 OPENAI_API_BASE_URLhttp://localhost:8000/v1 # 指向本地启动的ChatGLM3 API服务地址 OPENAI_API_MODEL_NAMEchatglm3-6b # 模型名称与API服务返回的一致即可 # ############################### # 嵌入模型 (Embedding) 配置 # ############################### # 配置本地部署的BGE-M3嵌入模型 EMBEDDING_TYPEopenai # 同样使用OpenAI兼容接口 EMBEDDING_OPENAI_API_KEYEMPTY EMBEDDING_OPENAI_API_BASE_URLhttp://localhost:6006/v1 # 指向本地BGE-M3 API服务 EMBEDDING_OPENAI_API_MODEL_NAMEBAAI/bge-m3 # 模型名称 # ############################### # 飞书机器人配置 (暂留空后续获取后填写) # ############################### FEISHU_APP_ID FEISHU_APP_SECRET FEISHU_VERIFICATION_TOKEN FEISHU_ENCRYPT_KEY # 如果飞书应用开启了“启用加密”则需要填写注意事项DB_PASSWORD、API_KEY务必替换为高强度密码。OPENAI_API_BASE_URL和EMBEDDING_OPENAI_API_BASE_URL是关键。它们指向我们后续将要启动的本地模型服务。localhost在Docker Compose网络内指向的是每个容器自己。因此如果模型服务与OpenClaw主应用不在同一个Docker容器内就不能用localhost。我们需要使用Docker Compose的服务名作为主机名。假设我们在docker-compose.yml里定义了一个叫llm-api的服务来提供ChatGLM3那么这里就应该填http://llm-api:8000/v1。这是部署中最容易出错的地方之一。先保留飞书配置为空我们完成基础部署后再去飞书开放平台申请。4.2 Docker Compose 文件调整默认的docker-compose.yml可能只包含了OpenClaw主应用和PostgreSQL。我们需要修改它把ChatGLM3和BGE-M3的模型服务也集成进来并配置正确的网络和卷映射。version: 3.8 services: # 1. PostgreSQL 数据库 postgres: image: postgres:15-alpine container_name: openclaw-postgres restart: unless-stopped environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: your_strong_password_here # 与.env中DB_PASSWORD一致 POSTGRES_DB: openclaw volumes: - postgres_data:/var/lib/postgresql/data networks: - openclaw-network # 2. OpenClaw 主应用 openclaw: image: openclaw/openclaw:latest # 使用官方镜像或自己构建 container_name: openclaw-app restart: unless-stopped ports: - 3000:3000 # 将宿主机的3000端口映射到容器的3000端口 depends_on: - postgres - chatglm3-api # 依赖模型服务 - bge-embedding-api environment: - NODE_ENVproduction # 其他环境变量通过.env文件传入 env_file: - .env volumes: # 映射上传文件目录 - ./storage/uploads:/app/storage/uploads # 映射日志目录 - ./logs:/app/logs # 映射向量数据库持久化目录 (确保与.env中CHROMADB_PERSIST_PATH的父目录对应) - ./data/chromadb:/app/data/chromadb networks: - openclaw-network # 3. ChatGLM3-6B API 服务 (使用开源项目 fastchat 或 vllm 部署) chatglm3-api: image: ghcr.io/huggingface/text-generation-inference:latest # 或使用其他镜像如chatglm3-6b-api:latest container_name: openclaw-chatglm3 restart: unless-stopped # 部署GPU资源非常重要 deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] # 另一种简单的GPU声明方式与deploy二选一 # runtime: nvidia # environment: # - NVIDIA_VISIBLE_DEVICESall ports: - 8000:8000 command: --model-id THUDM/chatglm3-6b --hostname 0.0.0.0 --port 8000 --max-input-length 4096 --max-total-tokens 8192 --quantize bitsandbytes # 启用量化以减少显存占用 volumes: # 映射模型缓存目录避免每次下载 - ./models:/data networks: - openclaw-network # 4. BGE-M3 Embedding API 服务 bge-embedding-api: image: sentence-transformers/sentence-transformers:latest container_name: openclaw-bge-embedding restart: unless-stopped ports: - 6006:6006 command: python -m sentence_transformers.serving --model_name BAAI/bge-m3 --port 6006 --host 0.0.0.0 volumes: - ./embedding_models:/root/.cache/sentence_transformers networks: - openclaw-network networks: openclaw-network: driver: bridge volumes: postgres_data: driver: local关键修改点解释网络所有服务postgres, openclaw, chatglm3-api, bge-embedding-api都加入了同一个自定义网络openclaw-network。在这个网络里容器之间可以使用服务名作为主机名互相访问。这就是为什么之前.env文件里我们可以把OPENAI_API_BASE_URL写成http://chatglm3-api:8000/v1的原因。GPU支持在chatglm3-api服务中我们通过deploy.resources或runtime: nvidia来声明需要GPU。这是让容器内模型推理能用上GPU的关键。模型数据持久化通过volumes将宿主机的./models目录映射到容器内的/data。这样第一次下载的模型文件会保存在宿主机上以后重启容器就不需要重新下载了。端口映射我们将ChatGLM3 API的8000端口和BGE-M3 API的6006端口也映射到了宿主机。这方便我们单独测试这些模型服务是否正常工作。修改完docker-compose.yml后必须同步更新.env文件中的模型地址# 在 .env 文件中修改 OPENAI_API_BASE_URLhttp://chatglm3-api:8000/v1 EMBEDDING_OPENAI_API_BASE_URLhttp://bge-embedding-api:6006/v15. 启动服务与初始化验证配置完成后我们就可以启动整个服务栈了。5.1 使用 Docker Compose 启动所有服务在项目根目录/opt/openclaw下执行sudo docker-compose up -d-d参数表示在后台运行。这个命令会依次拉取镜像如果本地没有、创建网络和卷并启动所有定义的服务。使用以下命令查看服务状态和日志# 查看所有容器状态 sudo docker-compose ps # 查看某个服务的日志例如查看模型服务是否正常加载 sudo docker-compose logs -f chatglm3-api重点观察chatglm3-api的日志你会看到它开始从Hugging Face下载THUDM/chatglm3-6b模型。这是一个数GB的文件下载速度取决于你的网络。首次启动可能需要较长时间。当看到类似Connected或Model loaded successfully的日志时说明模型服务就绪了。5.2 验证各服务健康状况验证PostgreSQLsudo docker-compose exec postgres pg_isready -U postgres输出postgres:5432 - accepting connections即表示正常。验证ChatGLM3 API服务curl http://localhost:8000/health或者使用更详细的v1接口检查curl http://localhost:8000/v1/models应该返回一个包含chatglm3-6b模型的JSON响应。验证BGE-M3 Embedding服务curl -X POST http://localhost:6006/embed \ -H Content-Type: application/json \ -d {inputs: [Hello world]}应该返回一个包含向量数组的JSON响应。验证OpenClaw主应用 打开浏览器访问http://你的服务器IP:3000。如果看到OpenClaw的登录或注册界面说明前端服务已启动。但此时可能因为数据库未初始化而无法登录我们需要进行数据迁移。5.3 初始化数据库与管理员账户OpenClaw应用启动后需要执行数据库迁移来创建表结构。通常官方镜像的启动脚本会包含这一步但为了保险我们可以手动触发或检查。# 进入openclaw应用容器 sudo docker-compose exec openclaw bash # 在容器内部执行数据库迁移如果项目使用Prisma等ORM # 具体命令需参考OpenClaw官方文档例如 # npx prisma migrate deploy # 或 # npm run db:migrate # 退出容器 exit更常见的情况是首次访问Web界面 (http://IP:3000) 时会引导你创建一个管理员账户。按照页面提示设置管理员邮箱和密码即可。创建成功后你就能登录到OpenClaw的管理后台了。踩坑实录在这一步我遇到了“502 Bad Gateway”错误。排查发现是chatglm3-api服务启动太慢OpenClaw应用在启动时尝试连接模型服务超时导致自身启动失败。解决方法是在docker-compose.yml中为openclaw服务添加restart: unless-stopped策略并增加健康检查或依赖等待。更简单的办法是先单独启动模型服务并确认其就绪后再启动OpenClaw应用。# 先启动模型和数据库 sudo docker-compose up -d postgres chatglm3-api bge-embedding-api # 等待模型服务日志显示加载完成 sudo docker-compose logs -f chatglm3-api # 看到模型加载成功后再启动主应用 sudo docker-compose up -d openclaw6. 飞书机器人创建与配置现在我们的OpenClaw已经在本地跑起来了。接下来要让它“活”起来能够接收和回复飞书消息。这需要在飞书开放平台创建一个企业自建应用机器人。6.1 在飞书开放平台创建应用访问 飞书开放平台 使用你的飞书管理员账号登录。点击顶部导航栏的“创建企业自建应用”。填写应用名称如“公司AI助手”、描述并上传应用图标。创建成功后进入应用详情页。在“凭证与基础信息”页面你可以找到至关重要的App ID和App Secret。记录下来填入我们之前的.env文件。FEISHU_APP_IDcli_xxxxxx FEISHU_APP_SECRETxxxxxxxxxxxxxxxxxxxxxxxx6.2 配置应用权限与事件订阅机器人要能收发消息需要获取相应权限并让飞书知道把消息推送到哪里。添加权限在应用详情页进入“权限管理”。添加以下权限im:message发送和接收单聊、群聊消息im:message.p2p_msg接收用户发送给机器人的单聊消息im:message.group_msg接收群聊中机器人的消息根据你的需求可能还需要contact:user.id:readonly读取用户信息等。 添加后记得点击“申请线上发布”或“版本管理与发布”来创建新版本并申请审核。对于测试你可以直接添加到“测试企业与人员”中进行体验无需审核。配置事件订阅这是最关键的一步。进入“事件订阅”页面。请求地址 URL填写你的OpenClaw服务的公网可访问地址并加上飞书回调路径。例如https://your-server-domain.com/api/v1/feishu/event。注意飞书要求必须是HTTPS地址。如果你没有域名和SSL证书在测试阶段可以使用内网穿透工具如ngrok、localtunnel生成一个临时的HTTPS地址。生产环境务必配置正式的域名和SSL证书。加密密钥飞书会生成一个Encrypt Key记录下来填入.env的FEISHU_ENCRYPT_KEY。如果不需要加密可以不启用此功能。Verification Token飞书同样会生成一个校验令牌记录下来填入.env的FEISHU_VERIFICATION_TOKEN。订阅事件点击“添加事件”在“消息与群组”分类下找到“接收消息 v2.0”并勾选“机器人接收消息事件”。保存配置。发布应用与添加到群聊完成权限和事件配置后在“版本管理与发布”中将应用发布到“测试环境”或“企业可用环境”。发布后你可以在飞书客户端中通过搜索应用名称找到你的机器人并将其添加到任意群聊或直接与它发起单聊。6.3 在OpenClaw中配置飞书连接更新.env文件后需要重启OpenClaw服务以使配置生效。sudo docker-compose restart openclaw重启后登录OpenClaw的管理后台。通常在“系统设置”、“集成”或“渠道管理”的菜单里可以找到飞书或其他平台的配置界面。将你在飞书开放平台获取的App ID,App Secret,Verification Token,Encrypt Key填写进去并保存。保存成功后OpenClaw后端会验证这些凭证并可能要求你回到飞书开放平台的“事件订阅”页面完成URL验证飞书会向你填写的URL发送一个带特定参数的GET请求你的服务需要正确响应。如果OpenClaw代码实现了验证逻辑这一步通常是自动完成的。6.4 验证消息互通在飞书客户端找到你添加的机器人发送一条消息比如“你好”。查看OpenClaw容器的日志看是否收到了飞书的事件推送sudo docker-compose logs -f openclaw你应该能看到处理im.message.receive_v1事件的日志。同时查看chatglm3-api容器的日志看是否收到了推理请求sudo docker-compose logs -f chatglm3-api如果一切正常几秒后你会在飞书中收到机器人的回复。避坑指南飞书事件订阅失败十有八九是URL验证没通过。常见原因有1) 你的服务器3000端口没有在安全组/防火墙中对外开放2) 你的回调地址不是HTTPS飞书强制要求3) OpenClaw服务中飞书回调的路由路径不对需要检查代码或文档确认正确的路径4) 网络延迟导致飞书验证超时。最有效的调试方法是查看OpenClaw应用的日志里面会明确记录飞书POST/GET请求的详情和错误信息。7. 知识库构建与智能体能力测试核心服务连通后我们要赋予AI智能体“专业知识”即构建知识库。7.1 在OpenClaw中创建知识库登录OpenClaw管理后台 (http://IP:3000)。导航到“知识库”或“知识管理”模块。点击“新建知识库”输入名称如“产品手册”、描述并选择嵌入模型这里应该能看到我们配置的BAAI/bge-m3。创建后进入知识库详情页。7.2 上传文档与处理OpenClaw支持多种文档上传方式本地上传直接上传PDF、Word、Excel、PPT、TXT等文件。批量上传可以打包成ZIP上传。网络抓取输入Confluence、Notion、普通网页的URL系统会自动爬取内容。上传一份你的产品说明书或公司内部FAQ文档进行测试。上传后系统会自动执行以下流水线文档解析将PDF等格式转换为纯文本。文本分割将长文本按语义切割成大小合适的片段Chunk。向量化调用我们部署的BGE-M3嵌入模型将每个文本片段转换为高维向量。存储索引将向量和对应的原文片段存储到ChromaDB中。你可以在界面上看到处理进度。处理完成后知识库会显示文档中的段落数量。7.3 测试问答效果现在我们可以通过两种方式测试在OpenClaw Web界面测试管理后台通常有一个“对话”或“测试”界面。选择你刚创建的知识库然后提问。例如上传了一份空调维修手册你可以问“空调不制冷可能是什么原因”。系统会先从知识库中检索相关段落再结合ChatGLM3模型生成回答。通过飞书机器人测试在飞书中向机器人提问。为了触发知识库检索你需要在问题中明确指向某个知识库或者提前在OpenClaw后台配置机器人的默认知识库。首次回答可能会比较慢因为需要同时进行检索和生成。后续相同知识的回答会快一些。7.4 优化检索效果高级技巧如果发现机器人回答不准确可能是检索环节出了问题。可以尝试以下优化调整文本分割策略在知识库设置中尝试不同的chunk size文本块大小和chunk overlap重叠长度。对于技术文档较小的块如256字和一定的重叠如50字可能效果更好。优化提问方式鼓励用户提出更具体、包含关键实体的问题。检查嵌入模型确保BGE-M3服务运行正常并且为中文文本提供了高质量的向量表示。混合检索OpenClaw可能支持同时使用向量检索和关键词BM25检索然后将结果融合可以提高召回率。8. 常见问题排查与性能优化在实际部署和运行中你肯定会遇到各种问题。这里我整理了从部署到运营全周期可能遇到的典型问题及其解决方案。8.1 部署阶段问题Q1: Docker Compose up 时chatglm3-api服务一直重启日志显示CUDA error: out of memory。原因GPU显存不足。ChatGLM3-6B即使量化后也需要数GB显存。T4显卡16GB通常够用但如果同时运行其他任务或者模型未成功量化就可能爆显存。解决检查docker-compose.yml中模型的启动命令确保包含了量化参数如--quantize bitsandbytes(对于text-generation-inference) 或--load-8bit(对于其他加载方式)。运行nvidia-smi命令查看是否有其他进程占用了大量显存。尝试使用更小的量化等级如4-bit量化如果模型和库支持。如果显存实在太小可以考虑使用CPU推理但速度会慢很多。修改chatglm3-api服务的配置移除GPU声明并添加环境变量DEVICEcpu。Q2: 访问OpenClaw Web界面 (http://IP:3000) 时页面空白或报错。原因前端资源加载失败或后端API未启动。解决检查OpenClaw容器是否正常运行sudo docker-compose ps。查看OpenClaw容器日志sudo docker-compose logs openclaw寻找错误信息。检查浏览器开发者工具F12的“网络(Network)”选项卡看是否有JS/CSS文件加载失败或API请求通常是/api/开头的返回错误如502, 503。这通常指向后端服务如模型服务不可用。逐一验证PostgreSQL、模型API服务是否健康方法见5.2节。Q3: 飞书机器人收不到消息回复OpenClaw日志显示Failed to connect to LLM API。原因OpenClaw无法连接到我们配置的模型API地址 (http://chatglm3-api:8000/v1)。解决进入OpenClaw容器内部测试网络连通性sudo docker-compose exec openclaw bash curl http://chatglm3-api:8000/v1/models如果报错Connection refused或Host not found说明Docker网络配置有问题。确认所有服务都在同一个Docker网络 (openclaw-network) 中sudo docker network inspect openclaw_openclaw-network。确认chatglm3-api服务名拼写正确且容器正在运行。8.2 运行阶段问题Q4: 机器人回复速度非常慢超过30秒。原因可能是模型推理速度慢或知识库检索耗时过长。解决模型侧确保使用了GPU推理。查看nvidia-smi确认GPU利用率。考虑升级为更强大的GPU或使用推理速度更快的库如vLLM。检索侧知识库文档过多向量检索可能变慢。确保ChromaDB运行在内存模式以获得最佳性能。对于超大规模知识库百万级片段考虑迁移到专业的向量数据库如Milvus或Qdrant。优化策略在OpenClaw中设置回答的“超时时间”并为用户设置等待提示。对于复杂问题可以拆分成多个步骤。Q5: 机器人回答的内容与知识库无关经常“胡言乱语”。原因检索到的相关段落太少或质量不高导致模型缺乏有效上下文从而开始“幻觉”。解决检查检索结果在OpenClaw的测试界面通常可以勾选“显示检索来源”或类似选项。看看你提问时系统到底检索到了哪些文本片段。如果检索到的片段不相关就需要优化知识库构建见7.4节。调整检索数量增加每次检索返回的文本片段数量如从3个增加到5个给模型更多上下文。优化提示词在OpenClaw的Agent或模型配置中可以修改系统提示词System Prompt明确要求模型“严格基于提供的上下文回答如果上下文没有相关信息就回答‘我不知道’”。Q6: 知识库文档更新后机器人的回答没有同步更新。原因向量数据库的索引没有更新。仅仅在OpenClaw界面上传新文档或删除旧文档可能不会立即触发向量库的重建。解决在知识库管理界面找到“重建索引”或“同步向量库”的按钮手动触发一次。如果是定时增量更新需要研究OpenClaw是否支持webhook或API以便在源文档变更时自动触发更新流程。8.3 性能与成本优化建议模型量化对于本地部署量化是节省显存和提升推理速度的关键。除了8-bit可以尝试4-bit量化如GPTQ、AWQ能在几乎不损失精度的情况下大幅降低资源消耗。使用更小的模型对于垂直领域知识问答不一定需要ChatGLM3-6B这样规模的模型。可以尝试更小的模型如Qwen1.5-1.8B、ChatGLM3-1.5B它们在特定任务上经过微调后效果可能接近大模型但推理速度快数倍。缓存机制对于常见、重复的问题可以在应用层引入缓存如Redis将“问题-答案”对缓存起来下次相同问题直接返回极大减轻模型负担。异步处理对于飞书的非即时性提问如文档总结、报告生成可以设计为异步模式。机器人先回复“正在处理”然后在后台调用模型完成后通过飞书消息卡片主动推送结果。监控与告警使用PrometheusGrafana监控Docker容器资源CPU、内存、GPU显存、模型API的响应延迟和错误率。设置告警在服务异常时及时通知。走到这一步一个功能完整、私有部署、并集成到飞书的企业级AI智能体就已经搭建完成了。从我的经验来看最大的挑战往往不是步骤本身而是各个环节的联调与排错。尤其是网络配置、模型服务依赖和飞书回调验证这几个环节需要耐心和细致的排查。一旦跑通你会发现它为团队带来的效率提升是显而易见的——无论是新员工快速查询公司制度还是技术支持人员从海量手册中精准定位解决方案这个24小时在线的智能助手都能成为业务的强力赋能者。