从零到一：在家用电脑上搭建私人AI助手

完整安装 · 错误排查 · Telegram集成 · GitHub集成 · 实时天气

版本 1.0  ·  2026年3月

目录

1.  前言：为什么要搭建本地AI

2.  为什么选择本地AI而不是云端AI

3.  硬件与软件要求

4.  系统架构详解

5.  详细安装步骤

5.1.  克隆项目

5.2.  配置环境变量（.env）

5.3.  启动容器

5.4.  WSL2 + Windows 专属配置

5.5.  信任HTTPS证书

5.6.  设置Windows端口转发

5.7.  批准浏览器设备

6.  Telegram机器人集成

7.  GitHub集成——用聊天管理代码

8.  实时天气功能配置

9.  常见错误与修复（10个真实案例）

10.  模型选择与切换指南

11.  实用命令速查表

12.  总结与展望

1. 前言：为什么要搭建本地AI

你是否曾经梦想过拥有一个像电影里一样的私人AI助手——随时回答问题、帮你处理工作、甚至在手机上直接和它聊天？这一切，现在都可以在你自己的家用电脑上实现，完全免费，数据永不离开你的机器。

本文将带你从零开始，一步一步地在家用PC（Windows + WSL2环境）上搭建一套完整的本地AI助手系统。我们使用的是 OpenClaw + Ollama 的组合方案——OpenClaw提供对话界面和工具集成，Ollama在你的NVIDIA GPU上运行大型语言模型。

这篇文章不仅是一份安装指南，更是一份"踩坑记录"。在搭建过程中我遇到了各种问题：SSL证书报错、端口无法访问、AI乱编天气数据……我会把每一个问题的原因和解决方案都详细记录下来，让你少走弯路。读完本文，你将真正理解每个组件的工作原理，而不只是复制粘贴命令。

2. 为什么选择本地AI而不是云端AI

在决定是否值得花时间搭建之前，先来看看本地AI和云端AI的核心区别：

对比项

云端AI（如ChatGPT）

本地AI（本方案）

数据隐私

❌ 数据上传到服务器

✅ 数据永不离开你的电脑

使用费用

❌ 按月/按量付费

✅ 一次配置，永久免费

网络依赖

❌ 必须联网

✅ 完全离线可用

响应速度

✅ 快（服务器算力）

✅ 快（本地GPU）

可定制程度

❌ 受平台限制

✅ 完全可控，自由定制

模型选择

❌ 只能用平台提供的

✅ 数百个开源模型任选

工具集成

部分支持（有限）

✅ GitHub、Telegram、天气API等

审查限制

❌ 有内容过滤

✅ 无审查，完全自主

  �� 核心理念

你的AI，你做主。没有订阅费，没有数据泄露，没有审查。
一次搭建，终身使用，这就是本地AI的魅力所在。

3. 硬件与软件要求

3.1 硬件要求

组件

最低要求

推荐配置

备注

操作系统

Windows 10

Windows 11

WSL2支持更稳定

显卡（GPU）

NVIDIA RTX 3070 (8GB显存)

RTX 4080/5080 (16GB+)

必须支持CUDA

内存（RAM）

16 GB

32 GB

模型加载占用较多

硬盘空间

20 GB可用

50 GB可用

qwen3:14b约需9GB

网络

普通宽带

百兆以上宽带

首次拉取模型约9GB

3.2 软件要求

软件

版本要求

用途

获取方式

Windows

10 / 11

宿主操作系统

系统自带

WSL2

2.x

Linux子系统（运行Docker）

wsl --install

Ubuntu (WSL2内)

22.04 LTS

Linux发行版

Microsoft Store免费

Docker Desktop

4.x 及以上

容器运行环境

docker.com

NVIDIA 驱动

525 及以上

GPU驱动

nvidia.com

NVIDIA Container Toolkit

最新版

Docker GPU直通

docs.nvidia.com

Git

2.x 及以上

克隆项目代码

git-scm.com

  ⚠️ 关键检查：验证Docker能否识别GPU

在所有步骤开始之前，先运行以下命令确认GPU可用：

  docker info | grep -i nvidia

如果输出中包含 "nvidia"，说明GPU配置正常。
如果没有输出，需要先安装NVIDIA Container Toolkit，否则模型将在CPU上运行，速度极慢。

4. 系统架构详解

