Openclaw本地部署与技能集成全链路实战指南-拓冰建站

1. 项目概述：这不是一个“安装教程”，而是一份Openclaw本地化落地的全链路实践手记

Openclaw这个词，最近半年在技术圈、AI工具圈、甚至部分金融和运营团队内部高频出现。它不是某个大厂发布的明星产品，也不是GitHub上刚冒头的玩具项目，而是一个正在快速演进、功能边界持续外扩的开源智能体（Agent）框架。标题里那个“可能全网最全/长的2万字”不是噱头——我花了整整三周时间，在四台不同配置的机器上反复部署、调试、压测、集成、拆解源码，把从零开始到稳定接入飞书、微信、MySQL、本地知识库、自定义技能的每一步都踩实了，才敢说这是一份真正能“抄作业”的保姆级记录。它不讲虚的架构图，不堆砌概念，只解决你打开终端后第一行该敲什么、遇到报错该查哪一行日志、WebUI打不开是缺端口还是缺依赖、为什么技能调用总卡在“thinking”、以及最关键的——它到底适不适合你当前的业务场景。如果你正面临这些具体问题：想用本地大模型跑一个能自动查数据库+写日报+回钉钉消息的自动化流程；想把公司内部的Excel报表、PDF制度文档、Confluence页面变成可被自然语言提问的知识库；或者只是单纯想搞懂Openclaw和LangChain、LlamaIndex、AutoGen这些名字听起来很像的框架到底差在哪……那这份内容就是为你写的。它覆盖Windows 10/11、Ubuntu 20.04/22.04、macOS Sonoma三大主流系统，支持Docker一键拉起和源码深度定制两种路径，所有命令、配置、截图、日志片段均来自真实环境，连pip install失败时的报错堆栈都截了屏存档。这不是教科书，这是我在工位上熬了三个通宵后，把键盘擦干净、把笔记整理好，推给你的一份带温度的实战复盘。

2. Openclaw核心定位与能力边界：先搞清它“不是什么”，再理解它“能做什么”

很多人第一次听说Openclaw，是看到“国产替代AutoGen”“中文版LangChain”这类标题党宣传。这种类比本身就有误导性。Openclaw既不是LangChain的简化版，也不是AutoGen的汉化包，更不是另一个RAG（检索增强生成）玩具。它的底层设计哲学非常明确：面向终端用户交付可感知价值，而非面向开发者交付抽象能力。这个定位差异，直接决定了它的技术选型、模块划分、甚至错误提示的友好程度。

2.1 它不是“另一个LLM推理框架”

你不会在Openclaw里找到类似vLLM、llama.cpp那样的模型量化、KV Cache优化、PagedAttention调度等底层推理引擎代码。它默认依赖HuggingFace Transformers + accelerate做模型加载，对模型格式的要求是标准的GGUF（用于llama.cpp兼容）或HF原生格式（如Qwen2、DeepSeek-V2）。这意味着：

如果你手头有经过AWQ量化、但没转成GGUF的Qwen2-7B模型，Openclaw无法直接加载，必须先用llama.cpp的convert-hf-to-gguf.py脚本转换；
如果你追求极致吞吐，想用vLLM跑7B模型达到300+ tokens/s，Openclaw目前不提供vLLM后端接入点（社区PR已提交，但未合并）；
它对显存的利用是“够用就好”策略：启动时会根据--gpu-layers参数（默认35）把模型前35层卸载到GPU，其余层留在CPU，这在RTX 3090上能跑满7B，但在RTX 4090上反而不如把--gpu-layers设为50来得快——这个参数没有银弹，必须实测。我测过12组组合，最终在4090上--gpu-layers=50比默认值快18%，但显存占用多出1.2GB，这就是它“务实不激进”的体现。

2.2 它不是“纯RAG知识库工具”

Openclaw内置的RAG模块叫KnowledgeBase，但它和LlamaIndex那种动辄要你写VectorStoreIndex.from_documents()的API完全不同。它的交互是声明式的：你只需把PDF、TXT、MD文件扔进./data/knowledge/目录，执行openclaw knowledge rebuild，它就会自动完成分块（chunking）、嵌入（embedding）、向量索引（FAISS）三步。关键在于，它默认使用的嵌入模型是bge-m3，这是一个支持中英混合、多粒度（段落/句子/词）、且对长文本语义保持极佳的模型。我拿公司200页的《财务报销制度V3.2》PDF测试，用bge-m3嵌入后，问“差旅补贴标准是多少”，返回结果精准定位到第47页第3段；换成text2vec-large-chinese，答案就飘到了“办公用品采购流程”章节。这不是玄学，bge-m3的论文里明确写了其在LongDocQA数据集上F1值比同类高12.7%。Openclaw没让你选模型，是因为它已经替你做了这个决策——它相信bge-m3是当前中文长文档场景下的最优解。

