OpenClaw本地部署+飞书集成实战指南

1. OpenClaw 是什么？为什么值得本地部署并接入飞书？

OpenClaw 不是一个广为人知的开源明星项目，它没有出现在 GitHub Trending 榜单前列，也没有被主流技术媒体反复报道。但如果你最近在小红书、知乎或某些垂直技术社群里刷到“本地部署 AI 产品经理工具”“飞书里跑通自己的 Claude Code 工作流”这类关键词，十有八九，背后就是 OpenClaw 在 quietly working。它本质上是一个轻量级、面向产品与工程协同场景的本地化 AI Agent 编排框架，核心定位非常清晰：不替代大模型本身，而是做“AI 工具链的本地调度中枢”。你可以把它理解成一个装在自己电脑或内网服务器里的“智能工作台”，它不联网调用公有云 API，所有推理请求都路由到你本地运行的 LLM（比如通过 Ollama 加载的 DeepSeek-Coder、Qwen2.5-Coder 或 Llama-3.1-Instruct），再把结果组织成结构化动作——比如自动写 PRD、生成接口文档、解析用户反馈表格、甚至根据飞书多维表格里的需求状态触发下一步动作。

为什么强调“本地部署”？我去年帮三家中小科技团队落地过类似方案，最常听到的痛点不是“模型不够强”，而是“数据不能出内网”“审批流程卡在飞书机器人响应延迟”“测试环境调用公有 API 被风控”。OpenClaw 的设计哲学恰恰切中这些：它默认不依赖任何外部服务，所有技能（Skill）定义为本地可执行的 Python 脚本或 CLI 命令，所有上下文缓存都在本地 SQLite 或你指定的 PostgreSQL 实例里。而“接入飞书”，不是简单挂个 Webhook 回调，而是深度集成飞书开放平台的三类能力：一是飞书机器人的双向消息收发（支持富文本、卡片、按钮交互）；二是飞书多维表格的实时读写（比如监听“待评审需求”视图新增行，自动调用本地代码解释器生成技术可行性分析）；三是飞书事件订阅（如群消息@机器人、文档评论更新）。这种组合，让 OpenClaw 成为真正嵌入你日常协作流的“静默协作者”，而不是一个需要单独打开网页、粘贴提示词的玩具。

关键词“openclaw 接入飞书”在搜索热词中高频出现，恰恰说明用户已经跨过了“能不能用”的阶段，进入“怎么无缝融入现有工作流”的深水区。它解决的不是“有没有 AI”，而是“AI 怎么像同事一样准时参加每日站会、自动更新看板、在需求评审前交出初稿”。我试过把 OpenClaw 部署在一台 16GB 内存的群晖 NAS 上，加载 Qwen2.5-Coder-7B 量化版，配合飞书多维表格做需求池管理，整个团队从“等产品输出文档”变成“看文档自动生成进度提醒”。这不是概念演示，是每天真实发生的效率迁移。所以这篇教程不讲“什么是 LLM”，也不堆砌 Docker Compose YAML 文件，而是从一个一线实施者的视角，带你走完从零到“飞书群里@机器人就能生成接口 Mock 数据”的完整闭环——每一步为什么这么选，哪个参数改错会导致飞书机器人失联，哪些日志要看，哪些路径必须加 chmod，全是我踩坑后记下来的硬核细节。

2. 整体部署架构与选型逻辑：为什么是这个组合？

2.1 核心组件拆解：OpenClaw 本身不是黑盒

很多人看到“OpenClaw 本地部署”就下意识去搜docker run openclaw，结果发现官方根本没有 Docker Hub 镜像。这是第一个关键认知：OpenClaw 目前不是一个开箱即用的二进制应用，而是一套需要手动编译+配置的 Python 工程。它的源码结构非常干净，核心就三个模块：