整个系统由4个Docker容器组成，每个容器职责单一、分工明确。它们通过一个内部Docker网络（openclaw-net）互相通信，对外只暴露一个HTTPS端口（18790），安全且简洁。

容器名称

基础镜像

核心职责

对外端口

openclaw-ollama

ollama/ollama:latest

运行LLM，NVIDIA GPU加速推理

11434（内部）

openclaw-model-init

ollama/ollama:latest

首次拉取模型，完成后自动退出

无

openclaw-gateway

自定义构建

聊天界面 + 工具集成（GitHub/Telegram/天气）

18789（内部）

openclaw-caddy

caddy:latest

HTTPS反向代理，自动管理TLS证书

18790（对外）

5. 详细安装步骤

5.1 克隆项目

打开WSL2终端（在Windows开始菜单中搜索"Ubuntu"），执行以下命令：

# 进入你的工作目录（可以改成你喜欢的路径）

cd ~

# 克隆项目

git clone https://github.com/CloudsDocker/home-ai-stack.git

cd OpenClaw

# 确认文件结构

ls -la

正确的项目结构应如下所示：

OpenClaw/

├── docker-compose.yml       # 核心配置：编排所有容器

├── Caddyfile                # HTTPS反向代理配置

├── .env.example             # 环境变量模板（需复制为.env）

├── install-tools.sh         # 安装辅助脚本

├── openclaw-approve         # 批准浏览器设备的工具脚本

└── openclaw/

    ├── Dockerfile           # 自定义容器镜像构建配置

    └── entrypoint.sh        # 容器启动时的自动配置脚本

5.2 配置环境变量（.env）

这是最关键的一步。.env 文件控制整个系统的认证、集成和行为。配置错误会导致服务无法启动或功能缺失。

# 复制模板

cp .env.example .env

# 编辑配置

nano .env

.env 配置项详细说明：

# ──────────────────────────────────────────────────────

# 必填项

# ──────────────────────────────────────────────────────

# 网关认证Token（用于浏览器登录，务必设置为强随机值）

# 生成方法：openssl rand -hex 24

OPENCLAW_GATEWAY_TOKEN=your_strong_random_token_here

# ──────────────────────────────────────────────────────

# 可选项：AI模型选择

# ──────────────────────────────────────────────────────

# 默认使用qwen3:14b-fast（快速版，适合日常使用）

OPENCLAW_MODEL=ollama/qwen3:14b-fast

# ──────────────────────────────────────────────────────

# 可选项：Telegram机器人

# ──────────────────────────────────────────────────────

# 从 Telegram 的 @BotFather 获取

TELEGRAM_BOT_TOKEN=123456789:ABCdef_your_bot_token

# 你的 Telegram 用户ID（从 @userinfobot 获取）

TELEGRAM_ALLOWED_USER_ID=987654321

# ──────────────────────────────────────────────────────

# 可选项：GitHub集成

# ──────────────────────────────────────────────────────

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

GITHUB_REPO=yourusername/yourrepo

GITHUB_USERNAME=yourusername

GITHUB_BASE_BRANCH=master

# ──────────────────────────────────────────────────────

# 可选项：Brave网络搜索

# ──────────────────────────────────────────────────────

BRAVE_API_KEY=BSAxxx...

  �� 如何生成安全Token

在WSL2终端中运行：

  openssl rand -hex 24

示例输出：a3f7b2c9d1e4f8a0b5c6d7e8f9a0b1c2d3e4f5a6

将此输出复制到 OPENCLAW_GATEWAY_TOKEN= 后面，不要添加引号。

5.3 启动容器

配置完成后，执行以下命令启动所有服务。第一次运行时系统会自动下载AI模型（约9GB），请保持网络通畅并耐心等待。

# 后台启动所有容器

docker compose up -d

# 实时查看启动日志（推荐开另一个终端窗口运行）

docker compose logs -f

# 也可以只看AI网关的日志

docker compose logs -f openclaw

# 查看各容器运行状态

docker compose ps

当日志中出现以下内容时，说明系统已完全就绪：

[openclaw] Ollama is ready.

[openclaw] Model qwen3:14b is ready.

[openclaw] TOOLS.md written with GitHub access config

[openclaw] Registered 2 Ollama model(s): ['qwen3:14b', 'qwen3:14b-fast']