2.3 它真正的核心价值：把“技能”（Skill）变成可插拔的原子单元

这才是Openclaw区别于其他框架的“心脏”。在LangChain里，你要写Tool类，重写_run方法，处理输入输出序列化；在AutoGen里，你要定义UserProxyAgent、AssistantAgent，再用GroupChatManager编排。Openclaw把这一切封装成一个.yaml文件。比如，你想让AI能查MySQL数据库，你不需要写Python代码，只需创建skills/mysql_query.yaml：

name: mysql_query description: 执行SQL查询并返回结构化结果 parameters: - name: sql type: string description: 要执行的SQL语句，必须是SELECT required: true exec: command: python3 ./skills/mysql_executor.py timeout: 30

然后在./skills/mysql_executor.py里写真正的逻辑——但注意，这个Python脚本的输入输出是严格约定的JSON格式，Openclaw只负责传参和收结果。这种设计带来两个硬核好处：

技能开发零耦合：前端工程师可以用Node.js写一个调用飞书API发消息的Skill，后端工程师用Go写一个调用内部RPC服务的Skill，数据科学家用R写一个调用statsmodels做回归分析的Skill，它们在Openclaw里完全平权，只要遵守JSON I/O协议；
故障隔离强：某个Skill崩溃（比如MySQL连接超时），不会导致整个Openclaw进程挂掉，它只会返回{"error": "mysql connection timeout"}，主流程继续执行。我在压测时故意把MySQL停掉，观察了12小时，Openclaw的skill_manager日志里只有ERROR级别记录，WebUI始终可用，这是很多“全家桶”框架做不到的稳定性。

提示：Openclaw的Skill机制不是魔法，它背后是subprocess.Popen+json.loads/stdin的朴素实现。这意味着你不能在Skill里开长期TCP连接（会阻塞主进程），也不能用sys.exit()退出（会导致Skill管理器误判为崩溃）。我踩过的最大坑是：一个用requests.Session()写的HTTP Skill，在并发100请求时内存泄漏，最后改成每次请求新建Session才解决。

3. 全平台部署实操：从裸机到Docker，每一步都附带“为什么这么选”

部署Openclaw，本质是在不同约束条件下做技术取舍。Windows用户要面对WSL2的兼容性，Ubuntu用户要处理systemd服务的持久化，Mac用户则要绕过Apple Silicon的ARM64编译陷阱。没有“最佳路径”，只有“最适合你当前环境的路径”。下面我把四条主线全部走通，并告诉你每一步背后的工程权衡。

3.1 Windows 10/11 原生部署（推荐给新手，避坑指南）

Windows部署最大的敌人不是Openclaw，而是Python生态的碎片化。官方文档建议用Anaconda，但实测下来，Miniconda更轻量、更可控。以下是完整流程：

安装Miniconda3（Python 3.10）
下载地址：https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe
注意：必须选x86_64版本，即使你的CPU是ARM64（如Surface Pro X）。因为Openclaw依赖的llama-cpp-python在Windows ARM64上无预编译wheel，手动编译需要Visual Studio 2022全套工具链，耗时4小时以上且成功率低于30%。x86_64版通过Windows x64子系统运行，性能损失不到8%，但稳定性100%。

创建专用环境并激活

conda create -n openclaw python=3.10 conda activate openclaw pip install --upgrade pip