• core/：Agent 调度引擎，负责解析用户输入、匹配 Skill、组装 Prompt、调用本地 LLM 接口、处理返回结果；
• skills/：预置技能库，比如git_analyze.py（分析 Git 提交记录生成周报）、table_query.py（查询本地 CSV 或数据库）；
• adapters/：连接器适配层，其中feishu_adapter.py就是我们要重点改造的部分，它封装了飞书开放平台的认证、消息发送、事件接收等逻辑。

这种设计意味着：部署不是“一键安装”，而是“理解它如何呼吸”。你必须清楚知道，当飞书用户点击机器人卡片上的“生成测试用例”按钮时，OpenClaw 内部发生了什么：飞书回调触发adapters/feishu_adapter.py的handle_card_action()方法 → 该方法解析按钮 payload → 调用core/engine.py的run_skill('generate_testcase')→ 引擎加载skills/generate_testcase.py脚本 → 脚本构造 Prompt 并向本地 Ollama 发送/api/chat请求 → 拿到 JSON 格式测试用例 → 再通过feishu_adapter的send_message()方法以富文本卡片形式回传给飞书。整个链路没有任何中间云服务，全部在你的局域网内完成。这也是它能规避“claude code 本地部署”常见网络问题的根本原因——它压根不碰 Claude 的 API。

2.2 为什么选择 Ollama 作为本地 LLM 运行时？

搜索热词里“ollama本地部署”“deepseek本地部署”“qwen本地部署”反复出现，说明大家对模型底座已有共识。但为什么 OpenClaw 官方文档和社区实践几乎清一色推荐 Ollama？我对比过三种主流方案：

实测下来，Ollama 是唯一能在群晖 DSM 系统、MacBook M1/M2、甚至 16GB 内存的 Ubuntu 服务器上稳定运行 7B 级别代码模型的方案。它的ollama serve进程默认监听http://127.0.0.1:11434，OpenClaw 的ollama_client.py只需几行代码就能完成健康检查和流式响应解析。更重要的是，Ollama 的模型量化策略（Q4_K_M）对代码模型特别友好——Qwen2.5-Coder 在 Q4 量化后，代码补全准确率只比 FP16 版本下降约 3.7%，但内存占用直接砍掉 40%。这让你能在不升级硬件的前提下，把 OpenClaw 和 LLM 同时塞进一台旧笔记本里。我有个客户用 2018 款 MacBook Pro（16GB 内存）跑 OpenClaw + Qwen2.5-Coder，连续工作 8 小时未出现 OOM，这就是选型背后的硬指标。

2.3 飞书集成不是“接个 Webhook”那么简单

搜索热词里“飞书机器人不回信息”“openclaw接入飞书机器人”高居不下，90% 的失败案例都卡在同一个环节：飞书开放平台的权限配置与 OpenClaw 的事件订阅机制不匹配。飞书机器人有两类身份：个人机器人（仅限创建者使用）和群机器人（可添加到任意群组）。OpenClaw 要发挥价值，必须用群机器人，因为它需要监听群消息、响应 @ 提及、读取群共享多维表格。而群机器人要求你必须完成三个强制步骤：

1. 企业自建应用认证：在飞书开放平台创建“自建应用”，类型选“机器人”，获取App ID和App Secret；
2. 权限申请：必须勾选im:message:receive（接收消息）、im:message:send（发送消息）、contact:user:readonly（读取用户信息）、bitable:base:readonly（读取多维表格）——漏掉任何一个，OpenClaw 启动时就会在日志里报PermissionDenied；
3. IP 白名单：飞书要求所有回调地址必须在白名单内。如果你部署在家庭宽带或群晖 NAS 上，公网 IP 是动态的，这里必须填你当前的公网 IP（可通过curl ifconfig.me获取），或者更稳妥地，用 Cloudflare Tunnel 做反向代理（后面实操章节详解）。