[openclaw] Starting gateway — model: ollama/qwen3:14b-fast  bind: lan  port: 18789

listening on ws://0.0.0.0:18789

  ⏱️ 首次启动需要时间

模型下载容器（openclaw-model-init）需要从网络下载约9GB的模型文件。
根据网速不同，这个过程可能需要10到60分钟。

查看下载进度：docker compose logs -f model-init

下载完成后，model-init容器会自动退出（这是正常行为）。

5.4 WSL2 + Windows 专属配置

如果你在Windows上通过WSL2运行Docker，需要额外的网络配置。这是因为WSL2有自己独立的网络空间，IP地址与Windows不同。

  WSL2网络访问原理图

  Windows浏览器            Windows网络层                  WSL2网络空间

  (Chrome/Edge)            (portproxy转发)                (Docker容器)

       │                        │                               │

       │  https://localhost      │   netsh portproxy             │

       │  :18790                │   127.0.0.1:18790 ───────────▶│ 172.x.x.x:18790

       │ ──────────────────────▶│ ────────────────────────────▶ │ openclaw-caddy

       │                        │                               │

  问题根源：浏览器访问 Windows 的 localhost，但服务运行在

           WSL2 虚拟机的私有 IP（172.x.x.x）上，直接无法访问。

  解决方案：用 Windows 的 netsh portproxy 命令建立端口映射。

5.5 信任HTTPS证书

Caddy会自动生成一个本地根CA证书，用于给localhost签发HTTPS证书。Windows和浏览器默认不信任未知CA，需要手动导入才能正常访问。

# 第一步：将证书从容器导出到Windows文件系统

docker exec openclaw-caddy cat /data/caddy/pki/authorities/local/root.crt   > /mnt/c/Users/Public/caddy-root.crt

# 验证文件已创建

ls -lh /mnt/c/Users/Public/caddy-root.crt

第二步：在Windows中导入证书（按顺序操作）：

  • 按 Win+R，输入 certmgr.msc，按回车，打开"证书管理器"
  • 在左侧树形菜单中，展开"受信任的根证书颁发机构"，点击"证书"
  • 在右侧空白区域右键 → "所有任务" → "导入"
  • 点击"下一步"，浏览文件，选择 C:\Users\Public\caddy-root.crt
  • 确保证书存储位置是"受信任的根证书颁发机构"
  • 完成导入后，完全关闭并重新打开Chrome或Edge（必须关闭所有窗口）

5.6 设置Windows端口转发

以管理员身份打开PowerShell（右键开始菜单 → "Windows PowerShell（管理员）"）：

# 第一步：在WSL2终端中获取当前IP

hostname -I | awk '{print $1}'

# 示例输出（你的IP会不同）：172.x.x.x

# 第二步：在 PowerShell（管理员）中执行（将IP替换为上面获取的值）

netsh interface portproxy add v4tov4 listenport=18790 listenaddress=127.0.0.1 connectport=18790 connectaddress=172.x.x.x

netsh interface portproxy add v6tov4 listenport=18790 listenaddress=::1 connectport=18790 connectaddress=172.x.x.x

# 验证配置是否生效

netsh interface portproxy show all

  ⚠️ 重要：重启后WSL2的IP会改变！

每次重启电脑后，WSL2会获得新的IP地址，端口转发会失效。
需要重新执行上述命令（先获取新IP，再重新添加转发规则）。

快速脚本：可将以下命令保存为 update-wsl-proxy.ps1，每次重启后运行：

  $ip = (wsl hostname -I).Trim().Split(" ")[0]
  netsh interface portproxy delete v4tov4 listenport=18790 listenaddress=127.0.0.1
  netsh interface portproxy add v4tov4 listenport=18790 listenaddress=127.0.0.1 connectport=18790 connectaddress=$ip
  Write-Host "代理已更新，WSL2 IP: $ip"

5.7 批准浏览器设备（首次访问）

第一次用浏览器访问时，OpenClaw需要确认这是受信任的设备。这是一次性操作，之后无需重复。

# 安装辅助脚本（只需运行一次）

bash install-tools.sh

# 打开浏览器访问（先访问，触发配对请求）：

# https://localhost:18790/#token=<你的OPENCLAW_GATEWAY_TOKEN>

# 然后在WSL2终端运行批准命令：

openclaw-approve

# 期望看到：

# Approving xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ...

# Approved <device-id>

