📝 前言

最近在折腾本地部署 OpenClaw 。它可以把你本地的 Ollama 模型接到飞书里，数据完全在自己手上，不用花一分钱 API 费用。

但！是！官方文档有些细节藏得比较深，尤其是 Ollama 的配置方式，如果跟着网上一些旧教程写，会导致身份配置完全不生效，Agent 根本不认识你是谁。

本文基于 Windows + Ollama + 飞书 实战，手把手带你绕过这些坑。

📑 目录

1. OpenClaw 是什么？

2. 环境准备

3. 安装 OpenClaw

4. 首次启动与 Gateway Token 配置（避坑点1）

5. 核心重点：Ollama 本地模型正确配置（避坑点2，必看！）

6. 配置 Agent 身份（USER.md / IDENTITY.md）

7. 接入飞书

8. Dashboard 使用指南

9. 常用命令速查

10. 常见问题排查（404、自称通义千问等）

11. 总结

---

一、OpenClaw 是什么？

OpenClaw 是一个开源的 AI 个人助手 「网关」 。你可以把它想象成一个万能插座，一头插着 Claude、GPT 或者本地 Ollama 这类大模型，另一头插着飞书、Telegram、Discord 等聊天软件。

核心亮点：

• 🔒 数据可控：完全本地部署，敏感数据不出门。

• 💰 零成本：配合 Ollama 使用本地模型，告别 API 账单。

• 🔌 多渠道：支持飞书、企微等多种平台。

• 🧠 带记忆：可以配置身份、长期记忆，打造专属人设。

二、环境准备

• Node.js：必须 v20 及以上（推荐 v22，太老版本会报错）。

• 内存：建议 8GB 以上（取决于你跑的模型大小）。

• 系统：Windows / macOS / Linux 均可，本文以 Windows 为例。

安装前先检查版本：

powershell

node -v
# 必须显示 v20.x 或更高

三、安装 OpenClaw

3.1 方式一：npm 全局安装（推荐）

打开 PowerShell 或 CMD，直接执行：

powershell

npm install -g openclaw@latest

如果你是国内网络，强烈建议加上淘宝镜像，不然可能卡死：

powershell

npm install -g openclaw@latest --registry https://registry.npmmirror.com

3.2 方式二：一键脚本（Mac/Linux）

bash

curl -fsSL https://openclaw.ai/install.sh | bash

3.3 验证安装

powershell

openclaw --version
# 出现版本号即成功

四、首次启动与 Gateway Token 配置（避坑点1）

4.1 运行初始化向导（可选）

powershell

openclaw onboard

这个向导会问你一些问题生成配置，也可以直接跳过，我们后面手动改文件。

4.2 启动 Gateway（核心服务）

powershell

openclaw gateway

看到类似 Gateway is running on http://localhost:18789 的日志，说明启动成功。

⚠️ 4.3 关键一步：配置 Gateway Token

打开浏览器访问 http://localhost:18789，此时大概率会弹窗提示 “gateway token missing”。

解决方法：

1. 找到你的配置文件。默认路径在：
   C:\Users\你的用户名\.openclaw\openclaw.json

2. 用记事本打开，找到 gateway.auth.token 这一行，复制后面那一长串字符串。

   json

   "gateway": {
     "auth": {
       "mode": "token",
       "token": "cl_xxx_xxxx"   // 复制这个值
     }
   }

3. 回到浏览器页面，进入 Settings（设置），在 Gateway Token 输入框里粘贴刚才复制的字符串，保存。

刷新页面，熟悉的 Dashboard 界面就出来了。

五、🔥 核心重点：Ollama 本地模型正确配置（避坑点2，必看！）

这是全网 80% 的人配置失败的原因。

❌ 5.1 常见错误示范（会导致身份失效）

很多教程（包括一些过时的 AI 回答）会让你这样写：

json

"baseUrl": "http://localhost:11434/v1"
"api": "openai-responses"

这是完全错误的！ 如果你用了 /v1 和 openai-responses，会导致：