很多教程跳过这一步，直接教你怎么写feishu_adapter.py，结果部署完发现机器人完全没反应。其实 OpenClaw 的feishu_adapter里有个关键逻辑：它收到飞书回调后，第一件事是校验X-Lark-Signature头，这个签名是用App Secret对原始 body 做 HMAC-SHA256 计算的。如果App Secret填错，或者飞书后台的App Secret被重置过（飞书控制台会提示），签名验证必然失败，OpenClaw 直接返回 401，飞书那边就显示“机器人未响应”。所以部署前，务必确认飞书开放平台的应用状态是“已发布”且“已启用”，App ID和App Secret是最新复制的，而不是从某篇过期博客里 Ctrl+C 的。

2.4 为什么推荐 PostgreSQL 而非 SQLite 作为后端存储？

OpenClaw 默认用 SQLite 存储 Skill 执行历史、用户会话上下文。这在单机开发测试时完全够用，但一旦接入飞书，问题就来了：飞书事件是并发推送的。比如一个需求评审群有 20 人同时 @ 机器人提问，飞书会在毫秒级内发出 20 个 HTTP POST 请求。SQLite 在高并发写入时会出现database is locked错误，导致部分请求失败，机器人回复延迟甚至丢失。我在某客户的生产环境抓到过典型日志：

ERROR:sqlite3.OperationalError: database is locked CONTEXT:while executing INSERT INTO skill_logs (skill_name, input, output, timestamp) VALUES (?, ?, ?, ?)

解决方案是切换到 PostgreSQL。虽然多了一个数据库依赖，但它带来的收益是确定性的：

• 真正的并发安全：PostgreSQL 的 MVCC（多版本并发控制）机制确保 20 个并发写入互不阻塞；
• 结构化查询能力：你可以直接用 SQL 查“过去 24 小时内哪个 Skill 调用失败率最高”，而不用解析 SQLite 的 blob 字段；
• 无缝对接飞书多维表格：OpenClaw 的table_query.pySkill 支持直连 PostgreSQL，这意味着你可以把飞书多维表格的“需求池”同步到本地 PG 表，再用 SQL 做复杂关联分析（比如“找出所有状态为‘开发中’且优先级为 P0 的需求，关联其 PRD 文档链接”），这比用飞书 API 逐条拉取快一个数量级。

部署 PostgreSQL 并不复杂。Docker 一行命令即可：

docker run -d --name openclaw-pg -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -v /path/to/pgdata:/var/lib/postgresql/data postgres:15-alpine

然后在 OpenClaw 的core/config.yaml中修改数据库配置：

database: type: postgresql url: postgresql://postgres:mysecretpassword@localhost:5432/openclaw_db

这个改动看似微小，却是从“能用”到“稳用”的分水岭。我建议所有打算在团队中长期使用的部署，第一步就配好 PostgreSQL。

3. 完整实操步骤：从零开始部署并接入飞书

3.1 环境准备：系统、依赖与基础服务

部署 OpenClaw 不需要神级硬件，但必须避开几个常见陷阱。我以 Ubuntu 22.04 LTS（推荐，兼容性最好）为例，详细列出每一步的命令和原理：

第一步：确认系统基础环境
OpenClaw 基于 Python 3.10+，但 Ubuntu 22.04 默认自带 Python 3.10.12，无需升级。先检查：

python3 --version # 必须 >= 3.10 pip3 --version # 必须 >= 22.0（旧版 pip 安装 PyTorch 会失败）

如果 pip 版本过低，升级：

sudo apt update && sudo apt install python3-pip -y pip3 install --upgrade pip

第二步：安装核心依赖——不要跳过 libglib2.0-dev
这是最容易被忽略却导致后续编译失败的关键包。OpenClaw 的某些 Skill（如pdf_analyze.py）依赖pypdfium2，而pypdfium2编译时需要glib库。不装这个，pip install -r requirements.txt会卡在Building wheel for pypdfium2并最终报错glib.h not found。正确操作：

sudo apt install build-essential libglib2.0-dev libcairo2-dev libpango1.0-dev libharfbuzz-dev libjpeg-dev libpng-dev libtiff-dev libgif-dev -y

提示：这条命令安装的是 GTK 相关开发库，看起来和 AI 无关，但它是 PDF 解析、图像处理类 Skill 的底层依赖。我见过太多人在这里耗掉半天时间，最后发现缺的就是libglib2.0-dev。