# 刷新浏览器，即可正常使用

  �� 安装完成！

如果你能看到OpenClaw的聊天界面，说明安装成功！
你现在拥有了一个完全运行在本地的私人AI助手。

6. Telegram机器人集成

Telegram集成是这套系统最实用的功能之一。配置完成后，你可以随时随地从手机发消息给AI，就像和朋友聊天一样自然。

配置步骤

  • 步骤1：在Telegram中搜索 @BotFather，发送 /newbot 命令
  • 步骤2：为机器人起一个名字（如"我的AI助手"）和用户名（必须以bot结尾，如"myai_assistant_bot"）
  • 步骤3：BotFather会返回一个Token，格式如：123456789:ABCdef_GHIjkl...
  • 步骤4：搜索 @userinfobot，发送任意消息，它会告诉你自己的用户ID（纯数字）
  • 步骤5：将Token和用户ID填入 .env 文件，重建容器

# 在 .env 中填写

TELEGRAM_BOT_TOKEN=123456789:ABCdef_your_real_token_here

TELEGRAM_ALLOWED_USER_ID=987654321

# 重建并重启AI网关容器

docker compose build --no-cache openclaw

docker compose up -d openclaw

# 验证：在Telegram中找到你的机器人，发送一条消息测试

  Telegram消息处理流程

  你的手机              Telegram服务器          OpenClaw容器（家里的电脑）

  (Telegram App)        (telegram.org)          (openclaw-gateway)

       │                     │                         │

       │  "明天天气怎么样"    │  通过HTTPS长轮询         │

       │ ───────────────────▶│ ───────────────────────▶│

       │                     │                         │ 执行天气API查询

       │                     │                         │ (Open-Meteo)

       │  "明天晴天，25-32°C" │  返回AI回复              │

       │ ◀───────────────────│ ◀───────────────────────│

  �� 安全说明

TELEGRAM_ALLOWED_USER_ID 是白名单机制——只有你自己的用户ID才能与AI交互。
即使别人找到了你的机器人用户名，也无法与它对话，确保隐私安全。

7. GitHub集成——用聊天管理代码

配置GitHub集成后，你可以直接在聊天中让AI查看你的Pull Request、创建PR、查找最新分支——完全不需要打开浏览器或记复杂的Git命令。

获取GitHub Personal Access Token

  • 登录 GitHub → 点击右上角头像 → Settings
  • 左侧菜单滚到底部：Developer settings → Personal access tokens → Tokens (classic)
  • 点击 "Generate new token (classic)"
  • 选择权限：至少勾选 repo（全部子选项）
  • 点击生成，立即复制Token（页面刷新后无法再看到！）

# 在 .env 中配置（替换为你的实际值）

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

GITHUB_REPO=yourusername/yourrepo

GITHUB_USERNAME=yourusername

GITHUB_BASE_BRANCH=master

# 重建容器使配置生效

docker compose build --no-cache openclaw

docker compose up -d openclaw

配置成功后，你可以用自然语言与AI交互：

你说："帮我看看我有哪些还没合并的PR"

AI做：立即执行Python代码调用GitHub API，列出所有open PR

你说："帮我从 feature/login-fix 分支创建一个PR到master"

AI做：自动创建PR，返回PR链接和编号

你说："我最近提交的分支是哪个？"

AI做：查询所有分支，按提交时间排序，告诉你最新的分支名

8. 实时天气功能配置

8.1 问题：AI为什么会乱编天气？

大语言模型（LLM）本质上是一个"概率预测机器"——它根据训练数据预测下一个词，而不是真的去查询互联网。当你问天气时，它会根据训练数据里的模式生成一个"看起来合理"的回答，但这个回答是完全虚构的，这就是AI领域常说的"幻觉"（Hallucination）问题。

  ❌ 未配置天气工具时的典型错误

用户：我所在城市明天天气怎么样？

AI（编造）：明天天气：多云转阴，最高18°C，最低12°C，东北风3级，有小雨可能...

❌ 实际情况：那天是晴天，最高气温32°C。AI给出的数据完全错误！

8.2 根本原因：entrypoint.sh覆盖了配置文件