安装核心依赖（关键步骤）
这里有个致命陷阱：llama-cpp-python必须指定--force-reinstall --no-deps，否则pip会试图安装旧版pydantic（v1.x），而Openclaw要求v2.6+。正确命令是：
```
pip install llama-cpp-python --force-reinstall --no-deps --index-url https://pypi.org/simple/ --extra-index-url https://download.pytorch.org/whl/cu118 pip install openclaw[all]
```
--extra-index-url指向PyTorch CUDA 11.8镜像，确保torch和torchaudio能装上。如果显卡是RTX 40系，CUDA 11.8是唯一兼容的版本（CUDA 12.x对40系驱动支持不稳）。
下载并配置模型（以Qwen2-7B-Instruct为例）
模型必须是GGUF格式。HuggingFace上Qwen2-7B-Instruct的官方GGUF版在Qwen/Qwen2-7B-Instruct-GGUF仓库。下载qwen2-7b-instruct.Q4_K_M.gguf（4.8GB，平衡精度与速度）。
放置路径：./models/qwen2-7b-instruct.Q4_K_M.gguf
配置文件config.yaml关键项：
```
model: path: "./models/qwen2-7b-instruct.Q4_K_M.gguf" n_gpu_layers: 50 # RTX 4090实测最优值 ctx_size: 4096 # 上下文长度，别设太高，Win内存吃紧
```
启动与验证
```
openclaw webui --host 0.0.0.0 --port 8080
```
如果浏览器打不开http://localhost:8080，90%概率是Windows防火墙拦截。解决方案：
- Win+R →wf.msc→ 高级设置 → 入站规则 → 新建规则 → 端口 → TCP 8080 → 允许连接 → 命名“Openclaw WebUI”
- 或者临时关闭防火墙（仅测试用）：netsh advfirewall set allprofiles state off

3.2 Ubuntu 20.04/22.04 源码部署（推荐给生产环境）

Ubuntu部署的核心诉求是可审计、可回滚、可监控。Docker虽然方便，但日志分散、进程隔离太强，不利于排查GPU显存泄漏这类底层问题。源码部署能让你完全掌控每个环节。

系统准备（关键检查项）

# 检查CUDA驱动（必须>=11.8） nvidia-smi # 输出应显示Driver Version: 525.85.12 或更高 # 检查gcc版本（必须>=11） gcc --version # Ubuntu 20.04默认是9.4，需升级 sudo apt update && sudo apt install -y build-essential sudo apt install -y software-properties-common sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test sudo apt update && sudo apt install -y gcc-11 g++-11 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100 --slave /usr/bin/g++ g++ /usr/bin/g++-11

Python环境（不用conda，用pyenv）
Conda在Ubuntu服务器上常因libglib版本冲突导致llama-cpp-python编译失败。pyenv更干净：

curl https://pyenv.run | bash export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)" pyenv install 3.10.12 pyenv global 3.10.12

编译安装llama-cpp-python（必须源码编译）

git clone https://github.com/abetlen/llama-cpp-python.git cd llama-cpp-python # 修改setup.py：将CUDA_ARCHS改为"80;86;87;90"（覆盖A100/3090/4090/Ada） pip install -e ".[cuda]" cd ..

安装Openclaw并配置systemd服务

git clone https://github.com/openclaw/openclaw.git cd openclaw pip install -e ".[all]" # 创建systemd服务文件 /etc/systemd/system/openclaw.service [Unit] Description=Openclaw Service After=network.target [Service] Type=simple User=ubuntu WorkingDirectory=/home/ubuntu/openclaw ExecStart=/home/ubuntu/.pyenv/versions/3.10.12/bin/python -m openclaw.webui --host 0.0.0.0 --port 8080 Restart=always RestartSec=10 Environment="PYTHONPATH=/home/ubuntu/openclaw" [Install] WantedBy=multi-user.target

启用服务：

sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw sudo journalctl -u openclaw -f # 实时看日志

3.3 macOS Sonoma (ARM64) 部署（M1/M2/M3芯片专属）

Mac部署的痛点是：Apple Silicon的ARM64架构与大量Python包的x86_64 wheel不兼容。强行用Rosetta2转译，性能损失40%以上。必须走原生ARM64路径。

安装ARM64原生Homebrew

# 卸载旧版（如果存在） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)" # 安装ARM64版 arch -arm64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

安装ARM64原生Python（用pyenv）

brew install pyenv # 必须指定--enable-framework，否则后续llama-cpp编译失败 CONFIGURE_OPTS="--enable-framework" pyenv install 3.10.12 pyenv global 3.10.12

编译llama-cpp-python（关键：禁用CUDA，启用Metal）
M系列芯片没有NVIDIA CUDA，但有Apple Metal加速。llama-cpp-python支持Metal后端：
```
LLAMA_METAL=1 pip install llama-cpp-python --no-cache-dir --force-reinstall --no-deps
```
LLAMA_METAL=1是开关，它会编译llama.cpp的Metal backend，让GPU计算跑在Apple GPU上。实测M2 Max（38核GPU）跑Qwen2-7B，token生成速度比CPU快3.2倍。

配置Openclaw使用Metal
config.yaml中添加：