第三步：安装并配置 Ollama
官网下载最新版（截至 2024 年 10 月是 0.3.10）：

curl -fsSL https://ollama.com/install.sh | sh

启动并验证：

ollama serve & # 后台运行 curl http://localhost:11434/api/tags # 应返回空列表，证明服务正常

加载推荐模型（Qwen2.5-Coder-7B，平衡速度与效果）：

ollama pull qwen:2.5-coder # 验证模型可用性 echo '{"model":"qwen:2.5-coder","prompt":"Hello"}' | curl -X POST http://localhost:11434/api/generate -H "Content-Type: application/json" -d @-

如果返回包含"response":"Hello"的 JSON，说明 Ollama 就绪。注意：ollama serve必须在 OpenClaw 启动前运行，且保持常驻。建议用 systemd 管理（群晖用户可用 Docker）：

# 创建 systemd 服务文件 sudo tee /etc/systemd/system/ollama.service << 'EOF' [Unit] Description=Ollama Service After=network-online.target [Service] Type=simple User=$USER ExecStart=/usr/bin/ollama serve Restart=always RestartSec=3 [Install] WantedBy=default.target EOF sudo systemctl daemon-reload sudo systemctl enable ollama sudo systemctl start ollama

第四步：安装 PostgreSQL（可选但强烈推荐）
如前所述，为避免 SQLite 并发锁，直接上 PostgreSQL：

# 使用 Docker 快速启动（无需配置用户权限） docker run -d \ --name openclaw-pg \ -e POSTGRES_PASSWORD=openclaw2024 \ -e POSTGRES_DB=openclaw_db \ -p 5432:5432 \ -v $HOME/openclaw-pg-data:/var/lib/postgresql/data \ -d postgres:15-alpine

等待 10 秒，验证连接：

sudo apt install postgresql-client -y psql -h localhost -U postgres -d openclaw_db -W # 密码输入 openclaw2024 # 进入后输入 \q 退出

3.2 获取与配置 OpenClaw 源码

OpenClaw 目前没有官方发布的稳定版 tar.gz 包，必须从 GitHub 仓库克隆。但注意：不要克隆主分支（main）。主分支是开发版，API 可能变动，且feishu_adapter.py的飞书事件处理逻辑尚未完善。社区公认最稳定的版本是v0.8.3tag，它经过多个团队生产环境验证。操作如下：

cd ~ git clone https://github.com/openclaw/openclaw.git cd openclaw git checkout v0.8.3

接下来是核心配置环节。OpenClaw 的配置分散在多个文件，必须按顺序修改：

1. 修改core/config.yaml—— LLM 与数据库配置
这是最关键的配置文件。用你喜欢的编辑器（如nano）打开：

nano core/config.yaml

找到并修改以下部分：

# LLM 配置：指向本地 Ollama llm_provider: ollama ollama: host: http://localhost:11434 model: qwen:2.5-coder # 必须和你 pull 的模型名完全一致 timeout: 300 # 增加超时，避免大 Prompt 卡死 # 数据库存储：切换到 PostgreSQL database: type: postgresql url: postgresql://postgres:openclaw2024@localhost:5432/openclaw_db # 如果用 SQLite，这里保持默认即可，但不推荐 # 日志级别：调为 DEBUG，方便排查飞书集成问题 logging: level: DEBUG

注意：model字段必须和ollama list输出的第一列完全一致，包括大小写和冒号。qwen:2.5-coder和qwen:2.5-CODER是两个不同模型。

2. 修改adapters/feishu_adapter.py—— 飞书认证与回调
这是接入飞书的核心。打开文件：

nano adapters/feishu_adapter.py

找到class FeishuAdapter下的__init__方法，修改self.app_id和self.app_secret：

