1. 为什么零基础也需要一个本地 AI 助理很多人第一次听到「本地 AI 助理」会以为要买服务器、要会训练模型其实门槛比想象中低得多。OpenClaw 是一个开源的本地 AI 助理框架它本身不包含模型权重而是负责把「模型推理 对话记忆 工具调用」串成一条可运行的链路。你只要给它一个 GGUF 格式的模型文件它就能在你自己的电脑上跑起来全程离线对话内容不出本机。它适合谁三类人最合适一是想学大模型应用但不想被云 API 账单追着跑的开发者二是手里有 8GB 以上内存、想拿旧笔记本练手的在校学生三是对数据隐私敏感、希望文档问答在本地闭环的技术爱好者。OpenClaw 的技术栈是 Python代码结构清晰改起来不费劲。但零基础最容易卡在三个地方第一系统 Python 里装了一堆包装 OpenClaw 时版本冲突报错看不懂第二模型文件下载下来不知道放哪路径写错导致加载失败第三第一次启动脚本时不知道要激活虚拟环境ModuleNotFoundError反复出现。这篇教程就按「环境隔离 → 模型放置 → 启动配置 → 验证请求 → 排错」的顺序把这三个坑一次填平。你跟着敲命令最后能对着终端里的助理问出第一句话就算跑通了。我试过在一台 16GB 内存的 Windows 笔记本上从零走完整套流程中间因为没建虚拟环境重装过一次依赖所以下面每一步都会把「为什么这么做」讲清楚避免你重复踩坑。2. 用 Python 虚拟环境隔离 OpenClaw 依赖2.1 先确认 Python 版本和 pip 可用OpenClaw 对 Python 版本有要求推荐 3.9 或 3.10兼容性最好。3.11 也能跑但部分底层推理库的预编译轮子可能还没跟上零基础建议直接用 3.10。打开终端Windows 用 PowerShell 或 CMDmacOS/Linux 用 Terminal输入python --version pip --version如果python命令找不到Windows 上试试py --versionmacOS 上可能是python3 --version。确认版本号在 3.9–3.11 之间即可。pip 版本旧的话顺手升级python -m pip install --upgrade pip2.2 创建并激活虚拟环境虚拟环境的作用是给 OpenClaw 单独开一个「房间」里面装的包不会污染系统全局。假设你的项目目录叫openclaw-demo先进入它再创建环境cd path/to/openclaw-demo python -m venv openclaw-env创建完成后目录里会多出一个openclaw-env文件夹。接着激活# Windows PowerShell openclaw-env\Scripts\Activate.ps1 # Windows CMD openclaw-env\Scripts\activate.bat # macOS / Linux source openclaw-env/bin/activate激活成功的标志是终端提示符前面出现(openclaw-env)。这个状态只对当前终端窗口有效关掉窗口再打开就要重新激活。很多人第一次失败就是因为新开了一个终端却忘了激活然后pip install装到了系统环境里。2.3 安装 OpenClaw 与推理后端在激活状态下安装核心库pip install openclaw如果你后面想用文档问答、网络搜索这些扩展能力可以装全量版pip install openclaw[all]GGUF 模型的推理后端是llama-cpp-pythonOpenClaw 会把它作为依赖带进来。如果你有 NVIDIA 显卡并想用 GPU 加速需要单独装带 CUDA 支持的版本命令里要指定编译参数这一步对零基础稍复杂建议先用 CPU 跑通再考虑 GPU。安装完成后验证一下pip list | grep openclaw能看到版本号就说明装好了。把当前依赖导出方便以后复现pip freeze requirements.txt注意requirements.txt要放在项目根目录不要放进openclaw-env文件夹里否则下次重建环境时容易混淆。2.4 虚拟环境常用操作速查日常你会反复用到这几条记不住可以存成便签操作命令查看已装包pip list导出依赖pip freeze requirements.txt按文件安装pip install -r requirements.txt退出环境deactivate删除环境停用后直接删openclaw-env文件夹每个独立项目都建议建一个专属环境。IDE 如 VSCode、PyCharm 能自动识别openclaw-env作为解释器选对解释器后代码提示和运行才在正确环境里。3. GGUF 模型目录结构与启动配置3.1 下载 GGUF 模型并规划目录OpenClaw 是框架真正干活的是模型。零基础推荐从 Qwen2.5-7B-Instruct 的 GGUF 量化版入手Q4_K_M 量化等级在精度和体积之间平衡得不错文件大约 4–5GB。你可以从 Hugging Face 或 ModelScope 手动下载也可以用 OpenClaw 内置的模型管理器from openclaw.utils.model_loader import download_model download_model(Qwen/Qwen2.5-7B-Instruct-GGUF, ./models)手动下载的话把.gguf文件放进项目下的models目录。推荐的目录结构是这样openclaw-demo/ ├── openclaw-env/ ├── models/ │ └── qwen2.5-7b-instruct-q4_k_m.gguf ├── config/ │ └── assistant.toml ├── first_assistant.py └── requirements.txt模型文件名建议保持下载时的原始命名不要随意改成中文或带空格路径里有空格时 Python 字符串处理容易出问题。3.2 用 TOML 写一份可复制的启动配置把模型路径、上下文长度、GPU 层数这些参数抽到配置文件里脚本会更干净。在config/assistant.toml写入[llm] model_path ./models/qwen2.5-7b-instruct-q4_k_m.gguf n_ctx 4096 n_gpu_layers 0 n_batch 512 verbose false [assistant] name 我的第一个本地助理 system_prompt 你是一个乐于助人且知识渊博的AI助手请用清晰简洁的中文回答。 [memory] max_turns 20n_gpu_layers 0表示纯 CPU 推理先用这个跑通。有显卡且装好 CUDA 版后端后可以改成 40 左右把大部分层放到 GPU 上。n_ctx是上下文窗口4096 对日常对话够用调大更吃内存。3.3 读取配置并初始化助理创建first_assistant.py把配置读进来import asyncio import tomllib from openclaw import OpenClaw from openclaw.llms import LlamaCppLLM def load_config(path./config/assistant.toml): with open(path, rb) as f: return tomllib.load(f) async def main(): cfg load_config() llm LlamaCppLLM( model_pathcfg[llm][model_path], n_ctxcfg[llm][n_ctx], n_gpu_layerscfg[llm][n_gpu_layers], n_batchcfg[llm][n_batch], verbosecfg[llm][verbose], ) assistant OpenClaw( llmllm, namecfg[assistant][name], system_promptcfg[assistant][system_prompt], ) print(f助理 {assistant.name} 已就绪输入 退出 结束。) while True: user_input input(\n[你]: ) if user_input.lower() in [退出, quit, exit]: break reply await assistant.chat(user_input) print(f\n[助理]: {reply}) if __name__ __main__: asyncio.run(main())tomllib是 Python 3.11 起内置的如果你用 3.10需要pip install tomli并把导入改成import tomli as tomllib。这一步是零基础容易忽略的版本差异。4. 验证请求与首次对话成功结果4.1 启动脚本并观察加载日志确保虚拟环境已激活在项目根目录运行python first_assistant.py第一次加载模型会花几秒到几十秒取决于磁盘速度和模型大小。终端会先打印模型加载信息然后出现「助理已就绪」。如果卡在加载阶段超过两分钟多半是模型路径不对或文件损坏先按第 5 节排查。4.2 用三个问题验证链路是否通第一问测基础对话[你]: 你好请介绍一下你自己 [助理]: 你好我是一个运行在你本地的AI助手……第二问测中文理解和代码能力[你]: 用Python写一个计算斐波那契数列的函数助理应该返回带def fib(n):的代码块。第三问测上下文记忆。默认脚本没有多轮记忆需要引入Conversation类from openclaw.memory import Conversation conversation Conversation(assistant) reply await conversation.chat(Python里列表和元组有什么区别) reply2 await conversation.chat(那我什么时候该用元组)第二问能正确接上「元组不可变、适合做字典键」这类上下文说明记忆模块工作正常。4.3 成功结果的判断标准跑通的标志有三个终端不再报错、助理能返回语义连贯的中文、连续两轮对话能引用上一轮内容。如果只满足前两个说明推理通了但记忆没启用三个都满足你的第一个本地 AI 助理就算真正跑起来了。此时可以按 CtrlC 退出下次重新激活环境再运行即可。5. 常见报错排查对照5.1 ModuleNotFoundError 与虚拟环境未激活最常见的报错长这样ModuleNotFoundError: No module named openclaw九成原因是终端没激活虚拟环境或者激活后换了新窗口。解决重新执行激活命令确认提示符前有(openclaw-env)再pip list看 openclaw 在不在列表里。不在就重装。5.2 模型加载失败与路径错误报错关键词通常是Failed to load model或file not found。检查三件事model_path是相对路径时基准是运行脚本的目录不是配置文件所在目录文件名大小写要和实际文件完全一致.gguf文件是否下载完整可以用文件大小对比官方说明。路径里避免中文和空格。5.3 401 与本地代理相关报错如果你在脚本里同时配置了云端 API 作为兜底可能遇到Error 401: Unauthorized local proxy failed: connection refused401 说明 Key 无效或没带上检查环境变量里TAOTOKEN_API_KEY是否设置正确。local proxy failed通常是本地网络配置问题先确认没有残留的代理环境变量干扰本地回环请求。把云端调用和本地 GGUF 推理分开测试能快速定位是哪一段出的问题。5.4 回复慢与内存不足CPU 推理 7B 模型每秒几个 token 是正常的。想提速把n_gpu_layers调大需 GPU 后端、换更高量化等级如 Q4_K_M、适当降低n_ctx。内存不足报错out of memory时换更小的模型或更高压缩的量化版本比如 Q3_K_S。5.5 接入云端模型时的三件套配置如果你希望本地 GGUF 之外再挂一个云端模型做对比无论用 Cline MCP、Codex 的auth.json还是 Claude Code 类工具配置里必须写全三件套Base URL、API Key、Model ID。以auth.json为例{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: claude-3-5-sonnet }Base URL 用https://taotoken.net/api不要多加路径后缀。Key 在控制台的 API Keys 页面生成Model ID 要和平台文档里列出的名称完全一致写错会报model not found。三件套缺任何一个请求都会在鉴权或路由阶段失败。6. 从跑通到用起来下一步怎么走跑通第一个助理后最自然的延伸是加工具。OpenClaw 的openclaw.tools模块里有计算器、搜索等现成工具传进OpenClaw(tools[...])就能让助理在需要时自动调用。再往上是文档问答装openclaw[rag]和pypdf用VectorStoreRetriever把本地 PDF 切片建索引助理就能基于你的资料回答。如果你想把本地推理和云端模型结合比如日常对话走本地 GGUF、复杂任务走云端可以在配置里做路由。云端接入的 Key 在控制台生成模型列表和接入文档在文档页有完整说明。想先感受模型对话效果可以直接用模型对话页面试几句打算长期做编码或 Agent 类任务Coding Plan 的额度模型更适合持续调用。最后给一个实用建议把requirements.txt、config/assistant.toml和启动脚本一起放进 Git 仓库模型文件用.gitignore排除。这样换台机器时克隆仓库、建虚拟环境、pip install -r requirements.txt、下载模型四步就能复现你的本地助理。