你可能会想：直接修改 workspace/TOOLS.md 加上天气工具说明不就行了？但这里有一个重要的"陷阱"：entrypoint.sh 每次容器启动时都会用Python脚本重新生成并覆盖 TOOLS.md！

  TOOLS.md覆盖问题示意图

  容器每次启动时（包括 docker compose restart）：

  entrypoint.sh

       │

       │  python3写入（覆盖！）

       ▼

  ~/.openclaw/workspace/TOOLS.md   ←── AI实际读取的文件

  workspace/TOOLS.md（项目目录） ──✗──  被忽略！仅在首次创建卷时使用

  结论：直接修改 workspace/TOOLS.md 对已运行的容器无效！

  正确做法：修改 entrypoint.sh 中的Python代码字符串。

8.3 正确修复方法

打开 openclaw/entrypoint.sh，找到 Python 的 content = """...""" 字符串，在结束的三引号之前加入天气工具说明：

# 在 entrypoint.sh 的 TOOLS.md 内容字符串末尾（结束"""之前）添加：

## Weather

**你的位置：** 你的城市，你的省/州，你的国家

（填入你实际所在位置的经纬度）

**重要规则：** 询问天气时，必须使用exec python3执行以下代码，

禁止猜测或编造天气数据！

```python

import urllib.request, json

lat, lon = 你的纬度, 你的经度   # 替换为你的实际经纬度

url = (

    "https://api.open-meteo.com/v1/forecast"

    f"?latitude={lat}&longitude={lon}"

    "&daily=weather_code,temperature_2m_max,temperature_2m_min,"

    "precipitation_sum,wind_speed_10m_max,uv_index_max"

    "¤t=temperature_2m,weather_code,wind_speed_10m,relative_humidity_2m"

    "&timezone=你的时区&forecast_days=7"

)

data = json.load(urllib.request.urlopen(url))

# ... 解析并打印结果

```

如何获取你所在地的经纬度：

  • 打开 maps.google.com，搜索你的城市或小区名称
  • 右键点击地图上的位置，选择"这是哪里？"
  • 屏幕下方会显示经纬度，例如：-33.7, 151.1（纬度在前，经度在后）

# 修改完 entrypoint.sh 后，重建容器使修改生效：

docker compose build --no-cache openclaw

docker compose up -d openclaw

# 测试：在聊天中问"明天天气怎么样？"

# AI应该立即执行Python代码，返回真实数据

  ✅ 修复后的效果

用户：明天天气怎么样？

AI：（立即执行Python，调用Open-Meteo免费API）
AI：明天天气预报：最低21°C，最高32°C，晴天，降水量0mm，风速12 km/h，UV指数9（高）

Open-Meteo API完全免费，无需注册，无需API Key，实时数据。

9. 常见错误与修复（10个真实案例）

以下是我在实际搭建过程中遇到的所有错误，每个都经过验证，附有根因分析和可直接使用的修复命令。

编号

错误现象

根本原因

严重程度

E1

ERR_CONNECTION_REFUSED (localhost:18790)

Windows端口转发未设置

�� 阻塞性

E2

ERR_SSL_PROTOCOL_ERROR

Caddy根证书未导入Windows

�� 阻塞性

E3

"pairing required" / "origin not allowed"

设备未批准 或 使用http而非https

�� 阻塞性

E4

GPU未被检测到 / CUDA错误

NVIDIA Container Runtime未正确配置

�� 阻塞性

E5

模型回复极慢（每秒不到2个字）

GPU初始化失败，退回CPU推理

�� 性能问题

E6

AI编造虚假天气数据

AI无实时天气工具，产生幻觉

�� 功能错误

E7

修改TOOLS.md不生效

entrypoint.sh每次启动覆盖此文件

�� 配置陷阱

E8

exec工具在Telegram中不可用

Telegram通道未配置exec权限

�� 功能缺失

E9

GitHub API返回401错误

Token无效、过期或权限不足

�� 功能缺失

E10

重启后浏览器又无法访问

WSL2每次重启分配新IP，端口转发失效

�� 常规维护

E1: ERR_CONNECTION_REFUSED

  错误现象

Chrome显示：ERR_CONNECTION_REFUSED
浏览器无法连接 https://localhost:18790

根本原因：

Docker容器运行在WSL2的网络空间（IP如172.x.x.x），而浏览器访问的是Windows的localhost。两者是隔离的网络空间，没有端口转发就无法互通。

修复步骤：

# 在WSL2中获取当前IP

hostname -I | awk '{print $1}'

# 假设输出: 172.x.x.x