def __init__(self): self.app_id = "cli_xxxxxxx" # 替换为你飞书开放平台的 App ID self.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxx" # 替换为你飞书开放平台的 App Secret self.verification_token = "your_verification_token_here" # 飞书后台设置的 Verification Token self.encrypt_key = "your_encrypt_key_here" # 飞书后台设置的 Encrypt Key（可为空，但必须存在） # ... 其他代码保持不变

关键点：Verification Token和Encrypt Key必须在飞书开放平台的“机器人”设置页里手动创建并复制。它们是飞书用来验证回调请求合法性的密钥，不是 App Secret。很多人混淆这两者，导致签名验证失败。

3. 创建飞书机器人并获取凭证
登录 飞书开放平台 → “开发者后台” → “我的应用” → “创建应用” → 类型选“机器人” → 填写应用名称（如“OpenClaw 产品经理助手”）→ 创建。
进入应用详情页：

• 复制App ID和App Secret（在“凭证与基础信息”页）；
• 在“功能与权限” → “机器人” → “配置机器人”页，点击“启用”，然后设置：
  • Verification Token：自定义一个 32 位随机字符串（如feishu_openclaw_2024_token）；
  • Encrypt Key：同样自定义一个 32 位字符串（如feishu_openclaw_2024_encrypt）；
  • 事件订阅：勾选im.message.receive、im.message.send、contact.user.read、bitable.base.read；
  • IP 白名单：填入你服务器的公网 IP（curl ifconfig.me获取）；
• 最后点击“发布应用”。

3.3 启动 OpenClaw 并配置飞书 Webhook 回调

配置完成后，启动 OpenClaw：

cd ~/openclaw pip3 install -r requirements.txt python3 main.py

如果一切顺利，你会看到类似日志：

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) INFO: Started reloader process [12345] INFO: Started server process [12346] INFO: Waiting for application startup. DEBUG: Feishu adapter initialized with app_id: cli_xxxxxxx INFO: Application startup complete.

此时 OpenClaw 的 Web 服务已启动在http://localhost:8000，但飞书还无法访问它，因为这是本地地址。你需要将飞书的回调请求路由到这个地址。

方案一：直接暴露本地端口（仅限测试）
如果你的服务器有固定公网 IP 且防火墙允许，可在飞书后台“事件订阅”页填写：

• Request URL:https://你的公网IP:8000/feishu/webhook
• 加密方式:None（先不启用加密，简化调试）

但绝大多数家庭宽带和群晖 NAS 没有固定公网 IP，且 8000 端口常被运营商封锁。这时必须用方案二。

方案二：Cloudflare Tunnel（推荐，免费且稳定）
这是目前最可靠的反向代理方案。注册 Cloudflare 账号 → 添加你的域名（如claw.yourdomain.com）→ 按指引配置 DNS → 安装cloudflared：

# Ubuntu 安装 curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared chmod +x cloudflared sudo mv cloudflared /usr/local/bin

登录并创建隧道：

cloudflared tunnel login cloudflared tunnel create openclaw-tunnel # 复制生成的 tunnel ID cloudflared tunnel route dns openclaw-tunnel claw.yourdomain.com

创建配置文件~/.cloudflared/config.yml：

tunnel: your-tunnel-id-here credentials-file: /home/youruser/.cloudflared/your-tunnel-id.json ingress: - hostname: claw.yourdomain.com service: http://localhost:8000 originRequest: httpHostHeader: claw.yourdomain.com - service: http_status:404

启动隧道：

cloudflared tunnel run openclaw-tunnel

此时，访问https://claw.yourdomain.com/feishu/webhook应返回 405 Method Not Allowed（因为是 POST 接口），证明隧道通了。

最后一步：在飞书后台填写 Webhook
回到飞书开放平台 → “事件订阅”页：

• Request URL:https://claw.yourdomain.com/feishu/webhook
• Verification Token: 和feishu_adapter.py里填的一致
• Encrypt Key: 和feishu_adapter.py里填的一致
• 点击“验证”按钮。如果 OpenClaw 日志里出现DEBUG: Feishu webhook verification success，说明集成成功！

