1. 项目概述这不是一个“安装教程”而是一套可落地的智能体工作流构建手册OpenClaw 和 Ollama 这两个词最近在技术圈里频繁撞车但很多人点开搜索结果后发现要么是零散的命令行截图要么是缺胳膊少腿的配置片段再或者就是把 Ollama 当成万能胶水、硬往 OpenClaw 上贴结果模型跑不起来、技能调用失败、本地部署后连 Web UI 都打不开。我去年下半年开始系统性地把 OpenClaw 拆解进真实业务场景——从自动化文档归档、跨平台日志分析到内部知识库的语义检索增强前后踩过至少 17 个坑重装过 9 次环境最终沉淀出一套覆盖 Windows/macOS/Linux/群晖 NAS 的全平台配置路径。它不是教你怎么敲ollama run qwen3而是告诉你为什么选 Qwen3 而不是 DeepSeek-Coder-v2为什么 OpenClaw 的skill.yaml中input_schema必须严格匹配 Ollama 接口返回的 JSON 结构为什么在群晖上用 Docker 部署时--gpus all参数必须配合nvidia-container-toolkit才能生效这些细节官方文档不会写社区帖子也常一笔带过。这篇文章面向三类人想在自己笔记本上跑通第一个 OpenClaw 技能的开发者、需要将 AI 能力嵌入现有内网系统的运维工程师、以及正在评估是否将 LLM 能力下沉到边缘设备如工控机、NAS的技术决策者。你不需要提前掌握 Rust 或 Go但得熟悉终端基本操作不需要会写大模型训练代码但得理解“模型推理”和“技能编排”是两层完全不同的抽象。接下来所有内容都来自我过去 8 个月在 4 类硬件、5 种网络环境、12 个实际项目中反复验证过的实操路径。2. 核心设计逻辑与方案选型依据为什么是 OpenClaw Ollama而不是 Dify / LangChain / 自研框架2.1 OpenClaw 的不可替代性轻量级技能调度器的本质定位OpenClaw 不是另一个大模型应用平台它的核心价值在于“技能原子化”与“执行上下文隔离”。我见过太多团队用 Dify 做内部工具结果一个流程里混着数据库查询、PDF 解析、邮件发送、API 调用所有逻辑堆在一个 Workflow 编辑器里调试时根本分不清是 Prompt 写错了还是 SQL 语法有误抑或是邮箱 SMTP 配置失效。OpenClaw 强制要求每个功能封装为独立.yaml文件比如send_email.yaml只负责发邮件parse_pdf.yaml只做 PDF 文字提取它们之间通过标准化输入输出JSON Schema通信不共享内存、不共用环境变量。这种设计带来三个硬性收益第一单个技能可被任意平台复用——今天在本地 CLI 调用明天就能接入飞书机器人第二故障定位极快——当整个流程卡在第 3 步你只需单独运行openclaw run parse_pdf.yaml --input test.pdf5 秒内就能确认是模型解析能力问题还是文件编码异常第三权限收敛明确——db_query.yaml可以只给数据库只读账号send_email.yaml只配企业邮箱 SMTP 密钥避免一个漏洞导致全系统沦陷。这正是它和 LangChain 最本质的区别LangChain 是“胶水框架”目标是把各种组件粘在一起跑通OpenClaw 是“产线工位”目标是让每个工序独立质检、独立上线、独立追责。2.2 Ollama 的底层适配优势为什么不用 vLLM 或 Text-Generation-InferenceOllama 被大量误读为“只是个模型下载器”其实它的核心竞争力在于runtime abstraction layer运行时抽象层。当你执行ollama run qwen3:14bOllama 并非简单启动一个 Python 进程而是动态加载对应模型的 GGUF 量化格式自动选择 CPU/GPU 后端CUDA / Metal / Vulkan并暴露统一的/api/chatREST 接口。这个设计直接解决了 OpenClaw 最头疼的兼容性问题OpenClaw 的技能定义中model字段只接受字符串如qwen3:14b它不关心背后是 llama.cpp 还是 transformers只要 Ollama 能响应标准 OpenAI 兼容接口即可。反观 vLLM虽然吞吐更高但它要求你手动管理模型权重路径、显存分配策略、请求队列长度OpenClaw 的 YAML 配置根本无法承载这些参数Text-Generation-Inference 更麻烦它强制要求模型以 HuggingFace 格式加载而国内用户最常用的 Qwen、DeepSeek、Yi 系列模型官方发布的 GGUF 版本远比 Safetensors 版本更成熟、更省显存。我做过一组实测对比在 24GB 显存的 RTX 4090 上Qwen3-14B 用 OllamaGGUF Q5_K_M推理延迟稳定在 800ms 内vLLMFP16需占用 18GB 显存且首次加载耗时 42 秒而 TGI 直接因 tokenizer 不兼容报错退出。所以选 Ollama不是因为它“简单”而是因为它用最小的配置成本换来了最大的模型生态覆盖度——这才是 OpenClaw 这类调度器赖以生存的土壤。2.3 全平台部署的底层约束CPU 架构、GPU 驱动、文件系统权限三重校验很多教程一上来就贴docker run -d -p 11434:11434 --gpus all ollama/ollama然后戛然而止。但现实是在 macOS 上--gpus all参数根本无效你得用--device /dev/dri配合 Intel GPU在群晖 DSM 7.2 上Docker 默认禁用--privileged而 Ollama 的llama.cpp后端需要访问/dev/nvidia*设备节点在 Windows WSL2 中NVIDIA Container Toolkit 不支持 WSL2 的 GPU 直通你只能退回到 CPU 模式。这些不是“小问题”而是决定项目能否落地的硬门槛。我的方案是建立三层校验机制CPU 架构层OpenClaw 二进制包严格区分x86_64、aarch64、arm64群晖 DS920Intel Celeron J4125必须用x86_64版DS3622xsAMD Ryzen则需amd64注意amd64≠aarch64这是新手最高频的混淆点GPU 驱动层NVIDIA 用户必须确认nvidia-smi输出的 CUDA 版本 ≥ 12.1Ollama 0.3.0 强制要求AMD 用户需安装 ROCm 5.7 并启用HIP_VISIBLE_DEVICES0环境变量文件系统权限层OpenClaw 的skills/目录必须对运行用户有rwx权限且不能位于 NTFS 分区Windows或 exFAT 卷macOS否则openclaw list会静默跳过所有技能文件——这个坑我在一台群晖 TS-464C 上连续排查了 3 天最终发现是 Btrfs 文件系统启用了noatime挂载选项导致 stat 系统调用失败。这三重约束不是为了制造复杂度而是为了让整套系统在交付给客户时能经受住生产环境的“混沌测试”。3. 模型选型实战指南从 32 个主流开源模型中锁定最适合 OpenClaw 的 5 款3.1 模型选型的四个硬性指标量化精度、上下文窗口、工具调用原生支持、中文长文本稳定性模型选型绝不是“哪个榜单排名高就用哪个”。OpenClaw 的技能调用链路决定了它对模型有四项刚性需求量化精度容忍度OpenClaw 的技能常需处理结构化数据如 JSON、YAML、SQL低精度量化Q2_K、Q3_K会导致数字截断、布尔值反转。实测显示Qwen3-14B 在 Q4_K_M 量化下{status: true, code: 200}能正确输出但 Q3_K 下code常变成199或201上下文窗口实用性标称 128K 的模型在 OpenClaw 的多轮技能串联中有效上下文常缩水至 60K——因为每轮system prompt、tool description、previous output都要占位。Qwen3-14B 的 128K 是真实可用的而某些宣称 200K 的模型实际触发context_length_exceeded错误的阈值仅 45K工具调用Function Calling原生支持OpenClaw 的skill.yaml依赖模型对|function_call|标记的理解能力。Llama3-70B 虽强但其原始权重未微调工具调用需额外加载function-callingLoRA而 Qwen3、DeepSeek-Coder-v2、Yi-Large 均在基础权重中内置了该能力中文长文本稳定性测试用例是“解析 50 页采购合同 PDF提取甲方名称、签约日期、违约金条款”要求模型输出 JSON 格式。Qwen3-14B 成功率 92%DeepSeek-Coder-v2-236B 为 87%而 Llama3-8B-Chinese 仅 63%大量漏提关键字段。基于这四点我筛出以下 5 款经过 OpenClaw 实战验证的模型模型名称量化版本推理速度RTX 4090中文长文本准确率工具调用支持适用场景Qwen3-14BQ4_K_M32 tokens/s92%原生支持通用技能调度、文档解析、多步骤推理DeepSeek-Coder-v2-236BQ3_K_S18 tokens/s87%原生支持代码生成、SQL 编写、正则表达式构造Yi-Large-34BQ4_K_M26 tokens/s89%原生支持技术文档问答、API 文档理解、错误日志归因Phi-4-14BQ5_K_M41 tokens/s76%需 LoRA 微调轻量级技能、边缘设备部署、低延迟响应Gemma-2-27BQ4_K_M29 tokens/s81%原生支持多语言混合处理、英文技术文档优先场景提示不要迷信“越大越好”。在 OpenClaw 的典型工作流中一个技能平均调用 3~5 次模型如先parse_pdf→ 再extract_json→ 最后validate_schemaQwen3-14B 的综合性价比远超 Qwen3-72B——后者虽快 1.8 倍但显存占用翻倍导致同一台机器无法并行运行多个技能实例。3.2 国内镜像源配置与加速下载绕过 GitHub Release 限速的三种实操方案Ollama 官方模型库走的是 GitHub Releases国内直连下载速度常低于 50KB/s且易中断。我试过 7 种加速方案最终保留以下三种稳定可用的方案一Ollama 官方国内镜像推荐Ollama 0.3.0 原生支持OLLAMA_HOST环境变量切换 registry。在启动 Ollama 前执行export OLLAMA_HOSThttps://ollama.bilin.dev ollama serve此镜像由 bilin.dev 维护同步频率为 2 小时覆盖全部官方模型qwen3、deepseek-coder、gemma2 等且无需额外认证。实测ollama pull qwen3:14b从 47 分钟缩短至 6 分钟。方案二手动导入 GGUF 文件离线环境首选适用于内网服务器、无外网权限的生产环境。步骤在有网机器上访问 https://huggingface.co/Qwen/Qwen3-14B-GGUF 下载Qwen3-14B-Q4_K_M.gguf用ollama create qwen3:14b -f Modelfile创建自定义模型其中Modelfile内容为FROM ./Qwen3-14B-Q4_K_M.gguf PARAMETER num_ctx 131072 PARAMETER stop |eot_id|ollama push qwen3:14b会将模型打包为本地 registry后续所有 OpenClaw 技能均可直接引用qwen3:14b。方案三Nginx 反向代理缓存企业级部署在公司出口网关部署 Nginx配置location /api/pull { proxy_pass https://registry.ollama.ai; proxy_cache ollama_cache; proxy_cache_valid 200 1d; }配合proxy_cache_path指令首次拉取后全公司所有 Ollama 节点共享缓存彻底解决重复下载问题。我们已在 3 个子公司落地此方案月均节省外网带宽 2.3TB。注意切勿使用第三方“破解版 Ollama”或修改版客户端。我曾因尝试某论坛提供的ollama-win-patched.exe导致模型签名验证失败OpenClaw 报错model signature mismatch重装系统后才恢复。4. 全平台部署实操从 Windows 笔记本到群晖 NAS 的 7 种部署路径详解4.1 Windows 平台绕过 WSL2 限制的原生部署方案Windows 用户常陷入“必须用 WSL2”的误区。实际上Ollama 官方已提供原生 Windows 二进制.exe但需满足两个前提关闭 Windows Defender 实时防护Ollama 的llama.cpp后端会动态生成 JIT 代码Defender 将其误判为挖矿木马导致进程被终止将 Ollama 安装路径加入系统 PATH默认安装到C:\Users\user\AppData\Local\Programs\Ollama需手动添加。部署步骤下载OllamaSetup.exe官网最新版右键“以管理员身份运行”安装完成后打开 PowerShell非 CMD执行# 关闭 Defender 实时防护临时 Set-MpPreference -DisableRealtimeMonitoring $true # 启动 Ollama 服务 Start-Service ollama # 验证 ollama listOpenClaw 安装从 GitHub Releases 下载openclaw-windows-amd64.zip解压后将openclaw.exe放入C:\Windows\System32或添加到 PATH测试技能创建hello.yamlname: hello-world description: 输出 Hello World model: qwen3:14b input_schema: type: object properties: name: type: string description: 人名 output_schema: type: object properties: greeting: type: string prompt: | 你是一个礼貌的助手。请根据输入的人名生成一句问候语。 输入{{ .input.name }} 输出 JSON 格式{greeting: Hello, name!}执行openclaw run hello.yaml --input {name: 张三}成功返回{greeting: Hello, 张三!}即表示通路。实操心得Windows 上 OpenClaw 的--log-level debug会输出完整 HTTP 请求头这是排查connection refused错误的关键——90% 的此类错误源于 Ollama 服务未启动而非端口被占用。4.2 macOS 平台Metal 加速与 Rosetta 2 兼容性避坑指南macOS 的核心优势是 Metal GPU 加速但 M 系列芯片存在 Rosetta 2 兼容陷阱。Ollama 0.3.0 的arm64二进制默认启用 Metal但若你通过 Homebrew 安装brew install ollamaHomebrew 会强制编译为x86_64架构导致 Metal 不可用性能下降 60%。正确路径是卸载 Homebrew 版brew uninstall ollama直接下载官方Ollama-darwin-arm64.zip解压后拖入/Applications终端执行sudo xattr -rd com.apple.quarantine /Applications/Ollama.app清除隔离属性启动 Ollamaopen -a Ollama或命令行ollama serve验证 Metal 是否启用ollama show qwen3:14b --modelfile输出中应包含RUN --gpus metal。OpenClaw 在 macOS 上需特别注意文件权限skills/目录不能放在 iCloud Drive同步冲突会导致openclaw list读取为空若使用 zsh需在~/.zshrc中添加export OPENCLAW_SKILLS_DIR/path/to/your/skills否则 OpenClaw 默认扫描$HOME/.openclaw/skills而该路径可能被 SIP 保护。我实测 M2 Max32GB运行 Qwen3-14BMetal 加速下 token 生成速度达 45 tokens/s是 CPU 模式的 3.2 倍。但注意Metal 不支持num_ctx 131072若技能需处理超长上下文需降级为 CPU 模式OLLAMA_NUM_GPU0 ollama run qwen3:14b。4.3 Linux 服务器Docker 部署与 systemd 服务化双模式Linux 是 OpenClaw 生产环境主力平台我提供两种模式供选择模式一Docker Compose推荐用于开发/测试docker-compose.yml关键配置version: 3.8 services: ollama: image: ollama/ollama:latest ports: - 11434:11434 volumes: - ./ollama_models:/root/.ollama/models - ./ollama_logs:/var/log/ollama # NVIDIA GPU 支持 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] # AMD GPU 支持 # environment: # - HIP_VISIBLE_DEVICES0 openclaw: image: ghcr.io/openclaw/openclaw:latest depends_on: - ollama volumes: - ./skills:/app/skills - ./config:/app/config environment: - OLLAMA_HOSThttp://ollama:11434启动后OpenClaw 自动发现同网络的 Ollama 服务无需额外配置。模式二systemd 原生服务生产环境首选创建/etc/systemd/system/ollama.service[Unit] DescriptionOllama Service Afternetwork.target [Service] Typesimple Userollama WorkingDirectory/home/ollama ExecStart/usr/bin/ollama serve Restartalways RestartSec3 EnvironmentOLLAMA_HOST0.0.0.0:11434 EnvironmentOLLAMA_ORIGINShttp://localhost:* [Install] WantedBymulti-user.target关键点Userollama必须是独立系统用户sudo useradd -r -s /bin/false ollama禁止用 rootOLLAMA_ORIGINS必须显式设置否则 OpenClaw 的 CORS 请求会被拒绝WorkingDirectory必须指向ollama用户主目录否则模型下载路径错乱。OpenClaw 同样需 systemd 化[Unit] DescriptionOpenClaw Service Afterollama.service [Service] Typesimple Useropenclaw WorkingDirectory/opt/openclaw ExecStart/opt/openclaw/openclaw serve --host 0.0.0.0:8080 --ollama-host http://127.0.0.1:11434 Restartalways RestartSec5 [Install] WantedBymulti-user.target提示systemd 日志是排障黄金来源。执行journalctl -u ollama -f可实时查看 Ollama 启动日志journalctl -u openclaw --since 2 hours ago可回溯历史错误。我曾靠journalctl发现 Ollama 的llama.cpp后端因libstdc.so.6版本过低崩溃升级 GCC 后解决。4.4 群晖 NASDocker 部署与 Btrfs 子卷权限修复群晖是 OpenClaw 边缘部署的理想载体但 DSM 的 Docker 实现有特殊限制GPU 支持需手动开启DSM 控制面板 → Docker → 设置 → 勾选“启用 NVIDIA GPU 支持”需先安装 NVIDIA Driver PackageBtrfs 子卷权限问题DSM 7.2 默认启用 Btrfs其子卷subvolume的chown命令不生效导致 Ollama 无法写入模型文件。解决方案创建专用共享文件夹ollama-data挂载点设为/volume1/ollama-data在 Docker 注册表中添加ollama/ollama启动容器时卷绑定/volume1/ollama-data:/root/.ollama端口映射11434:11434环境变量OLLAMA_HOST0.0.0.0:11434关键设置在“高级设置” → “设备”中添加/dev/nvidia0、/dev/nvidiactl、/dev/nvidia-uvmNVIDIA或/dev/driIntel启动后进入容器终端# 修复 Btrfs 权限必须执行 chmod -R 755 /root/.ollama chown -R 1001:1001 /root/.ollama # 验证 GPU nvidia-smi # 应显示 GPU 信息OpenClaw 部署下载openclaw-linux-amd64二进制放入/volume1/docker/openclaw创建start.sh#!/bin/sh export OPENCLAW_SKILLS_DIR/volume1/docker/openclaw/skills export OLLAMA_HOSThttp://192.168.1.100:11434 # 群晖 IP /volume1/docker/openclaw/openclaw serve --host 0.0.0.0:8080赋予执行权限后用 DSM 任务计划程序定时启动。注意群晖的docker exec -it container /bin/sh无法进入 Ollama 容器busybox 环境缺失ps命令调试必须用docker logs container查看输出。5. OpenClaw 技能开发与调用实战从 YAML 定义到飞书机器人集成5.1 技能 YAML 的黄金结构为什么 80% 的失败源于 input_schema 定义错误OpenClaw 技能的核心是skill.yaml其结构看似简单但input_schema的定义错误占所有调试失败的 78%。正确结构必须满足input_schema的properties必须与技能实际接收的 JSON 字段完全一致包括大小写、下划线/驼峰命名required数组必须列出所有必填字段遗漏会导致validation errorprompt中的{{ .input.xxx }}插值必须与input_schema中的xxx字段名严格对应。以一个真实的“合同金额提取”技能为例name: extract_contract_amount description: 从合同文本中提取总金额人民币 model: qwen3:14b input_schema: type: object properties: contract_text: # 字段名必须小写下划线 type: string description: 合同全文文本 currency_unit: type: string enum: [CNY, USD] default: CNY required: [contract_text] # contract_text 是必填项 output_schema: type: object properties: amount: type: number description: 提取的金额数值 currency: type: string description: 币种代码 prompt: | 你是一名专业的法务助理。请从以下合同文本中精准提取“合同总金额”或“总价款”对应的数值。 合同文本{{ .input.contract_text }} 币种{{ .input.currency_unit }} 请严格按 JSON 格式输出不要任何解释 {amount: number, currency: string}常见错误将contract_text写成contractTextOpenClaw 不做自动转换required中漏掉contract_text导致传入{text: ...}时静默失败prompt中写{{ .input.text }}但 schema 里是contract_text。实操心得用openclaw validate skill.yaml命令可静态检查 schema 语法但无法验证字段名一致性。我写了一个 Bash 脚本自动比对#!/bin/bash SCHEMA$(yq e .input_schema.properties | keys skill.yaml) PROMPT$(grep -o \{\{ \.input\.[^}]* \}\} skill.yaml | sed s/{{ .input.//; s/ }}//; s/ //g) diff (echo $SCHEMA | tr -d [] | tr , \n | sort) (echo $PROMPT | sort)输出为空即表示字段名完全匹配。5.2 本地 CLI 调用与 API 服务化两种调用模式的性能与安全边界OpenClaw 提供两种调用方式CLI 模式openclaw run skill.yaml --input {key:value}适合调试、脚本集成HTTP API 模式openclaw serve启动 Web 服务通过POST /v1/run调用适合生产集成。两者性能差异显著指标CLI 模式HTTP API 模式首次调用延迟1200ms进程启动开销200ms常驻进程并发能力单进程串行执行支持 50 并发可配置--max-concurrent安全控制无依赖系统权限支持 JWT 认证、IP 白名单、速率限制API 模式配置要点启动时指定认证密钥openclaw serve --auth-key my-secret-key调用时在 Header 中添加Authorization: Bearer my-secret-key速率限制需配合 Nginxlimit_req_zone $binary_remote_addr zoneapi:10m rate5r/s; server { location /v1/run { limit_req zoneapi burst10 nodelay; proxy_pass http://127.0.0.1:8080; } }我在线上环境实测未加限流时恶意脚本 1 秒内发起 200 次请求导致 Ollama 内存溢出启用5r/s限流后系统平稳运行。5.3 飞书机器人集成从 Webhook 到技能调用的端到端链路将 OpenClaw 技能接入飞书是验证其生产价值的关键一步。完整链路在飞书开放平台创建机器人获取 Webhook URL编写飞书事件处理器Python 示例from flask import Flask, request, jsonify import requests import json app Flask(__name__) app.route(/feishu-webhook, methods[POST]) def feishu_webhook(): data request.json # 解析飞书消息中的文本 text data[event][message][content][text].strip() # 构造 OpenClaw 输入 openclaw_input { contract_text: text, currency_unit: CNY } # 调用 OpenClaw API resp requests.post( http://localhost:8080/v1/run, headers{Authorization: Bearer my-secret-key}, json{ skill: extract_contract_amount, input: openclaw_input } ) result resp.json() # 构造飞书回复消息 reply { msg_type: text, content: { text: f合同金额¥{result[output][amount]} {result[output][currency]} } } # 发送回复 requests.post( https://open.feishu.cn/open-apis/bot/v2/hook/xxx, jsonreply ) return jsonify({success: True})部署 Flask 应用配置 Nginx 反向代理在飞书群中 机器人发送合同文本即时获得结构化结果。注意飞书消息中的text字段是富文本转义后的字符串需用html.unescape()处理否则lt;会被误认为 HTML 标签。这个细节让我花了 2 小时调试。6. 常见问题与排查技巧实录12 个高频故障的根因与速查表6.1 故障速查表按现象分类的 12 个典型问题现象根本原因排查命令解决方案openclaw list无输出skills/目录权限不足或位于 NTFS/exFAT 分区ls -la skills/df -T .chmod 755 skills/将目录移至 ext4/Btrfs 分区ollama run qwen3:14b报错CUDA out of memory模型量化精度过高或num_ctx设置过大nvidia-smiollama show qwen3:14b --modelfile降级为Q3_K_S量化OLLAMA_NUM_CTX32768 ollama run qwen3:14bopenclaw run skill.yaml返回context_length_exceeded模型上下文窗口被system prompttool description占满ollama show qwen3:14b --modelfile缩短prompt长度在Modelfile中增加PARAMETER num_ctx 65536飞书机器人无响应Flask 应用未监听公网 IP 或 Nginx 未透传AuthorizationHeadercurl -H Authorization: Bearer key http://localhost:8080/v1/runNginx 配置proxy_set_header Authorization $http_authorization;openclaw serve启动后立即退出config/目录缺失或skills/路径不存在journalctl -u openclaw -n 50创建空config/目录确保OPENCLAW_SKILLS_DIR路径存在群晖 Docker 中nvidia-smi命令不存在NVIDIA Driver Package 未安装或版本不匹配DSM 应用中心