model: path: "./models/qwen2-7b-instruct.Q4_K_M.gguf" n_gpu_layers: 1 # Metal后端只需设1，它会自动调度全部GPU核心 use_metal: true # 显式开启Metal

3.4 Docker一键部署（推荐给快速验证、CI/CD集成）

Docker不是银弹，但对“5分钟跑起来看看效果”场景无可替代。Openclaw官方提供了docker-compose.yml，但有几个隐藏坑：

GPU支持必须用nvidia-container-toolkit
Ubuntu上安装：

curl -sL https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - distribution=$(. /etc/os-release;echo $ID$VERSION_ID) curl -sL https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update && sudo apt-get install -y nvidia-docker2 sudo systemctl restart docker

Docker Compose配置（修正版）
官方docker-compose.yml没指定GPU设备，会导致nvidia-smi在容器内不可见。修正如下：

version: '3.8' services: openclaw: image: openclaw/openclaw:latest ports: - "8080:8080" volumes: - ./models:/app/models - ./data:/app/data - ./skills:/app/skills environment: - MODEL_PATH=/app/models/qwen2-7b-instruct.Q4_K_M.gguf - GPU_LAYERS=50 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] # 关键：添加runtime runtime: nvidia

启动与日志查看

docker-compose up -d docker-compose logs -f # 查看实时日志 # 如果报错"Failed to initialize CUDA"，说明nvidia-docker2没装好或驱动版本不匹配

4. 核心功能深度解析：WebUI、Skill、KnowledgeBase、Database四大模块实操

Openclaw的WebUI不是简单的聊天界面，它是一个完整的Agent工作台。理解它的四个核心模块，等于掌握了80%的日常操作。

4.1 WebUI：不只是聊天框，而是Agent状态监控中心

打开http://localhost:8080，你会看到一个简洁界面。但它的每个区域都有明确工程意义：

顶部状态栏（Status Bar）：显示Model: Qwen2-7B | GPU Layers: 50 | VRAM: 6.2/24.0 GB。这个VRAM读数不是nvidia-smi的粗略值，而是Openclaw自己通过llama_cpp.Llama对象的get_kv_cache_token_count()和get_used_memory()方法实时计算的精确值。它能告诉你：当前上下文占用了多少显存，离OOM还有多远。当这个数字超过90%，你就该清理对话历史或降低ctx_size了。
左侧技能面板（Skills Panel）：列出所有已加载的Skill。点击一个Skill，右侧会显示其YAML定义和最近3次调用日志。这里有个隐藏功能：长按Skill名称2秒，会弹出“Test Skill”按钮，你可以手动输入JSON参数，直接触发Skill执行，无需走完整Agent流程。这在调试MySQL查询SQL语法错误时极其高效。
中间聊天区（Chat Area）：支持Markdown渲染、代码块高亮、表格自动对齐。但最关键的是消息元数据：每条AI回复下方有小字[Skill: mysql_query]或[RAG: finance_policy.pdf]，明确告诉你这条回复是靠哪个Skill或哪个知识库片段生成的。这解决了“AI胡说八道时，我怎么知道它信了谁”的溯源难题。
底部控制栏（Control Bar）：除了常规的发送、清空，有一个Debug Mode开关。打开后，所有消息都会附带DEBUG: {"thoughts": "...", "plan": [...], "tool_calls": [...]}这样的JSON结构。这是Openclaw的ReAct（Reasoning + Acting）引擎的原始输出。我靠这个调试过一个金融分析Skill：发现它总是把“市盈率”（PE Ratio）误解为“市净率”（PB Ratio），根源是Prompt里没给足够清晰的术语定义。加了一行PE Ratio = Price / Earnings Per Share后，准确率从62%升到98%。

4.2 Skill开发：从零写一个“查飞书多维表格”的实战案例

官方Skill库里没有飞书多维表格（Lark Bitable）支持，但开发一个只需30分钟。以下是完整过程：

注册飞书开放平台应用
进入https://open.feishu.cn/app → 创建新应用 → 选择“自建应用” → 开启“多维表格”权限 → 获取APP_ID、APP_SECRET、VERIFICATION_TOKEN。

创建Skill YAML文件
skills/lark_bitable_query.yaml：

name: lark_bitable_query description: 查询飞书多维表格中的数据 parameters: - name: app_token type: string description: 多维表格所在应用的app_token required: true - name: table_id type: string description: 表格ID required: true - name: filter type: string description: 过滤条件，如 "field_1 = '张三'" required: false exec: command: python3 ./skills/lark_bitable_executor.py timeout: 60

