1. 项目概述在Windows上搭建本地AI助手如果你和我一样对依赖云端API的AI助手总有些顾虑——无论是出于隐私、成本还是单纯想折腾一下本地部署的乐趣——那么今天分享的这个项目绝对值得你花时间研究一下。它叫OpenClaw Ollama Setup核心目标就一个让你在Windows电脑上用一条PowerShell命令就能跑起来一个功能完整的、基于本地大语言模型的AI助手。整个过程不需要任何云服务API密钥所有计算和对话都发生在你自己的机器上。这个项目本质上是一个自动化部署脚本它把几个优秀的开源项目——OpenClaw一个AI Agent框架和Ollama一个本地大模型运行环境——无缝地整合在了一起。通过Docker容器化部署它帮你处理了从环境检测、模型下载、配置生成到服务启动的所有繁琐步骤。最终你会得到一个可以通过浏览器访问的Web仪表盘或者一个能接入Telegram的聊天机器人而它的“大脑”就是你从Ollama拉取的、完全在本地运行的LLM模型。我花了几天时间在自己的Windows 11开发机上完整走了一遍流程从环境准备到功能测试。这篇文章我会带你深入这个项目的每一个环节不仅告诉你“怎么做”更会解释“为什么这么做”并分享我在部署和调试过程中踩过的坑和总结的经验。无论你是想搭建一个私人的AI工作伙伴还是想学习现代AI应用本地化部署的实践这篇指南都能给你提供一条清晰的路径。2. 核心组件与架构深度解析在动手之前理解整个系统的构成和它们之间的协作关系至关重要。这能帮助你在遇到问题时快速定位是哪个环节出了岔子。2.1 核心三件套Ollama, OpenClaw, DockerOllama是这个生态的基石。你可以把它理解为一个本地化的“模型商店”和“推理引擎”。它负责两件事一是从它的模型库中下载你指定的大模型文件如qwen3:14b二是提供一个标准化的API服务兼容OpenAI的API格式让其他应用可以像调用ChatGPT一样调用你本地的模型。它的轻量化和易用性是本地AI应用得以普及的关键。OpenClaw则是一个建立在LLM之上的“智能体框架”。如果说Ollama提供了“大脑”那么OpenClaw就是为这个大脑配备了“四肢”和“感官”。它不仅仅是一个聊天界面更是一个可以调度工具、管理记忆、运行子任务的AI Agent系统。项目内置了诸如网页搜索通过Brave Search API、GitHub操作等技能并且允许你通过编写“技能”来扩展其能力。它的网关Gateway组件是所有交互的入口和调度中心。Docker Desktop for Windows扮演了“沙盒”和“粘合剂”的角色。OpenClaw及其依赖的服务被打包成容器通过Docker Compose统一管理。这样做的好处是环境隔离、依赖清晰、部署可重复。更重要的是在Windows上Docker Desktop巧妙地处理了容器与宿主机之间的网络通信使得容器内的OpenClaw服务能够通过host.docker.internal这个特殊域名无缝访问到宿主机上运行的Ollama服务。2.2 网络架构与数据流整个系统的数据流可以这样理解用户发起请求你在浏览器打开OpenClaw的仪表盘或者向Telegram机器人发送一条消息。网关接收与处理请求到达运行在Docker容器中的OpenClaw网关Gateway。网关负责身份验证、会话管理和请求路由。调用本地模型网关将处理后的请求一个符合OpenAI API格式的提示词通过HTTP发送到http://host.docker.internal:11434。这个地址会被Docker自动解析为宿主机的本地回环地址127.0.0.1从而访问到宿主机上Ollama服务的API端口。模型推理Ollama接收到请求加载指定的模型进行推理计算生成文本回复。结果返回与执行生成的文本回复被返回给网关。如果回复中包含工具调用例如“搜索一下今天的新闻”网关会调用对应的技能如Brave搜索执行并将结果再次发送给模型进行下一轮推理直到生成最终面向用户的纯文本回答。交付用户最终的回答由网关推送回WebSocket连接的仪表盘或通过Telegram Bot API发送给用户。注意host.docker.internal是Docker for Windows/macOS提供的一个特殊DNS名称用于让容器访问宿主机服务。这是实现“容器内应用访问宿主机本地服务”这一关键需求的标准且安全的方式避免了需要将Ollama服务绑定到所有网络接口0.0.0.0的安全风险。2.3 配置的哲学约定大于配置这个项目的自动化脚本setup.ps1体现了一个很好的设计思想为大多数场景提供智能的默认值同时为高级用户留出清晰的覆盖入口。脚本顶部的一系列变量如$OLLAMA_MODELS,$SETUP_TELEGRAM就是这些“入口”。你不需要去修改复杂的JSON或YAML文件只需在运行脚本前设置这些PowerShell变量脚本就会基于你的选择动态生成所有底层配置。例如默认的$OLLAMA_MODELS (qwen3:14b)表示使用通义千问14B版本作为主模型。如果你觉得14B模型对内存要求太高约需12GB空闲RAM完全可以改为(llama3.1:8b)。脚本会自动处理模型的拉取和OpenClaw中模型别名的配置。这种设计降低了入门门槛也让定制化流程变得标准化。3. 从零开始的完整部署实操记录下面我将以一台干净的Windows 11专业版系统为例展示从零开始部署的全过程。我的机器配置是i7-12700H, 32GB RAM并确保至少有50GB的可用磁盘空间用于存放模型。3.1 前期准备安装核心依赖第一步安装 Docker Desktop这是整个项目的运行基础。前往 Docker 官网下载 Windows 版本的 Docker Desktop Installer。安装过程基本是“下一步”到底但有两个关键点需要注意安装完成后Docker Desktop 会要求你重启电脑。必须重启否则WSL 2Windows Subsystem for Linux 2内核无法正常加载Docker将无法工作。重启后首次运行Docker Desktop它会提示你接受服务条款。之后你会在系统托盘区看到鲸鱼图标。等待其状态变为“Docker Desktop is running”这通常需要一分钟左右。你可以打开PowerShell输入docker version来验证是否安装成功。第二步安装 Ollama前往 Ollama 官网下载 Windows 版本的安装包。安装过程非常简单安装完成后Ollama会默认以后台服务的形式运行。你可以在PowerShell中输入ollama --version来验证。更重要的验证是打开浏览器访问http://localhost:11434如果看到Ollama的API响应可能是一个404页面但标题是Ollama说明服务已就绪。实操心得建议在安装Ollama后手动通过命令行先拉取一个小模型测试一下比如ollama run llama3.1:8b。这不仅能测试网络和下载是否正常也能让你对Ollama的命令行交互有个直观感受。如果这一步失败后续的自动化脚本也必然会失败。第三步安装 Git我们需要用Git来克隆项目仓库。如果你从事开发工作大概率已经安装了。如果没有请下载并安装 Git for Windows。安装后在PowerShell中运行git --version确认。3.2 执行自动化部署脚本当上述三个依赖都就位后真正的“一键部署”开始了。# 1. 克隆仓库务必使用 --recurse-submodules 参数 git clone --recurse-submodules https://github.com/flottokarotto/openclaw-ollama-setup.git C:\MyOpenClaw cd C:\MyOpenClaw # 2. 确认Docker Desktop正在运行系统托盘鲸鱼图标是绿色的 # 3. 以管理员身份打开PowerShell并运行部署脚本 .\setup.ps1脚本运行过程详解 当你执行.\setup.ps1后脚本会按顺序执行以下任务你可以在终端里看到详细的日志输出检测Ollama脚本会检查Ollama进程是否存在。如果不存在它会尝试从常见安装路径如$env:LOCALAPPDATA\Programs\Ollama\ollama.exe启动它。你会看到类似“Starting Ollama...”的提示。拉取模型根据$OLLAMA_MODELS变量默认为qwen3:14b脚本调用ollama pull命令下载模型。这是最耗时的一步14B模型大约有9GB下载速度取决于你的网络。请耐心等待。验证Docker连接脚本会运行docker info来确保Docker守护进程可用。准备配置目录在$env:USERPROFILE\.openclaw目录下创建必要的子文件夹如workspace和skills并将项目自带的模板文件如AGENTS.md复制过去仅当目标文件不存在时。生成配置文件脚本的核心工作之一。它会基于你设置的变量动态生成openclaw.json配置文件。这个文件定义了模型端点、Telegram Bot令牌、各种技能参数等。配置文件会放在$env:USERPROFILE\.openclaw目录下。构建Docker镜像脚本会进入OpenClaw子模块目录执行docker build来构建OpenClaw网关的镜像。这里有一个优化脚本利用了Docker的构建缓存。如果源码没有变化你没有设置$AUTO_UPDATE$true第二次运行时会跳过构建直接使用已有的镜像速度极快。启动服务通过docker compose up -d命令在后台启动OpenClaw网关容器。健康检查脚本会等待几秒钟然后尝试访问容器内的健康检查端点确认服务已正常启动。当脚本运行完毕你会在终端看到最重要的信息OpenClaw Dashboard的访问地址通常是http://localhost:18789。3.3 首次访问与设备配对打开浏览器访问上述地址。你不会直接进入聊天界面而是会看到一个“设备配对请求”的页面。这是OpenClaw的安全设计之一任何新的浏览器设备都需要授权。你需要回到PowerShell终端执行脚本输出的那两条命令来完成配对# 列出待批准的设备请求会显示一个requestId docker exec openclaw-openclaw-gateway-1 node dist/index.js devices list # 批准该请求将 requestId 替换为上一条命令输出的实际ID docker exec openclaw-openclaw-gateway-1 node dist/index.js devices approve requestId批准后刷新浏览器页面你就会看到OpenClaw的Web聊天界面了。至此一个完全本地的AI助手就已经在你的电脑上运行起来了。4. 高级配置与功能扩展指南基础部署完成后我们可以根据个人需求解锁更多功能。这些功能都是通过修改setup.ps1脚本顶部的变量或创建包装脚本来实现的。4.1 配置多模型与智能体分工默认使用单个模型如qwen3:14b既处理主对话也处理并行的子任务Subagents。但我们可以配置更高效的“大小模型协同”策略。场景我希望主对话使用能力更强的14B模型保证质量而让并行的、工具性的子任务如同时搜索多个关键词使用更快的8B模型提升响应速度。实现创建一个新的PowerShell脚本例如run-dual-model.ps1内容如下# 定义模型数组第一个是主模型最后一个是子任务模型 $OLLAMA_MODELS (qwen3:14b, qwen3:8b) # 运行主部署脚本 . $PSScriptRoot\setup.ps1运行这个脚本.\run-dual-model.ps1脚本会自动拉取qwen3:8b模型并在openclaw.json中配置好模型别名。在Web聊天框中你可以使用/model smart切换到14B模型用/model fast切换到8B模型。而所有由系统自动触发的子任务都会默认使用数组中的最后一个模型即qwen3:8b。4.2 集成Telegram机器人将OpenClaw连接到Telegram意味着你可以在手机上随时随地与你的本地AI助手聊天。这是非常实用的功能。第一步创建Telegram Bot在Telegram中搜索BotFather。发送/newbot指令按提示操作。为你的机器人取名如MyLocalAIBot和设置用户名必须以bot结尾如my_local_ai_bot。创建成功后BotFather会给你一个Bot Token形如1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ。妥善保存它相当于你机器人的密码。第二步创建专属运行脚本为了避免将Token硬编码在原始脚本中最佳实践是创建一个新的脚本文件。在项目根目录创建run-telegram.ps1这个文件名已被.gitignore排除不会提交到Git# 启用Telegram通道 $SETUP_TELEGRAM $true # 粘贴你从BotFather获得的Token $TELEGRAM_BOT_TOKEN 1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ # 允许哪些Telegram用户ID可以私聊机器人。暂时留空我们稍后获取。 $TELEGRAM_ALLOW_FROM () # 运行主部署脚本 . $PSScriptRoot\setup.ps1运行.\run-telegram.ps1。脚本会重新配置并重启网关服务。第三步获取你的Telegram User ID并授权在Telegram中搜索userinfobot向其发送任意消息它会回复你的用户ID是一个纯数字。将你的用户ID填入$TELEGRAM_ALLOW_FROM数组例如(987654321)。再次运行.\run-telegram.ps1以更新配置。现在你可以在Telegram中搜索你创建的机器人用户名如my_local_ai_bot并开始私聊。消息会由你本地的Ollama模型处理并回复。4.3 配置群组聊天无提及响应让机器人在Telegram群组中工作且不需要成员它就能响应这需要额外的配置。很多人在这里会踩坑。关键步骤分解关闭机器人的“隐私模式”这是最重要的一步。再次联系BotFather发送/mybots- 选择你的机器人 -Bot Settings-Group Privacy- 选择Turn off。这允许机器人看到群组中的所有消息。将机器人移出并重新加入群组隐私模式的更改只在机器人加入新群组时生效。如果机器人已经在群里你必须先将它移除然后再重新添加。否则它依然无法读取普通消息。获取群组Chat ID群组ID是一个负数例如-1001234567890。获取方法方法一推荐将机器人添加到群组后在群内发一条消息。然后在PowerShell中查看网关日志docker compose -f openclaw/docker-compose.yml logs -f openclaw-gateway。在日志中搜索chat.id你会看到对应的负数值。方法二将userinfobot临时添加到群组它会发送群组的ID。更新运行脚本修改你的run-telegram.ps1添加群组ID$SETUP_TELEGRAM $true $TELEGRAM_BOT_TOKEN 1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ $TELEGRAM_ALLOW_FROM (987654321) # 添加群组ID注意是负数 $TELEGRAM_GROUP_ALLOW (-1001234567890) . $PSScriptRoot\setup.ps1验证配置运行更新后的脚本。在群组中发送消息机器人应该能自动回复。你还可以通过一个API调用来验证机器人设置$token YOUR_BOT_TOKEN docker exec openclaw-openclaw-gateway-1 node -e fetch(https://api.telegram.org/bot$token/getMe) .then(r r.json()).then(d console.log(JSON.stringify(d.result, null, 2))) 在输出中确认can_read_all_group_messages字段的值为true。4.4 启用网页搜索能力让AI助手能联网搜索可以极大扩展其知识时效性。项目通过Brave Search API实现。访问 Brave Search API 页面 注册并获取一个免费API密钥。免费 tier 每月有2000次查询足够个人使用。在你的运行脚本如run-telegram.ps1中添加$BRAVE_SEARCH_API_KEY BSA_Your_Key_Here重新运行脚本。之后你就可以在聊天中让AI助手“搜索一下关于xxx的最新消息”它会调用Brave搜索并总结结果。5. 运维、调试与故障排查实录即使有自动化脚本在实际运行中也可能遇到各种问题。下面是我在部署和使用过程中遇到的一些典型情况及解决方法。5.1 容器启动失败与日志查看问题现象运行.\setup.ps1后脚本在“Starting services...”步骤长时间卡住或报错最后提示启动失败。排查思路这是最常见的问题。首先检查Docker Desktop是否真的在运行系统托盘图标为绿色。然后查看具体容器的日志。# 查看网关容器的最后50行日志 docker logs --tail 50 openclaw-openclaw-gateway-1 # 或者持续跟踪日志输出类似 tail -f docker compose -f openclaw/docker-compose.yml logs -f openclaw-gateway常见原因与解决端口冲突OpenClaw默认使用18789端口。如果该端口被其他程序占用容器会启动失败。可以通过修改openclaw/docker-compose.yml文件中的端口映射如将18789:18789改为18790:18789来解决然后重新运行.\setup.ps1。Ollama连接失败在容器日志中看到“Connection refused”或“ECONNREFUSED”错误指向host.docker.internal:11434。这表示容器无法访问宿主机的Ollama服务。确认Ollama运行在PowerShell中执行ollama list确保Ollama服务正常。测试端口在宿主机上执行curl http://localhost:11434应该能收到Ollama的响应。检查Docker网络极少数情况下Docker的虚拟网络可能有问题。尝试重启Docker Desktop。镜像构建失败如果日志显示在docker build阶段出错可能是网络问题导致依赖包下载失败。可以尝试在科学上网环境下重试或者手动进入openclaw子目录执行docker build .查看详细错误。5.2 模型加载缓慢或响应迟钝问题现象聊天界面可以打开但发送消息后需要等待非常久超过1分钟才有回复或者直接超时。排查思路这通常是本地LLM推理的瓶颈与你的硬件配置直接相关。分析与解决检查资源占用打开任务管理器查看CPU、内存和GPU如果有的占用情况。运行一个14B参数量的模型内存占用峰值可能会达到12-16GB。如果你的内存不足系统会使用硬盘交换文件导致速度极慢。选择合适的模型如果你的硬件资源有限不要强行运行大模型。在setup.ps1中尝试更小的模型例如llama3.2:3b仅需约4GB内存速度很快适合入门或低配置机器。qwen2.5:7b在7B级别中能力均衡需要约8GB内存。gemma2:9b需要约10GB内存在代码和推理任务上表现不错。利用GPU加速Ollama支持通过CUDA利用NVIDIA GPU进行加速这能极大提升推理速度。确保你安装了正确的NVIDIA显卡驱动和CUDA工具包。Ollama会自动检测并使用GPU。你可以通过ollama run llama3.1:8b命令测试在输出信息的开始部分如果看到类似“ GPU加速是”的提示具体提示因版本而异则说明GPU加速已启用。调整Ollama参数你可以通过设置环境变量来限制模型使用的资源例如OLLAMA_NUM_PARALLEL1可以减少并行请求数对于低配置机器可能更稳定。但这属于高级调优通常不需要修改。5.3 Telegram机器人无响应或报错问题现象机器人已添加到Telegram但发送消息后无回复或在网关日志中看到API错误。排查步骤检查Token和配置首先确认$TELEGRAM_BOT_TOKEN变量设置正确并且已经通过.\run-telegram.ps1重新部署。Token错误是最常见的原因。查看网关日志运行docker compose -f openclaw/docker-compose.yml logs -f openclaw-gateway然后向机器人发送一条消息。观察日志中是否有来自Telegram的Webhook请求记录以及是否有错误信息。常见错误403 Forbidden通常是Token错误或者机器人已被封禁。400 Bad Request: chat not found在群组配置中Chat ID必须是负数。请再次确认你获取的群组ID是否正确前面是否带了负号。机器人只回复私聊不回复群组99%的原因是机器人的“隐私模式”没有关闭或者关闭后没有将机器人移出群组重新添加。请严格按照4.3节的步骤操作。机器人重复发言或陷入循环这可能是系统提示词AGENTS.md过长或内容导致模型行为异常。尝试恢复项目自带的默认AGENTS.md模板。也可能是使用了某些经过特殊微调的模型切换回原版基础模型如qwen3:14b通常可以解决。5.4 日常维护与更新重启服务如果你修改了配置如模型、Telegram设置需要重启网关容器。项目提供了一个便捷脚本.\restart.ps1这个脚本会执行docker compose down然后docker compose up -d实现快速重启。更新OpenClaw源码如果你想获取OpenClaw框架的最新特性可以在运行setup.ps1前设置$AUTO_UPDATE $true。这会让脚本在构建镜像前先更新openclaw子模块的代码。注意这可能会因为API变更导致与现有配置不兼容建议在测试环境中先尝试。清理与卸载如果你想彻底清理整个环境# 停止并删除容器 docker compose -f openclaw/docker-compose.yml down # 删除构建的Docker镜像可选 docker rmi openclaw-gateway # 删除配置和数据目录位于用户目录下的 .openclaw 文件夹 # 请谨慎操作这会删除所有聊天记录和自定义技能Ollama拉取的模型文件默认存储在C:\Users\你的用户名\.ollama\models如需释放磁盘空间可以手动删除。经过以上步骤你应该已经拥有了一个完全在本地运行、功能可扩展的AI助手。从我的体验来看使用qwen3:14b这类中等规模的模型在32GB内存的机器上响应速度已经足够流畅能够胜任代码解释、文案构思、知识问答等大部分日常任务。将AI的能力从云端“拉回”本地不仅带来了一种数据自主的安全感也为探索AI应用的更多可能性打开了一扇门。