# 在PowerShell（管理员）中执行（替换IP）:

netsh interface portproxy add v4tov4 listenport=18790 listenaddress=127.0.0.1 connectport=18790 connectaddress=172.x.x.x

netsh interface portproxy add v6tov4 listenport=18790 listenaddress=::1 connectport=18790 connectaddress=172.x.x.x

# 刷新浏览器

E2: ERR_SSL_PROTOCOL_ERROR

  错误现象

Chrome显示：ERR_SSL_PROTOCOL_ERROR 或 NET::ERR_CERT_AUTHORITY_INVALID
无法建立安全连接

根本原因：

Caddy使用自签名本地CA证书。Windows和Chrome不信任未知CA，需要手动将其加入系统信任列表。

修复步骤：

# 导出Caddy根证书

docker exec openclaw-caddy cat /data/caddy/pki/authorities/local/root.crt   > /mnt/c/Users/Public/caddy-root.crt

# Windows操作（图形界面）：

# Win+R → 输入 certmgr.msc → 回车

# 展开"受信任的根证书颁发机构" → 右键"证书" → 所有任务 → 导入

# 选择上面导出的 caddy-root.crt 文件

# 完全重启Chrome（关闭所有窗口后重新打开）

E3: "Pairing Required" / "Origin Not Allowed"

  错误现象

OpenClaw界面显示 "Device pairing required"
或显示 "Origin not allowed"

根本原因：

"Pairing required"：每台新浏览器第一次访问都需要设备授权，这是安全机制。
"Origin not allowed"：使用了http://而不是https://，或浏览器不在安全上下文中。

修复步骤：

# 修复 "pairing required"：

openclaw-approve

# 然后刷新浏览器

# 修复 "origin not allowed"：

# 确保URL使用 https:// 开头

# 正确格式：https://localhost:18790/#token=<你的token>

E4: GPU未被检测到

  错误现象

docker compose logs ollama 显示：
cuda: driver version mismatch 或 no GPU found

根本原因：

NVIDIA Container Runtime未正确安装，或Docker Desktop未启用GPU支持，导致容器无法访问GPU。

修复步骤：

# 第一步：验证GPU可用性

docker info | grep -i nvidia

# 期望输出包含: Runtimes: ... nvidia ...

# 第二步：测试GPU访问

docker run --rm --gpus all nvidia/cuda:12.0-base-ubuntu22.04 nvidia-smi

# 应该显示你的GPU信息

# 如果不可用，需要：

# 1. 安装 NVIDIA Container Toolkit（参考官方文档）

# 2. Docker Desktop → Settings → Resources → WSL Integration → 启用你的Ubuntu

E5: 模型回复极慢（CPU模式）

  错误现象

AI每次回复需要几分钟，明显不正常（正常GPU推理应是流畅的字流输出）

根本原因：

14B参数模型在CPU上每秒约生成1-3个token，而GPU上可达30-60 token/s。GPU初始化失败后，Ollama会静默回退到CPU模式，不报错但速度极慢。

修复步骤：

# 检查Ollama是否在用GPU

docker compose logs ollama | grep -E "gpu|cuda|CUDA|GPU"

# 期望看到: "CUDA: 1" 或 "GPU layers: 33/33"

# 实时查看GPU使用率（在WSL2中运行）

nvidia-smi -l 1

# 如果AI在推理时GPU利用率接近0%，说明在用CPU

# 解决：重新安装NVIDIA Container Toolkit，重启Docker

  �� 提示

14B模型在RTX 3080以上显卡上运行流畅（30+ token/s）。如果显存不足，可改用qwen3:8b（6GB显存）。

E6: AI编造虚假天气数据

  错误现象

询问天气时，AI给出的温度、天气情况与实际完全不符
（例如：夏天说18°C，实际32°C；晴天说有雨）

根本原因：

AI模型没有实时数据获取能力。在没有配置天气工具的情况下，它会基于训练数据"猜测"一个看似合理的回答，这就是所谓的"幻觉"（Hallucination）。答案可能听起来合理，但数据是假的。

修复步骤：

# 解决方案：在 entrypoint.sh 中添加天气工具（详见第8章）

# 然后重建：

docker compose build --no-cache openclaw

docker compose up -d openclaw

# 使用免费的 Open-Meteo API（无需注册，无需API Key）：

