在 macOS 上配置 OpenClaw 连接本地 Ollama 完整指南

前言

最近在 macOS 上体验了 OpenClaw（"小龙虾"）这个开源 AI 助手框架，配合本地运行的 Ollama，实现了完全离线、免费的 AI 对话。本文将详细记录从零开始的配置过程，包括每一个选项的选择和背后的原因，希望能帮助遇到同样需求的朋友。

环境：

macOS (Apple Silicon)
已安装 Ollama，并下载了模型 gpt-oss:120b-cloud
目标：让 OpenClaw 通过 Web UI 调用本地 Ollama 模型

第一步：安装 Node.js 和 OpenClaw

OpenClaw 需要 Node.js 22+ 环境。

bash

复制代码

# 使用 Homebrew 安装 Node.js 22（或从官网下载 pkg）
brew install node@22

# 设置 npm 国内镜像加速（可选）
npm config set registry https://registry.npmmirror.com

# 全局安装 OpenClaw
npm install -g openclaw

如果遇到权限错误，使用 sudo npm install -g openclaw。

第二步：运行配置向导

在终端执行：

bash

复制代码

openclaw onboard

接下来会进入交互式配置，以下是每个问题的回答记录。

1. Onboarding mode

text

复制代码

● QuickStart (Configure details later via openclaw configure.)
○ Manual

选择：Manual

理由：QuickStart 只会配置基本项，后续还需要手动调整；Manual 可以一次性完成所有自定义设置，包括连接本地 Ollama。

2. What do you want to set up?

text

复制代码

● Local gateway (this machine) (No gateway detected (ws://127.0.0.1:18789))
○ Remote gateway (info-only)

选择：Local gateway

理由：Ollama 在本机运行，需要在本机部署 OpenClaw 网关。

3. Model/auth provider

列表很长，需要向下滚动找到 Custom Provider （通常在列表最底部）。
选择：Custom Provider

理由：Ollama 不属于列表中的任何商业服务，需要手动指定 API 地址。

4. API Base URL

text

复制代码

http://127.0.0.1:11434/v1█

直接回车确认

Ollama 默认 API 地址就是 http://127.0.0.1:11434/v1，OpenClaw 已自动填入。

5. How do you want to provide this API key?

text

复制代码

● Paste API key now (Stores the key directly in OpenClaw config)
○ Use external secret provider

选择：Paste API key now

理由：Ollama 不需要真实 API Key，我们只需随便填一个占位符。

6. API Key (leave blank if not required)

输入：ollama（或其他任意字符，如 123）

Ollama 不验证，但不能留空。

7. Endpoint compatibility

text

复制代码

● OpenAI-compatible (Uses /chat/completions)
○ Anthropic-compatible
○ Unknown (detect automatically)

选择：OpenAI-compatible

理由：Ollama 的 API 端点兼容 OpenAI 格式。

8. Model ID

根据 ollama list 查看已安装的模型，我本地是：

text

复制代码

gpt-oss:120b-cloud    569662207105    -       22 minutes ago

输入：gpt-oss:120b-cloud

必须与 ollama list 显示的完全一致。

9. Endpoint ID

text

复制代码

custom-127-0-0-1-11434█

直接回车确认

默认 ID 足够标识这个自定义端点。

10. Model alias (optional)

text

复制代码

e.g. local, ollama

输入：local（或直接回车跳过）

别名方便在 Web UI 中识别，我输入了 local。

此时提示：

text

复制代码

Configured custom provider: custom-127-0-0-1-11434/gpt-oss:120b-cloud

11. Gateway port

text

复制代码

18789█

直接回车确认

默认端口，后续通过 http://localhost:18789 访问。

12. Gateway bind

text

复制代码

● Loopback (127.0.0.1)
○ LAN (0.0.0.0)
○ Tailnet (Tailscale IP)
○ Auto (Loopback → LAN)
○ Custom IP

选择：Loopback (127.0.0.1)

只在本机监听，最安全，适合个人使用。

13. Gateway auth

text

复制代码

● Token (Recommended default (local + remote))
○ Password

选择：Token

使用令牌认证，OpenClaw 会生成随机 token。

14. Tailscale exposure

text

复制代码

● Off (No Tailscale exposure)
○ Serve
○ Funnel

选择：Off

不需要通过 Tailscale 暴露服务。

15. How do you want to provide the gateway token?

text

复制代码

● Generate/store plaintext token (Default)
○ Use SecretRef

选择：Generate/store plaintext token

让 OpenClaw 自动生成并存储 token。

16. Gateway token (blank to generate)

直接回车留空

OpenClaw 会自动生成随机 token。

17. Configure chat channels now?

text

复制代码

● Yes / ○ No

选择：No

聊天渠道（如 Discord、Telegram）暂不需要，跳过。

18. Search provider

text

复制代码

● Brave Search (Structured results · country/language/time filters)
○ Gemini (Google Search)
○ Grok (xAI)
○ Kimi (Moonshot)
○ Perplexity Search
○ Skip for now

选择：Skip for now

暂不需要联网搜索，以后可随时配置。

19. Configure skills now? (recommended)

text

复制代码

● Yes / ○ No

选择：No

跳过技能（计算器、天气等），先体验基础对话。

20. Enable hooks?

text

复制代码

◻ Skip for now
◻ 🚀 boot-md
◻ 📎 bootstrap-extra-files
◻ 📝 command-logger
◻ 💾 session-memory

操作：只选中 Skip for now

用空格取消其他选项，仅保留 Skip for now，然后回车。

21. Install Gateway service (recommended)

text

复制代码

● Yes / ○ No

选择：Yes

安装为系统服务，实现开机自启和后台运行。

22. Gateway service runtime

text

复制代码

● Node (recommended) (Required for WhatsApp + Telegram. Bun can corrupt memory on reconnect.)

选择：Node

官方推荐 Node 运行时。

23. Gateway service already installed

text

复制代码

● Restart
○ Reinstall
○ Skip

选择：Restart

之前可能安装过，重启使新配置生效。

24. How do you want to hatch your bot?

text

复制代码

● Hatch in TUI (recommended)
○ Open the Web UI
○ Do this later

选择：Open the Web UI

自动打开浏览器进入 Web 界面，更直观。

25. Enable bash shell completion for openclaw?

text

复制代码

● Yes / ○ No

选择：Yes

启用命令补全，方便后续使用。

第三步：完成并登录

配置完成后，终端会显示类似信息：

text

复制代码

Gateway service restarted successfully.
Access URL: http://localhost:18789

浏览器自动打开该地址，但需要输入 Token。在终端执行：

bash

复制代码

openclaw token generate

复制输出的令牌，粘贴到网页中，即可开始对话。

常见问题

无法连接 Ollama ：检查 Ollama 是否在运行（任务栏图标或 ps aux | grep ollama），以及设置中是否开启了网络暴露（Ollama → Settings → Allow other programs to connect）。
模型不响应 ：确认 Model ID 与 ollama list 完全一致，包括标签（如 :latest）。