OpenClaw 配置本地 Ollama 模型指南：Auth 设置与离线部署
前置要求（硬件与软件准备）
硬件建议（本地模型跑得顺的关键）：
- GPU：NVIDIA RTX 4060 及以上（8GB+ 显存推荐），Apple Silicon M2/M3/M4 也极佳。
- 内存：16GB 起步，32GB 更流畅（OpenClaw 系统提示词 + 工具调用很容易吃 10k+ tokens）。
- 磁盘：20GB+ 剩余空间（模型文件很大）。
- CPU：至少 8 核（无 GPU 时备选）。
软件要求：
- Ollama 0.17 或更高（官方强烈推荐）
- Node.js 18+（npm 安装 OpenClaw）
- Windows 用户建议用 PowerShell 以管理员身份运行；macOS/Linux 用终端即可。
- 可选：Git（安装技能时用到）
检查命令（全部复制粘贴执行）：
node --version # 应 >= v18
npm --version # 应 >= 8
ollama --version # 应 >= 0.17
步骤 1：安装 Ollama 并拉取本地模型
拉取推荐本地模型（强烈建议先用 7B-14B 量化版测试）：
# 通用推荐（速度快、效果好）
ollama pull qwen2.5:7b
ollama pull qwen3:8b # 2026 新模型，推理更强
ollama pull glm-4.7-flash # ~25GB VRAM，适合强推理
ollama pull llama3.3:8b # Meta 经典
进阶：创建大上下文模型（OpenClaw 必须 ≥16k tokens） OpenClaw 默认需要 16k+ 上下文，否则会报错。我们用 Modelfile 扩展：
# Windows（PowerShell）
cd ~
@"
FROM qwen2.5:7b
PARAMETER num_ctx 32768
"@ | Out-File -Encoding ascii Modelfile
ollama create qwen2.5:7b-32k -f Modelfile
macOS/Linux 同理用 cat > Modelfile 创建文件。验证：
ollama list
ollama show qwen2.5:7b-32k --modelfile
现在模型就绪，Ollama 服务默认监听 http://127.0.0.1:11434。
步骤 2：安装 OpenClaw
最推荐方式（官方一键法，2026 新特性）：
ollama launch openclaw
Ollama 会自动检查并通过 npm 安装 OpenClaw，弹出模型选择器，启动 TUI（终端界面）。
直接在终端聊天即可！想换本地模型？执行 ollama launch openclaw --model qwen2.5:7b-32k 即可。
手动安装方式（适合想深度配置的用户）：
npm install -g openclaw@latest
openclaw --version # 验证版本
步骤 3：配置 OpenClaw 连接本地 Ollama 模型（最核心一步）
方式一：配置向导（推荐新手）
openclaw onboard
按提示操作：
| 步骤 | 操作选择 |
|---|---|
| Model/auth provider | 选择 Custom Provider（列表最后一项） |
| API Base URL | 输入 http://127.0.0.1:11434/v1 |
| API Key | 必须填写 ollama-local（新版强制要求） |
| Endpoint compatibility | 选择 OpenAI-compatible |
| Model ID | 输入你创建的模型名（如 qwen2.5:7b-32k） |
| 其他问题（技能、渠道） | 全部 Skip for now 或 No |
配置完成后会显示 Web UI 地址（通常 http://127.0.0.1:18789）。
方式二：手动编辑配置文件（高级用户，必备） 配置文件位置：
- Windows:
C:\Users\你的用户名\.openclaw\openclaw.json - macOS/Linux:
~/.openclaw/openclaw.json
【新增】Auth 配置部分（2026 最新推荐写法）
虽然 Ollama 是本地模型，不需要真实密钥，但 OpenClaw 完全基于 OpenAI-compatible 协议设计，必须提供规范的 auth 对象才能通过认证校验。官方推荐使用固定标识 "apiKey": "ollama-local"，既安全又统一。
完整推荐配置（已包含 auth 部分，直接复制替换）：
{
"models": {
"providers": {
"ollama": {
"baseUrl": "http://127.0.0.1:11434/v1",
"auth": {
"type": "api_key",
"apiKey": "ollama-local"
},
"api": "openai-completions",
"models": [
{
"id": "qwen2.5:7b-32k",
"name": "Qwen2.5 7B 32K (本地)",
"reasoning": true,
"input": ["text"],
"cost": { "input": 0, "output": 0 },
"contextWindow": 32768,
"maxTokens": 32768
}
]
}
}
},
"agents": {
"defaults": {
"model": { "primary": "ollama/qwen2.5:7b-32k" }
}
}
}
Auth 配置字段详解：
type: 固定写"api_key"（或"bearer"，两者均可，推荐api_key）apiKey: 必须写"ollama-local"（这是 OpenClaw 本地模型的官方标识，千万不要留空或随便改）
保存文件后，立即重启 OpenClaw：
openclaw tui
步骤 4：启动并测试（TUI + Web UI）
openclaw tui
看到欢迎语 Wake up, my friend! 就成功了！输入任意问题测试。
同时打开浏览器访问 Web UI（配置向导里给的地址），更直观。
步骤 5：连接消息应用（让 AI 随时随地可用）
openclaw configure --section channels
支持 Telegram、WhatsApp、Slack、Discord、iMessage 等。 选择 Telegram → 按提示输入 Bot Token 和 Chat ID（去 @BotFather 创建机器人）→ 选择 Finished 保存。
步骤 6：安装技能（让 AI 真正'动手'）
# 安装技能管理器
npx clawhub install clawhub
# 推荐必装技能（复制执行）
npx clawhub install filesystem-mcp # 文件系统
npx clawhub install github # GitHub（需 gh CLI）
npx clawhub install summarize # 总结 PDF/网页
npx clawhub install weather # 天气（无需 API）
npx clawhub install openai-whisper # 本地语音识别
安装后重启 TUI，在聊天里说'帮我安装 GitHub 技能' 或直接用 openclaw skills list 检查状态。
常见问题 & 终极排查
- 'Authentication failed' 或 'Invalid API Key'
→ 检查
auth.apiKey是否精确为"ollama-local"（大小写敏感），type是否为api_key。重启 TUI 后重试。 - 'Model context window too small (4096 tokens)'
→ 手动修改
~/.openclaw/agents/main/agent/models.json和主配置文件，把contextWindow和maxTokens改成 32768，重启 TUI。 - Verification failed
→ 确认 Ollama 正在运行（
ollama list），Base URL 带/v1，auth对象完整无误。 - 技能 missing
→ 安装对应依赖（如 GitHub 需要
ghCLI），然后重启。 - Windows 端口占用 → 任务管理器结束 ollama.exe 进程后重启。
- 响应慢 / 空白 → 换小模型（7B），或确认 GPU 驱动最新，上下文别超过模型上限。
- 想换模型
→
ollama launch openclaw --config或直接改配置文件 primary 字段 + auth 部分。
高级玩法
- 多模型切换：在 config.json 加多个模型，TUI 里说'切换到 GLM 模型'。
- Docker / 1Panel 部署：服务器党可参考社区教程。
- 语音输入输出：安装 whisper + sherpa-onnx-tts 技能。
- 安全加固：官方文档建议隔离工作区，工具调用前仔细审查。