# https://api.open-meteo.com/v1/forecast?latitude=纬度&longitude=经度&...

E7: TOOLS.md修改不生效

  错误现象

直接修改了 workspace/TOOLS.md，重启容器后AI行为没有任何变化

根本原因：

entrypoint.sh 在每次容器启动时都会用Python脚本重新生成并写入 TOOLS.md，完全覆盖你的修改。workspace/TOOLS.md 只在第一次创建Docker卷时作为种子文件使用。

修复步骤：

# ❌ 错误做法（会被覆盖）：

vim workspace/TOOLS.md

# ✅ 正确做法：

vim openclaw/entrypoint.sh

# 找到 content = """...""" 字符串

# 在结束的 """ 之前添加你的内容

# 然后重建：

docker compose build --no-cache openclaw

docker compose up -d openclaw

E8: exec工具在Telegram中不可用

  错误现象

在Telegram中请AI执行代码时，AI说"我没有执行工具"或只描述步骤而不实际执行

根本原因：

OpenClaw按通道（channel）管理工具权限。Telegram DM通道默认不启用exec工具，需要在配置中显式开启。

修复步骤：

# 确认 entrypoint.sh 中包含以下配置：

# 1. exec工具全局配置

openclaw config set tools.exec.security allowlist

openclaw config set tools.exec.safeBins '["curl","python3"]'

openclaw config set tools.exec.ask off

# 2. Telegram DM通道的系统提示中包含工具权限：

# dm_direct["tools"] = {"alsoAllow": ["exec"]}

# 修改后重建：

docker compose build --no-cache openclaw && docker compose up -d openclaw

E9: GitHub API 401错误

  错误现象

AI在执行GitHub操作时返回：
401 Unauthorized 或 {"message": "Bad credentials"}

根本原因：

Personal Access Token无效（格式错误、含多余空格）、已过期、或未授予足够权限（需要repo scope）。

修复步骤：

# 检查Token是否正确（应以 ghp_ 开头，无空格）

grep GITHUB_TOKEN .env

# 用Token直接测试API（替换YOUR_TOKEN）

curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

# 正常应返回你的用户信息JSON，而不是401

# 如果Token无效，在GitHub重新生成：

# GitHub.com → Settings → Developer settings → Personal access tokens → 生成新Token

# 需要的权限：repo（全部子项）

E10: 重启后浏览器又无法访问

  错误现象

重启电脑或WSL2后，浏览器再次显示 ERR_CONNECTION_REFUSED

根本原因：

WSL2使用动态IP分配——每次重启都会获得新的IP地址，之前设置的端口转发规则还指向旧IP，因此失效。

修复步骤：

# 获取新的WSL2 IP

NEW_IP=$(hostname -I | awk '{print $1}')

echo "当前WSL2 IP: $NEW_IP"

# 在PowerShell（管理员）中更新转发规则：

netsh interface portproxy delete v4tov4 listenport=18790 listenaddress=127.0.0.1

netsh interface portproxy add v4tov4 listenport=18790 listenaddress=127.0.0.1 connectport=18790 connectaddress=<新IP>

  �� 提示

建议创建一个PowerShell脚本放在启动项中，每次开机自动更新端口转发。
或者在Windows中为WSL2设置静态IP（高级配置，可参考WSL2官方文档）。

10. 模型选择与切换指南

选择合适的模型取决于你的显卡显存和使用场景：

模型名称

所需显存

推理速度

回答质量

推荐使用场景

qwen3:14b-fast

~10 GB

⭐⭐⭐⭐⭐ 极快

⭐⭐⭐⭐ 优秀

日常对话、工具调用（默认推荐）

qwen3:14b

~10 GB

⭐⭐⭐ 中等

⭐⭐⭐⭐⭐ 最佳

复杂推理、代码分析、深度问答

qwen3:8b

~6 GB

⭐⭐⭐⭐⭐ 极快

⭐⭐⭐ 良好

显存不足时的轻量替代方案

llama3.1:latest

~5 GB

⭐⭐⭐⭐ 快

⭐⭐⭐ 良好

英文任务为主的轻量场景

phi4

~9 GB

⭐⭐⭐ 中等

⭐⭐⭐ 良好

⚠️ 不支持工具调用，不推荐

# 下载新模型

docker exec openclaw-ollama ollama pull qwen3:8b

# 切换默认模型