编写Executor Python脚本
skills/lark_bitable_executor.py：

import json import sys import requests from datetime import datetime # 从stdin读取Openclaw传入的参数 input_data = json.loads(sys.stdin.read()) app_token = input_data.get("app_token") table_id = input_data.get("table_id") filter_expr = input_data.get("filter", "") # 飞书API认证（获取tenant_access_token） auth_url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal/" auth_payload = { "app_id": "YOUR_APP_ID", "app_secret": "YOUR_APP_SECRET" } auth_resp = requests.post(auth_url, json=auth_payload) tenant_token = auth_resp.json().get("tenant_access_token") # 查询多维表格 query_url = f"https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records" headers = {"Authorization": f"Bearer {tenant_token}"} params = {"filter": filter_expr} if filter_expr else {} query_resp = requests.get(query_url, headers=headers, params=params) # Openclaw要求：必须输出JSON，且必须有"result"字段 if query_resp.status_code == 200: records = query_resp.json().get("data", {}).get("items", []) # 只返回关键字段，避免数据过大 simplified = [{"id": r["record_id"], "fields": {k: v for k, v in r["fields"].items() if k in ["姓名", "部门", "入职日期"]}} for r in records] print(json.dumps({"result": simplified}, ensure_ascii=False)) else: print(json.dumps({"error": f"API Error: {query_resp.status_code} {query_resp.text}"}, ensure_ascii=False))

在WebUI中测试
在Skills Panel里找到lark_bitable_query，点击Test Skill，输入：
```
{ "app_token": "app_xxx", "table_id": "tbl_yyy", "filter": "field_1 = '张三'" }
```
成功返回后，你就可以在聊天中自然提问：“查一下张三在飞书多维表格里的入职日期”。

实操心得：飞书API返回的record_id是全局唯一，但fields里的字段ID（如field_1）是应用内唯一。我第一次调试时，把field_1写成了field_2，结果返回空数组，花了2小时才定位到是字段ID映射错了。建议在Skill里加一行日志：print(f"[DEBUG] Querying field_1 with value {filter_expr}")，把调试信息输出到Openclaw的Skill日志里。

4.3 KnowledgeBase：如何让AI真正“读懂”你的PDF和Excel

Openclaw的KnowledgeBase不是简单扔文件进去就完事。它的分块（chunking）策略直接影响RAG效果。

默认分块逻辑
Openclaw用unstructured库解析PDF/DOCX，用pandas读取Excel。分块大小默认是512字符，重叠（overlap）128字符。但这个值对财报类长文本不友好。我测试过某上市公司2023年报（PDF，186页），用默认分块，问“2023年净利润是多少”，AI返回了“详见第127页”，而不是具体数字。原因是：净利润数据在“合并利润表”里，而该表格被切分在两个chunk中，语义断裂。

自定义分块方案（推荐）
修改config.yaml：

knowledge: chunk_size: 1024 # 加大到1024，适应表格和长段落 chunk_overlap: 256 # 重叠也加大，保证表格跨chunk时信息完整 separators: ["\n\n", "\n", "。", "！", "？", "；", "，"] # 中文标点优先切分

Excel特殊处理
Openclaw会把Excel每个Sheet当作一个独立文档处理。但如果Sheet里是结构化数据（如销售明细表），直接分块毫无意义。正确做法是：用Python脚本预处理，把Excel转成Markdown表格，再喂给KnowledgeBase。例如：
```
# preprocess_excel.py import pandas as pd df = pd.read_excel("sales_2023.xlsx", sheet_name="Q4") # 只保留关键列 df_clean = df[["日期", "产品", "销售额", "地区"]] # 转Markdown md_table = df_clean.to_markdown(index=False) with open("sales_q4.md", "w", encoding="utf-8") as f: f.write("# 2023年第四季度销售数据\n\n" + md_table)
```
把生成的sales_q4.md放进./data/knowledge/，重建知识库即可。这样问“华东地区10月销售额最高的是哪个产品”，AI就能精准回答。

4.4 Database集成：MySQL配置详解与延迟根因分析

Openclaw支持MySQL、PostgreSQL、SQLite。MySQL是最常用，也是最容易出问题的。

MySQL配置要点
skills/mysql_query.yaml里，exec.command指向的Python脚本必须处理好连接池。我用SQLAlchemy+pymysql：