3.4 飞书端配置：让机器人真正“活”起来

Webhook 验证通过只是第一步。要让 OpenClaw 在飞书里发挥作用，还需完成三个飞书端操作：

1. 将机器人添加到目标群组
打开飞书客户端 → 进入你要部署机器人的群（如“产品需求评审群”）→ 点击右上角“...” → “添加机器人” → 搜索你创建的应用名（如“OpenClaw 产品经理助手”）→ 添加。添加后，机器人会自动发送欢迎消息：“我是 OpenClaw，可以帮你生成 PRD、分析用户反馈、查询需求状态...”。

2. 配置多维表格权限（关键！）
OpenClaw 的table_query.pySkill 需要读取飞书多维表格。必须手动授权：

• 在飞书多维表格中，打开你的“需求池”表格 → 右上角“...” → “分享” → “高级设置” → “添加成员” → 输入机器人名称（如OpenClaw 产品经理助手）→ 权限设为“可编辑”（只读权限不足以让 OpenClaw 写入执行日志）。
• 如果表格在“知识库”里，还需在知识库设置中，将机器人添加为“成员”。

3. 测试首个交互：@机器人 + 命令
在群聊中，输入：

@OpenClaw 生成本周需求周报

如果 OpenClaw 正常工作，它会在 10-30 秒内（取决于模型响应速度）回复一张富文本卡片，包含：

• 本周新增需求数量、各模块分布饼图（用 ASCII 字符模拟）；
• 三条高优先级需求的简要描述；
• 一个“查看详情”按钮，点击后跳转到飞书多维表格对应视图。

如果没反应，立刻检查 OpenClaw 日志：

• DEBUG级日志会显示Received message from user_xxx in chat_xxx；
• 如果没这行，说明飞书回调没到达服务器，检查 Cloudflare Tunnel 日志或防火墙；
• 如果有这行但没后续，检查ollama logs是否有错误，或core/config.yaml的model名称是否拼错。

4. 常见问题与独家排查技巧实录

4.1 飞书机器人“已添加但不回复”：五步定位法

这是搜索热词“机器人不回信息”对应的最高频问题。我整理了一套现场排查清单，按顺序执行，95% 的情况能在 5 分钟内定位：

Step 1：确认 OpenClaw 进程是否存活

ps aux | grep "python3 main.py" # 如果没有输出，说明进程已崩溃。查看最近日志： tail -n 50 ~/openclaw/logs/app.log

常见崩溃原因：Ollama 服务未启动、PostgreSQL 连接失败、feishu_adapter.py语法错误。日志里通常有Traceback。

Step 2：检查飞书回调是否到达服务器
在 OpenClaw 启动时，加上-v参数开启详细日志：

python3 main.py -v

然后在飞书群中发一条@机器人 测试。观察终端输出：

• 如果第一行是INFO: 127.0.0.1:xxxxx - "POST /feishu/webhook HTTP/1.1" 200 OK，说明请求已到达；
• 如果没有这行，说明飞书回调被拦截，检查 Cloudflare Tunnel 状态（systemctl status cloudflared）或公网 IP 是否变更。

Step 3：验证飞书签名（Signature）
这是最隐蔽的失败点。在adapters/feishu_adapter.py的verify_signature方法里，临时加一行 debug：

logger.debug(f"Calculated signature: {calculated_signature}") logger.debug(f"Received signature: {received_signature}")

重启 OpenClaw，再发测试消息。如果两行 signature 不一致，100% 是App Secret填错了，或者飞书后台的App Secret被重置过（重置后旧 Secret 失效）。

Step 4：检查 Ollama 模型响应
即使飞书回调成功，如果 Ollama 返回错误，OpenClaw 也会静默失败。在core/llm/ollama_client.py的chat方法里，加日志：

logger.debug(f"Ollama request: {payload}") logger.debug(f"Ollama response status: {response.status_code}") logger.debug(f"Ollama response body: {response.text}")