docker exec openclaw-gateway openclaw models set ollama/qwen3:8b

docker compose restart openclaw

# 查看已下载的模型列表

docker exec openclaw-ollama ollama list

11. 实用命令速查表

# ──────────────────────────────────────────────────────────────────────

# 日常启动与管理

# ──────────────────────────────────────────────────────────────────────

docker compose up -d                    # 启动所有服务（后台运行）

docker compose down                     # 停止并移除所有容器

docker compose restart openclaw         # 只重启AI网关（不重新下载模型）

docker compose ps                       # 查看所有容器状态

# ──────────────────────────────────────────────────────────────────────

# 日志查看

# ──────────────────────────────────────────────────────────────────────

docker compose logs -f                  # 所有容器实时日志

docker compose logs -f openclaw         # 只看AI网关

docker compose logs -f ollama           # 只看Ollama（模型服务）

docker compose logs --tail=50 openclaw  # 最近50行日志

# ──────────────────────────────────────────────────────────────────────

# 配置修改后重建

# ──────────────────────────────────────────────────────────────────────

docker compose build --no-cache openclaw && docker compose up -d openclaw

# ──────────────────────────────────────────────────────────────────────

# 数据重置（保留已下载的AI模型，重置聊天记录和配置）

# ──────────────────────────────────────────────────────────────────────

docker compose down

docker volume rm openclaw_openclaw-data

docker compose up -d

# ──────────────────────────────────────────────────────────────────────

# 完全重置（慎用！会删除所有数据包括已下载的9GB模型）

# ──────────────────────────────────────────────────────────────────────

docker compose down

docker volume rm openclaw_ollama-data openclaw_openclaw-data openclaw_caddy-data openclaw_caddy-config

docker compose up -d

# ⚠️ 完全重置后需重新导入HTTPS证书

12. 总结与展望

经过完整的搭建和踩坑，我们最终实现了一套功能完整的本地AI助手系统：

  • ✅ 完全本地运行：数据永不离开你的机器，隐私100%保护
  • ✅ GPU加速推理：qwen3:14b在NVIDIA显卡上流畅运行，响应迅速
  • ✅ HTTPS安全访问：Caddy自动管理证书，浏览器访问安全无警告
  • ✅ 手机随时使用：Telegram机器人随时随地，像聊天一样自然
  • ✅ GitHub代码助手：用自然语言管理PR和分支，无需记命令
  • ✅ 真实天气数据：Open-Meteo API实时查询，不再依赖AI编造
  • ✅ 永久免费使用：一次配置，长期使用，无任何订阅费

这次搭建的最大收获，不只是拥有了一个AI助手，而是深刻理解了每个组件的工作原理：为什么WSL2需要端口转发、为什么entrypoint.sh会覆盖配置文件、为什么AI会产生幻觉……这些理解让你能够真正驾驭和自定义这套系统。

展望未来，这套系统还可以进一步扩展：

  • 接入邮件：让AI监控并摘要重要邮件
  • 日历集成：提醒即将到来的会议和任务
  • 智能家居：通过Telegram控制家里的智能设备
  • 私人知识库：上传文档，让AI基于你的私人资料回答问题

如果这篇文章对你有帮助，欢迎给 GitHub 项目点个 ⭐ Star，也欢迎把文章分享给同样对本地AI感兴趣的朋友！

GitHub: https://github.com/CloudsDocker/home-ai-stack

# 人工智能
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

第6周学习总结：代码执行工具 + 多工具初步整合

本周完成了代码执行工具的安全沙箱设计，并为 Agent 添加了联网搜索能力，工具集扩展至 4 个，实现了从“只说不做”到“既说又做”的能力升级。

avatar 2048 AI社区
cover

OBS直播使用教程：OBS美颜插件OBS美颜摄像头OBS美颜相机下载安装使用教程

avatar 2048 AI社区

收藏！2026年小白程序员必入局的高薪AI赛道（含10大吃香岗位）

2026年AI岗位激增12倍，月薪破6万，供需比仅0.97，企业高薪抢人。文章介绍了10个前景广阔的AI岗位，如AI科学家、大模型算法工程师、AI产品经理等，部分岗位适合非计算机背景者。提供内部转型、转行过渡、自学上岸、考取证书等四条普通人入局AI的路径，强调越早入局机会越大。---

avatar 2048 AI社区