from sqlalchemy import create_engine, text import json import sys input_data = json.loads(sys.stdin.read()) sql = input_data.get("sql", "") # 使用连接池，避免频繁创建连接 engine = create_engine( "mysql+pymysql://user:password@localhost:3306/dbname?charset=utf8mb4", pool_pre_ping=True, # 每次用前检测连接是否有效 pool_recycle=3600, # 连接存活1小时后回收 max_overflow=10 # 连接池最多溢出10个连接 ) try: with engine.connect() as conn: result = conn.execute(text(sql)) rows = [dict(row) for row in result.fetchall()] print(json.dumps({"result": rows}, ensure_ascii=False)) except Exception as e: print(json.dumps({"error": str(e)}, ensure_ascii=False))

为什么会有延迟？——三层根因分析
用户常问“Openclaw为什么会延迟”，答案不在Openclaw本身，而在三层外部依赖：

延迟层	典型表现	排查命令	解决方案
网络层	MySQL在远程服务器，ping延迟>50ms	`ping mysql-server-ip`	将MySQL迁至同一局域网，或用SSH隧道加密压缩
数据库层	`SHOW PROCESSLIST`看到大量`Sending data`	`EXPLAIN SELECT ...`	为WHERE字段加索引，避免SELECT *
模型层	WebUI显示“thinking...”超30秒	`nvidia-smi`看GPU利用率<10%	检查`n_gpu_layers`是否设得太低，导致大量计算在CPU

我遇到过最典型的延迟案例：一个查询SELECT * FROM user_logs WHERE created_at > '2024-01-01'，表有2000万行，没索引。Openclaw等了2分17秒才返回。加了created_at索引后，降到0.8秒。Openclaw的“延迟”其实是它在等数据库响应，它自己没在“思考”。

5. 常见问题与独家排查技巧：那些官方文档不会写的坑

以下问题，全部来自我部署23台机器、处理156个用户咨询的真实记录。每一个都有对应日志、截图和一击必杀的解决方案。

5.1 “WebUI打不开，但终端显示‘WebUI started’”

这是Windows和macOS用户最高频问题。根本原因不是端口被占，而是Openclaw的--host参数默认绑定127.0.0.1，而现代浏览器（Chrome/Firefox/Safari）对localhost的解析有时会走IPv6（::1），导致连接失败。

现象：终端输出INFO: Uvicorn running on http://127.0.0.1:8080，但浏览器访问http://localhost:8080空白，F12看Network全是ERR_CONNECTION_REFUSED。
诊断：在终端里执行curl -v http://127.0.0.1:8080，如果返回HTML，证明服务正常；再执行curl -v http://localhost:8080，如果失败，就是DNS解析问题。
终极方案：启动时强制指定IPv4：
```
openclaw webui --host 0.0.0.0 --port 8080
```
0.0.0.0表示监听所有IPv4地址，localhost和127.0.0.1都能访问。这是最稳妥的做法。

5.2 “Skill调用报错‘Command not found’，但文件明明存在”

这是Linux/macOS用户的经典权限坑。Openclaw用subprocess.Popen执行Skill脚本，但默认不带shell环境，所以#!/usr/bin/env python3的shebang可能失效。

现象：skills/my_skill.py文件存在，chmod +x也执行了，但WebUI里Test Skill报/bin/sh: 1: ./skills/my_skill.py: not found。
根因：subprocess.Popen在shell=False（默认）下，不会调用/bin/sh去解析shebang，而是直接把./skills/my_skill.py当二进制执行。

解决方案：在YAML里显式指定解释器：

exec: command: python3 ./skills/my_skill.py # 不要写 ./skills/my_skill.py

或者，确保脚本第一行是#!/usr/bin/env python3，并在YAML里写：

exec: command: ./skills/my_skill.py shell: true # 强制走shell

5.3 “模型加载慢，GPU显存没占满”

这通常发生在RTX 4090用户身上。n_gpu_layers设得太高，但模型权重还没加载完，GPU就在等CPU喂数据，造成“显存空转”。

现象：nvidia-smi显示GPU Memory Usage只有30%，但nvidia-smi dmon -s u显示GPU Utilization <5%。
原理：llama.cpp的GPU卸载是分层进行的。如果n_gpu_layers=100，但模型只有80层，它会把前80层卸载，后20层无效。更糟的是，如果ctx_size设得太大（如8192），CPU内存带宽成为瓶颈，GPU只能干等。
实测最优解：对Qwen2-7B（32层），n_gpu_layers=32；对Qwen2-72B（80层），n_gpu_layers=80。ctx_size不要超过模型原生支持的最大值（Qwen2-7B是32768，但实际