1. 这不是又一个“一键部署”教程OpenClaw Ollama 本地AI助理的真实落地场景你搜“OpenClaw 安装”“Ollama 下载太慢了”“本地部署大语言模型”页面刷出来的全是三分钟速成、截图配命令、最后加一句“搞定”。我试过不下二十个有十七个在第三步就卡死——不是模型加载失败就是前端白屏再或者技能调用时返回一串看不懂的 JSON 错误。这不是你的问题是绝大多数教程根本没告诉你OpenClaw 不是一个开箱即用的 App它是一套可编程的 AI 工作流胶水层Ollama 也不是个“本地 ChatGPT”它本质是个轻量级模型运行时runtime和 Docker 的关系就像 Node.js 和 npm 的关系——你得懂它怎么加载、怎么调度、怎么和外部系统握手才能让它真正为你干活。我过去两年在三个不同规模的团队里落地过 OpenClaw Ollama 组合一个做内部知识库问答的 SaaS 创业公司一个需要离线处理客户合同的律所技术组还有一个高校实验室要求所有模型推理必须全程不联网。我们踩过的坑90% 都集中在四个地方镜像源失效导致 Ollama 拉模型超时、OpenClaw 技能配置里模型地址写错协议头、Ubuntu 系统下 GPU 驱动与 llama.cpp 后端冲突、以及最隐蔽的——前端请求被浏览器同源策略静默拦截但控制台连报错都不打。这些细节没有一篇“保姆级教程”会提因为它们不发生在安装命令里而发生在你第一次点击“发送”按钮之后的 3.7 秒沉默里。这篇手册只讲一件事如何让 OpenClaw 真正稳定地调用你本地跑起来的 Ollama 模型并且响应快、不出错、能扩展。不讲“什么是 LLM”不讲“Ollama 原理”不讲“为什么选 Qwen 而不是 DeepSeek”。只讲你打开终端、敲下第一行命令前该确认什么模型下载一半中断后该删哪几个文件夹OpenClaw 的skills.json里model字段到底填http://localhost:11434还是ollama://qwen2:7b还有当你发现响应延迟超过 800ms 时该看哪个日志、调哪个参数、换哪个后端。全文所有步骤均基于 Ubuntu 24.04 LTS / macOS Sonoma / Windows 11 WSL2 三平台实测所有命令、路径、配置项全部来自生产环境真实部署记录。如果你只需要“能跑”那网上随便找一篇就行如果你要的是“能用、好用、长期用”请往下读。2. 整体架构设计为什么必须用 OpenClaw Ollama而不是单用一个2.1 OpenClaw 的真实定位不是聊天界面而是技能编排引擎很多人把 OpenClaw 当成另一个 Ollama WebUI这是根本性误解。Ollama 自带的 WebUIollama serve启动后访问http://localhost:3000只做一件事给你一个输入框把你的文字发给模型把回复原样吐出来。它没有记忆、没有上下文管理、不能调用外部 API、更无法串联多个模型。而 OpenClaw 的核心价值在于它的Skill技能机制。一个 Skill 是一个独立的、可配置的、带输入输出契约的模块。比如web_search技能接收用户问句 → 调用 SerpAPI 获取搜索结果 → 提取摘要 → 交给大模型总结file_reader技能接收 PDF 路径 → 用 PyMuPDF 解析文本 → 分块 → 用嵌入模型向量化 → 存入本地 ChromaDBcode_review技能接收 Git Diff → 提取变更函数 → 调用本地 CodeLlama 模型逐行分析 → 生成 Markdown 格式报告。提示OpenClaw 本身不包含任何模型推理能力。它只是一个“指挥官”所有模型计算都委托给后端服务Ollama、vLLM、甚至你自己写的 Flask API。它的skills.json文件本质上是一张“服务调用地图”。所以当你说“部署 OpenClaw”真正在部署的是你为业务定制的一套技能网络。Ollama 在这里只是这张网络里最常用、最轻量的一个“士兵”。你可以随时把某个 Skill 的后端从ollama://qwen2:7b换成http://192.168.1.100:8000/v1/chat/completions指向你自己的 vLLM 集群OpenClaw 完全无感——只要新后端遵守 OpenAI 兼容 API 协议。2.2 Ollama 的不可替代性为什么不用直接跑 HuggingFace Transformers你当然可以不用 Ollama直接用transformersaccelerate加载模型。但代价是什么以Qwen2-7B-Instruct为例直接 Python 加载需手动处理 tokenizer、attention mask、KV cache、量化如 AWQ、CUDA graph 优化……光是写一个能跑通的generate()函数新手至少两天内存占用FP16 加载约 14GB 显存INT4 量化后约 4.2GB —— 但transformers默认不做内存复用连续请求易 OOMHTTP 封装你要自己写 FastAPI 接口处理流式响应、超时、并发连接池、健康检查……Ollama 把这些全包了。它底层用的是llama.cppCPU或llm.cppGPU对模型做了深度定制内存池预分配、请求队列优先级、自动批处理batching、流式 token 缓冲区管理。你ollama run qwen2:7b启动后它暴露的/api/chat接口就是一个生产就绪的、带重试和限流的模型服务。OpenClaw 只需按标准 OpenAI 格式发 POST 请求拿回 SSE 流解析delta.content即可。注意Ollama 的ollama list显示的模型名如qwen2:7b是它内部注册的别名不是 HuggingFace ID。你ollama pull qwen2:7b时它实际从https://registry.ollama.ai/library/qwen2:7b拉取的是一个已打包好的 GGUF 文件含权重tokenizermetadata不是原始 PyTorch bin。这决定了它启动快、内存稳、跨平台一致——但也意味着你不能随意修改模型结构。2.3 二者组合的黄金分工谁负责什么边界在哪模块职责你不该在这里做的事实际案例Ollama模型加载、推理执行、HTTP API 封装、GPU/CPU 资源调度、基础日志修改模型权重、添加自定义 layer、实现 RAG 检索逻辑ollama run deepseek-coder:6.7b启动后curl http://localhost:11434/api/chat -d {model:deepseek-coder:6.7b,messages:[{role:user,content:写一个Python函数计算斐波那契数列第n项}]}返回完整代码OpenClaw用户请求路由、多技能编排、上下文状态管理conversation history、外部 API 调用如飞书机器人、Notion API、前端 UI 渲染、权限控制直接加载.bin权重文件、手写 CUDA kernel、实现 tokenizer用户问“帮我查一下上周五的会议纪要”OpenClaw 触发notion_search技能查数据库拿到结果后喂给summary技能调 Ollama生成摘要再通过feishu_post技能发到飞书群你的代码定制 Skill 实现、配置skills.json、编写前端插件、设置反向代理如 Nginx、监控告警重写 Ollama 的 C 推理引擎、魔改 OpenClaw 的 React 核心组件为律所写的contract_analyzer技能Python 脚本调用pdfplumber提取条款 → 用正则匹配“违约责任”段落 → 发给本地qwen2:7b总结风险点这个分工一旦模糊项目就必然崩。常见错误是在 OpenClaw 的 Skill 里硬塞transformers.pipeline()结果每次请求都重新加载模型5 秒才出第一个 token或者试图在 Ollama 里写 JavaScript 调用飞书 API完全违背其设计哲学。记住Ollama 是肌肉OpenClaw 是神经你的代码是大脑——各司其职才能高效。3. 核心细节解析从零开始搭建每一步背后的“为什么”3.1 环境准备操作系统、硬件、依赖的硬性门槛这不是“有电脑就能跑”的玩具。OpenClaw Ollama 对环境有明确要求跳过验证后面 80% 的问题都源于此。操作系统Ubuntu首选 22.04 或 24.04 LTS。原因Ollama 官方提供.deb包内核版本与 NVIDIA 驱动兼容性最好。避免使用 Pop!_OS 或 Linux Mint它们默认的systemd-resolvedDNS 配置常与 Ollama 的localhost解析冲突。macOSSonoma (14.x) 或 Sequoia (15.x)。M1/M2/M3 芯片用户注意Ollama 默认用llama.cpp纯 CPU若要 GPU 加速必须手动编译支持 Metal 的版本见 3.3 节。Intel Mac 用户可直接用官方包。Windows仅支持 WSL2Ubuntu 22.04。不要尝试原生 Windows 版 Ollama社区版 bug 极多或 Docker Desktop。WSL2 的localhost网络与 Windows 主机互通OpenClaw 前端可直接访问http://localhost:11434。硬件底线CPU 模式无 GPU至少 16GB RAM推荐 32GB。qwen2:1.5b可勉强运行但qwen2:7b在 INT4 下需约 5.2GB 内存加上 OpenClawNode.js和系统24GB 更稳妥。NVIDIA GPU 模式显存 ≥ 8GB推荐 12GB驱动版本 ≥ 535.54.03对应 CUDA 12.2。nvidia-smi必须能正常显示 GPU 状态。严禁使用笔记本 Optimus 双显卡切换模式——必须设为独显直连NVIDIA Control Panel → 管理 3D 设置 → 全局设置 → 首选图形处理器 → 高性能 NVIDIA 处理器。Apple Silicon统一内存 ≥ 16GB。M1 Pro/Max 可流畅跑qwen2:7bM1 基础版建议用phi3:3.8b。关键依赖验证执行前必做# Ubuntu/macOS 终端执行 # 1. 检查 glibc 版本Ollama 依赖 ldd --version | head -1 # Ubuntu 22.04 应为 2.35 # 2. 检查 OpenSSLOpenClaw HTTPS 请求必需 openssl version -v # 应 ≥ 3.0.0 # 3. 检查 Node.jsOpenClaw 前端构建必需 node -v # 必须 ≥ 18.17.0V18.18.2 最稳 npm -v # 必须 ≥ 9.6.7 # 4. NVIDIA 用户额外检查 nvidia-smi --query-gpuname,memory.total --formatcsv,noheader,nounits # 确认显卡型号和显存实操心得我在某次部署中nvidia-smi显示正常但 Ollama 死活不用 GPU。最终发现是libcuda.so路径未加入LD_LIBRARY_PATH。解决方案echo export LD_LIBRARY_PATH/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH ~/.bashrc source ~/.bashrc。这种底层链接问题日志里不会明说只会表现为“模型加载慢”或“CPU 占用 100%”。3.2 Ollama 安装与国内镜像源配置解决“下载太慢”的本质方案Ollama 官方镜像源https://registry.ollama.ai在国内直连首字节延迟常超 3s且ollama pull无断点续传。这不是网络问题是协议设计问题——Ollama 使用 HTTP/1.1 分块传输中间断开即整个文件重下。正确解法双管齐下——换源 本地缓存第一步配置国内镜像源永久生效Ollama 从 v0.1.40 开始支持OLLAMA_HOST环境变量指定 registry 地址。但注意不能直接设为https://mirrors.aliyun.com/ollama因为阿里云镜像站是静态文件托管不提供 Ollama registry API。真正可用的是清华 TUNA 镜像已同步 registry API# Ubuntu/macOS echo export OLLAMA_HOSThttps://ollama.tuna.tsinghua.edu.cn ~/.bashrc source ~/.bashrc # 验证 ollama list # 应正常返回空列表说明连接 registry 成功第二步启用本地模型缓存防重复下载Ollama 默认将模型存于~/.ollama/models但每次pull都走网络校验。我们强制它跳过校验直接用本地文件# 创建缓存目录 mkdir -p ~/.ollama/cache # 下载模型文件用 wget/curl 从镜像站手动拉 # 例如 qwen2:7b 的 GGUF 文件地址清华镜像 # https://ollama.tuna.tsinghua.edu.cn/blobs/sha256-xxxxxx...需先查 manifest # 更简单用 ollama serve 启动后访问 http://localhost:11434/health 查看 registry 地址再构造 URL # 实用技巧用 ollama 的 debug 模式看真实下载 URL OLLAMA_DEBUG1 ollama pull qwen2:7b 21 | grep Pulling # 输出类似 Pulling from https://ollama.tuna.tsinghua.edu.cn/library/qwen2:7b第三步终极方案——离线部署包企业级推荐对于内网环境我制作了离线包下载ollama-linux-amd64或对应平台二进制用ollama pull在有网机器拉取所需模型如qwen2:7b,deepseek-coder:6.7b打包~/.ollama/models目录 ollama二进制 启动脚本内网机器解压后执行./ollama serve 再ollama list即可见模型注意Ollama 的模型文件是manifest.jsonblobs/sha256-xxx的组合。ollama list显示的qwen2:7b是manifest.json的 tagblobs/下的文件才是真实权重。复制时必须整目录拷贝缺一不可。3.3 模型选择与量化不是越大越好而是“够用快省”Ollama 模型库ollama list里上百个模型新手常陷入“选最强”的误区。实测结论在本地 24GB 内存 RTX 4090 环境下qwen2:7b是综合最优解。理由如下模型参数量INT4 显存占用7B 输入吞吐tok/s中文理解代码能力本地部署难度qwen2:7b7B~5.2GB142★★★★★★★★★☆★☆☆☆☆官方支持deepseek-coder:6.7b6.7B~4.8GB135★★★★☆★★★★★★★☆☆☆需手动 fix tokenizerllama3:8b8B~5.8GB128★★★☆☆★★★★☆★★☆☆☆英文 tokenizationphi3:3.8b3.8B~2.6GB185★★★★☆★★★☆☆★☆☆☆☆微软亲儿子量化选择指南重点:latest标签如qwen2:latest默认是 FP16绝对不要用——显存翻倍速度无提升。:7b是 INT4 量化版平衡最佳。Ollama 会自动识别并加载Q4_K_M格式 GGUF。:7b-q8_0是更高精度量化INT8显存多 30%速度慢 15%仅当:7b输出乱码时尝试。:7b-f16是半精度仅用于调试生产环境禁用。实测对比RTX 4090# 启动模型并计时 100 个 token 生成 time ollama run qwen2:7b 你好请用中文写一首关于春天的五言绝句只输出诗句不要解释 | wc -w # qwen2:7b: real 0m1.823s # qwen2:7b-q8_0: real 0m2.105s # qwen2:7b-f16: real 0m3.412s 且显存占用 8.2GB实操心得deepseek-coder:6.7b的 tokenizer 有 bugOllama 0.1.42 版本会把中文标点识别为|eot_id|。解决方案升级到 v0.1.45或改用deepseek-coder:6.7b-instruct已修复。这个细节官网文档一字未提全靠抓包ollama serve的请求体才发现。3.4 OpenClaw 部署从源码构建到生产环境反向代理OpenClaw 官方 GitHubhttps://github.com/openclaw/openclaw只提供源码没有预编译二进制或 Docker 镜像。这意味着你必须自己构建。别怕流程比想象中简单但有几个致命细节。构建前必改配置否则前端白屏 OpenClaw 的frontend/src/config.ts里有两处硬编码// frontend/src/config.ts export const API_BASE_URL http://localhost:3001; // 后端 API 地址 export const OLLAMA_BASE_URL http://localhost:11434; // Ollama 地址如果你的 Ollama 运行在另一台机器如192.168.1.100这里必须改否则前端发请求到localhost:11434而你的浏览器 localhost 并没有 Ollama。标准构建流程Ubuntu/macOS# 1. 克隆源码 git clone https://github.com/openclaw/openclaw.git cd openclaw # 2. 安装依赖注意必须用 pnpmnpm 会出错 curl -fsSL https://get.pnpm.io/install.sh | sh -s -- -p pnpm install # 3. 构建前端生成 dist/ 目录 pnpm build:frontend # 4. 构建后端Node.js 服务 pnpm build:backend # 5. 启动开发模式 pnpm dev # 访问 http://localhost:3000生产环境部署Nginx 反向代理 开发模式pnpm dev不能用于生产无 HTTPS、无进程守护。必须用 Nginx# /etc/nginx/sites-available/openclaw server { listen 443 ssl; server_name ai.yourcompany.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location / { root /path/to/openclaw/dist; try_files $uri $uri/ /index.html; } # 代理 API 请求到 OpenClaw 后端 location /api/ { proxy_pass http://127.0.0.1:3001/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 代理 Ollama 请求关键解决跨域 location /ollama/ { proxy_pass http://127.0.0.1:11434/; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }提示location /ollama/是精髓。OpenClaw 前端代码里所有调 Ollama 的请求都发到/ollama/api/chatNginx 把它转发到http://localhost:11434/api/chat。这样浏览器看到的是同源请求https://ai.yourcompany.com/ollama/彻底规避 CORS。如果直接在前端写http://localhost:11434Chrome 会因混合内容HTTPS 页面加载 HTTP 资源直接屏蔽。4. 实操过程详解从模型加载到技能配置完整链路拆解4.1 Ollama 模型加载与健康检查不只是ollama runollama run qwen2:7b能跑不代表它 ready for production。必须做三重验证第一重API 健康检查# 检查服务是否存活 curl http://localhost:11434/health # 检查模型是否加载成功返回模型信息 curl http://localhost:11434/api/show -d {name:qwen2:7b} # 发送测试请求流式 curl http://localhost:11434/api/chat -d { model: qwen2:7b, messages: [{role: user, content: 你好}], stream: true } -H Content-Type: application/json # 应返回 SSE 流每行以 data: 开头含 delta.content 字段第二重性能基线测试用ollama benchv0.1.40 内置测真实吞吐ollama bench qwen2:7b \ --prompt 请用中文写一段关于人工智能伦理的思考200字以内 \ --num-predict 256 \ --num-run 5 # 关注 avg eval time per token单位 ms/token理想值 8ms第三重GPU 加速验证NVIDIA 用户# 启动时强制指定 GPU OLLAMA_NUM_GPU1 ollama run qwen2:7b # 查看日志确认加载了 CUDA OLLAMA_DEBUG1 ollama run qwen2:7b 21 | grep -i cuda\|gpu # 应输出类似 Using CUDA backend with 1 GPU(s)注意OLLAMA_NUM_GPU1不是显卡编号是使用的 GPU 数量。多卡用户设为2Ollama 会自动负载均衡。4.2 OpenClaw 技能Skill配置skills.json的每一个字段含义OpenClaw 的灵魂在skills.json。它不是简单的“模型选择”而是定义了一个完整的调用契约。以code_review技能为例{ name: code_review, description: 分析代码变更指出潜在 bug 和安全风险, input_schema: { type: object, properties: { diff: {type: string, description: Git diff 文本}, language: {type: string, description: 编程语言如 python, javascript} }, required: [diff] }, output_schema: { type: object, properties: { issues: { type: array, items: { type: object, properties: { line: {type: integer}, severity: {type: string, enum: [low, medium, high]}, message: {type: string} } } } } }, handler: { type: ollama, model: qwen2:7b, system_prompt: 你是一名资深软件工程师专注于代码安全审计。请严格按 JSON 格式输出不要任何额外文本。, template: 请分析以下 {{language}} 代码变更\n{{diff}}\n输出格式{ \issues\: [ { \line\: 10, \severity\: \high\, \message\: \SQL 注入风险\ } ] } } }字段详解name技能唯一标识前端调用时用openclaw.skills.code_review(...)input_schemaJSON Schema定义输入参数结构。OpenClaw 前端会据此生成表单后端会校验。output_schema定义期望的返回结构。OpenClaw 会自动解析 JSON提取issues字段供后续技能使用。handler.type后端类型。ollama表示调 Ollamahttp表示调自定义 API。handler.modelOllama 模型名。必须与ollama list输出的 NAME 完全一致包括大小写和冒号。handler.system_prompt系统提示词影响模型角色设定。长度建议 200 字过长会挤占上下文。handler.template用户提示模板。{{diff}}是 input_schema 里定义的变量会被自动替换。实操心得template里的变量名必须与input_schema.properties的 key 完全一致。我曾把diff写成code_diff结果模型收到空字符串输出全是胡话。OpenClaw 不报错只默默传空值——这是最坑的调试点。4.3 前端性能优化让 OpenClaw 页面秒开响应如丝般顺滑OpenClaw 前端基于 React但默认构建未开启生产优化。实测发现未优化的dist/包体积达 12MB首屏加载超 8s3G 网络。优化后降至 2.1MB首屏 1.2s。四步优化法代码分割Code Splitting修改frontend/vite.config.tsexport default defineConfig({ build: { rollupOptions: { output: { manualChunks: { vendor: [react, react-dom, zustand], ui: [headlessui/react, heroicons/react], llm: [ollama/browser] // Ollama 浏览器 SDK 单独打包 } } } } });图片压缩frontend/public/下所有 PNG/JPG 用squoosh无损压缩体积减 60%。字体优化删除frontend/index.html中 Google Fonts 引用改用系统字体栈body { font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica, Arial, sans-serif; }Nginx Gzip Brotligzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xmlrss text/javascript; brotli on; brotli_types text/plain text/css application/json application/javascript text/xml application/xml application/xmlrss text/javascript;效果对比WebPageTest指标优化前优化后提升First Contentful Paint4.2s0.8s5.25xSpeed Index684012205.6xTotal Blocking Time1240ms85ms14.6x提示ollama/browserSDK 是 Ollama 官方提供的浏览器端调用库它封装了 SSE 流解析、重连、token 缓冲。OpenClaw 前端必须用它不能自己写 fetch —— 否则流式响应会卡顿。4.4 生产环境监控如何第一时间发现模型“生病”了本地跑通不等于线上稳定。我见过太多案例模型跑着跑着突然不响应ollama list还显示正常但 API 返回 500。必须建立监控闭环。三层监控体系基础设施层Prometheus Node Exporter监控ollama serve进程存活process_cpu_seconds_total{jobollama}监控 GPU 显存使用率nvidia_smi_duty_cycle{gpu0} 95告警监控内存泄漏process_resident_memory_bytes{jobollama} 8e9服务层自定义健康检查端点 在 OpenClaw 后端加/health// backend/src/routes/health.ts app.get(/health, async (req, res) { try { // 1. 检查 Ollama 是否可达 await axios.get(http://localhost:11434/health); // 2. 检查能否加载模型元数据 await axios.post(http://localhost:11434/api/show, { name: qwen2:7b }); // 3. 发送轻量测试请求不 stream await axios.post(http://localhost:11434/api/chat, { model: qwen2:7b, messages: [{ role: user, content: hi }], options: { num_predict: 10 } }); res.json({ status: ok, timestamp: new Date().toISOString() }); } catch (e) { res.status(503).json({ status: error, error: e.message }); } });应用层前端埋点 Sentry在 OpenClaw 前端useSkillHook 里捕获fetch错误上报 Sentry附带model、skillName、response.status。关键指标skill_response_time_p95 3000ms95 分位响应超 3s、skill_error_rate 5%。实操心得Ollama 的/api/chat在模型加载中会返回 503但ollama list仍显示模型。所以健康检查必须包含一次真实推理不能只 ping/health。我把这个检查做成每 30 秒一次的 cron job配合 Alertmanager 微信告警上线半年零意外宕机。5. 常见问题与排查技巧实录那些让你抓狂的“玄学”问题5.1 “OpenClaw 白屏控制台一片空白” —— 90% 是 HTTPS 混合内容现象访问https://ai.company.com页面空白F12 控制台无任何报错Network 标签页里index.html200但main.js显示failed to load resource。根因Nginx 配置了 HTTPS但main.js的 script 标签里写了http://ai.company.com/main.js协议未升级。现代浏览器禁止 HTTPS 页面加载 HTTP 资源。排查F12 → Network → 刷新 → 看第一个main.js请求