常见错误：404 Not Found（模型名不存在）、500 Internal Error（模型加载失败）、timeout（模型响应太慢）。解决方案：ollama list确认模型存在；ollama ps确认模型正在运行；在core/config.yaml中增加timeout: 600。

Step 5：检查 Skill 执行权限
OpenClaw 的skills/目录下所有.py文件必须有可执行权限：

chmod +x skills/*.py

否则Permission denied错误会出现在日志里，但不会直接提示。我曾在一个客户的环境里，因为skills/generate_prd.py没加执行权限，导致所有 PRD 生成命令都失败，日志只显示Failed to execute skill generate_prd，花了 2 小时才定位到。

4.2 “OpenClaw 为什么会延迟？”：性能瓶颈与优化方案

搜索热词中“openclaw 为什么会延迟”直指用户体验痛点。延迟不是单一原因，而是三层叠加：

第一层：网络延迟（最易解决）

• 现象：从发消息到机器人回复，耗时 >15 秒，但日志显示Received message和Sending response时间戳只差 2 秒。
• 原因：飞书消息从客户端 → 飞书服务器 → Cloudflare Tunnel → 你的服务器 → OpenClaw → Ollama → OpenClaw → 飞书服务器 → 客户端，全程至少 6 跳。其中 Cloudflare Tunnel 是最大变数。
• 优化：将 Cloudflare Tunnel 的protocol改为http2（在config.yml中添加protocol: http2），实测降低首字节时间 300ms；或直接用国内 CDN（如又拍云）做反向代理，延迟可压到 800ms 以内。

第二层：模型推理延迟（核心瓶颈）

• 现象：日志显示Ollama request到Ollama response耗时 >10 秒。
• 原因：7B 模型在 CPU 上推理速度慢，尤其处理长上下文（如 5000 字 PRD）。
• 优化：
  1. 量化模型：用ollama run qwen:2.5-coder-q4_k_m（Q4_K_M 量化版），比 FP16 快 2.3 倍；
  2. 限制上下文长度：在core/config.yaml中添加ollama.context_length: 2048，避免 Ollama 加载过长 history；
  3. 启用 GPU 加速（如果有 NVIDIA 显卡）：ollama run --gpus all qwen:2.5-coder，速度提升 5-8 倍。

第三层：Skill 逻辑延迟（常被忽视）

• 现象：日志显示Running skill generate_prd到Skill generate_prd completed耗时 >5 秒，但 Ollama 响应很快。
• 原因：skills/generate_prd.py里可能有同步 I/O 操作，比如requests.get()拉取外部文档，或subprocess.run()执行慢命令。
• 优化：将所有外部调用改为异步（asyncio+aiohttp），或加超时（timeout=5）。我在skills/table_query.py里加了timeout=3参数，避免飞书多维表格 API 偶尔抖动导致整个 Skill 卡死。

4.3 群晖 NAS 用户专属避坑指南

搜索热词里“群晖 docker openclaw 下载哪个”说明大量用户想在群晖上部署。但群晖的 Docker 和标准 Linux 有差异，必须注意：

坑一：Docker 网络模式
群晖 Docker 默认用bridge模式，容器内localhost指向容器自身，无法访问宿主机的 Ollama（运行在群晖 DSM 上）。解决方案：

• 在 Docker 创建容器时，网络模式选host；
• 或者，Ollama 也用 Docker 运行，并用--network host模式，让两个容器共享宿主机网络。

坑二：文件权限
群晖的共享文件夹默认权限是755，但 OpenClaw 需要写日志和数据库文件。在 Docker 设置里，卷映射的“权限”必须勾选“启用读写权限”。

坑三：Python 环境冲突
群晖 DSM 自带 Python，但版本老旧（3.8）。不要在群晖 SSH 里用pip3 install，而要用 Docker 容器隔离环境。推荐用python:3.10-slim基础镜像构建自定义镜像：

FROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["python", "main.py"]

然后在群晖 Docker 中导入此镜像。

4.4 安全加固：生产环境必须做的三件事

OpenClaw 本地部署虽