1. 身份配置失效：你写的 USER.md、IDENTITY.md 不会被模型读到，Agent 会忘记自己是谁。

2. 工具调用 404：调用搜索引擎等插件时会报错。

3. 模型可能返回 404：因为 Ollama 的 /v1 兼容层没那么稳定。

✅ 5.2 正确配置：使用 Ollama 原生 API

正确的做法是直接调用 Ollama 的原生接口，不要走 /v1 兼容层。

编辑 C:\Users\你的用户名\.openclaw\openclaw.json，修改或添加以下内容：

json

{
  // 环境变量，随便写个非空的就行
  "env": {
    "OLLAMA_API_KEY": "any-string-is-ok"
  },
  "models": {
    "providers": {
      "ollama": {
        // ⚠️ 重点：baseUrl 不要加 /v1
        "baseUrl": "http://127.0.0.1:11434",
        "apiKey": "any-string-is-ok",
        // ⚠️ 重点：api 类型必须是 "ollama"，不是 "openai-responses"
        "api": "ollama",
        // 列出你本地已经下载的模型
        "models": [
          { "id": "qwen2.5:7b", "name": "通义千问2.5 7B" },
          { "id": "deepseek-r1:14b", "name": "DeepSeek R1 14B" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      // 设置默认模型
      "model": { "primary": "ollama/qwen2.5:7b" }
    }
  }
}

关键点总结：

• baseUrl：结尾是 11434，不要 /v1。

• api：值必须是 ollama。

• apiKey：任意字符串，不能为空。

5.3 记得同步修改 Agent 内部配置（重要）

OpenClaw 会在 workspace 里生成 Agent 的具体配置。保险起见，建议也检查一下这两个文件，把里面的 api 改成 ollama：

• C:\Users\你的用户名\.openclaw\workspace\agents\main\agent\config.json

• C:\Users\你的用户名\.openclaw\workspace\agents\main\agent\models.json

确保里面没有 openai-responses 的残留。

六、配置身份与记忆（USER.md / IDENTITY.md）

OpenClaw 的灵魂在于通过 Markdown 文件注入人设。

6.1 文件存放位置

进入你的工作区目录：

text

C:\Users\你的用户名\.openclaw\workspace\

你会看到这几个核心文件：

• USER.md：你是谁？你的背景、喜好、工作。

• IDENTITY.md：Agent 是谁？它的名字、性格、任务。

• SOUL.md：更底层的灵魂设定，比如行为准则、边界。

• memory/ 文件夹：每天的对话记忆会存在这里。

6.2 USER.md 示例（定义你自己）

markdown

- **Name:** 博哥
- **Alias:** 博哥
- **Timezone:** Asia/Shanghai
- **Bio:** 杭州某科技公司程序员，日常写代码、摸鱼、修服务器。

## 最近关注
- 在学 Rust，感觉脑子不够用。
- 公司服务器老是报警，求个心理阴影面积。

6.3 IDENTITY.md 示例（定义 AI 人设）

markdown

- **Name:** OpenClaw / 小爪
- **Creature:** 一只机械爪形状的 AI 助手
- **Vibe:** 幽默、毒舌但靠谱，喜欢用表情包说话
- **Emoji:** 🤖 🐾

你是张博的专属 AI 助手，叫“小爪”。你的任务是用最接地气的方式帮他解决问题。可以开玩笑，但遇到技术问题必须给出准确答案。

注意： 改完这些文件后，如果 Agent 依然没反应，或者自称“我是通义千问”，99% 的原因就是第五节提到的配置错误（走了 /v1 兼容层），请立刻回去检查。

七、配置飞书

7.1 创建飞书应用

1. 访问 飞书开放平台，点击「创建企业自建应用」。

2. 起个名字，比如“小爪助手”。

3. 创建成功后，进入「凭证与基础信息」，拿到 App ID 和 App Secret。

4. 进入「权限管理」，开通：

   • contact:user.base:readonly（获取用户基本信息）

   • im:message 相关的发送和接收权限（大概三四个，都勾上）

   • im:chat 相关的群聊权限（如果你想让 AI 进群）

7.2 配置 openclaw.json

回到 openclaw.json，在 channels 和 plugins 里添加飞书配置：

json

{
  // ... 其他配置
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "你的 AppId",
      "appSecret": "你的 AppSecret",
      // 私聊策略：pairing 表示需要配对才能用（推荐，防止被陌生人骚扰）
      "dmPolicy": "pairing",
      // 群聊策略：deny 表示默认拒绝所有群聊，需要手动批准
      "groupPolicy": "deny",
      // 连接模式：polling 轮询（稳定），websocket（更实时但可能不稳定）
      "connectionMode": "polling"
    }
  },
  "plugins": {
    "entries": {
      "feishu": { "enabled": true }
    }
  }
}

7.3 启动飞书连接服务

保持 Gateway 在运行，新开一个终端，执行：

powershell

openclaw feishu

看到日志输出 Feishu client started 表示连接成功。

7.4 用户配对

用户第一次在飞书私聊你的机器人时，机器人会返回一串配对码。你需要拿着这个码在终端里批准：

powershell

openclaw pairing approve feishu 这里输入配对码

批准后，就可以正常聊天了。

八、Dashboard 使用指南

再次打开 http://localhost:18789，这里有一些常用设置：

• Workspace：确保指向你的工作目录（默认是 ~/.openclaw/workspace），这里决定了加载哪些 .md 文件。

• Primary Model：在这里可以快速切换 Agent 使用的模型。

• Identity：可以在这里修改 Agent 的显示名和 Emoji，效果和改 IDENTITY.md 一样。

• Reload Config：改完配置后，一定要点这个按钮或者重启 Gateway，否则不会生效。

九、常用命令速查

命令	作用
openclaw gateway	启动 Gateway 主服务
openclaw gateway restart	重启 Gateway
openclaw feishu	启动飞书连接
openclaw doctor	运行健康检查，诊断配置问题
openclaw models list	查看当前可用的模型列表
openclaw devices list	查看待配对的设备/用户
openclaw logs --follow	查看实时日志，排查错误必备

十、常见问题排查

Q1：HTTP 404: 404 page not found

• 检查 Ollama 是否运行：在终端输入 ollama list，如果能列出模型，说明 Ollama 没问题。

• 检查 baseUrl：openclaw.json 里的 baseUrl 是不是写了 http://127.0.0.1:11434 （千万不要加 /v1）。

• 检查 api 类型：是不是 "api": "ollama"，不是 openai-responses。

Q2：gateway token missing

• 去 Dashboard 的 Settings 页面，手动粘贴 openclaw.json 里的 gateway.auth.token 值。

Q3：Agent 自称是通义千问 / 不知道我是谁 / 说话不像设定的人设

• 根本原因：模型没有读到 USER.md 和 IDENTITY.md。

• 解决方法：回到 第五节，严格按照 Ollama 原生 API 的方式配置。这通常是走了 OpenAI 兼容层导致的。

Q4：模型选择器里没有我下载的模型

• 在 openclaw.json 的 models.providers.ollama.models 数组里，显式列出你下载的模型 ID。

• 也可以在 agents.defaults.models 里为模型起个别名：

  json

  "models": {
    "ollama/qwen2.5:7b": { "alias": "我的小助手" }
  }

• 修改后重启 Gateway。

十一、总结

1. Ollama 配置是重中之重：牢记 api: "ollama"，baseUrl 不加 /v1。这是身份配置生效的前提。

2. 身份靠文件：人设全靠 workspace 里的 .md 文件，改完记得重载配置。

3. 飞书需配对：安全机制需要手动 approve 配对码。

4. 遇事不决看日志：openclaw logs --follow 能看到详细错误信息。

希望这篇指南能帮你少踩坑，顺利把小爪接到飞书里！

📚 参考链接

• 官方文档：https://docs.openclaw.ai

• Ollama 配置专题：https://docs.openclaw.ai/providers/ollama

• GitHub 仓库：https://github.com/openclaw/openclaw