# OpenClaw 配置问题完全指南

_整理时间：2026-03-09 16:44 UTC_
_来源：George 提供_
_用途：小笔 ✍️ 和小智 🧠 学习材料_
_版本：完整教程版 v2.0_

—

## 🎓 如何使用本教程

**给技术小白的建议：**
– 🟢 绿色 = 安全操作，可以放心做
– 🟡 黄色 = 需要注意，小心操作
– 🔴 红色 = 危险操作，先确认再执行
– 💡 = 小贴士，帮你理解概念

**阅读顺序：**
1. 先看”问题现象”（这是什么问题？）
2. 再看”原因分析”（为什么会这样？）
3. 然后看”解决方案”（怎么修？）
4. 最后看”如何避免”（下次不踩坑）

—

## ⚠️ 重要提示：操作位置

**本文档中的命令分两类：**

### 🖥️ 宿主机操作（在 george 的 Linux 主机上执行）
“`bash
# 提示符通常是：george@host:~$ 或 $
# 例如：编辑 docker-compose.yml、查看日志等
“`

### 🐳 容器内操作（在 OpenClaw 容器内执行）
“`bash
# 提示符通常是：node@a433fd453cf0:/app$ 或 #
# 例如：安装插件、修改 openclaw.json 等
“`

**进入容器的方法：**
“`bash
# 宿主机执行
docker exec -it openclaw-openclaw-gateway-1 bash
# 或
docker exec -it a433fd453cf0 bash
“`

—

## 📋 问题 1：容器不断重启 (配置文件格式错误)

### 🔍 问题现象
“`
容器启动几秒就挂掉
反复重启，无法正常运行
日志显示配置错误
“`

### 🧐 原因分析

**根本原因：** 配置文件中有无效选项或语法错误

**具体例子：**
1. `dashscope-embedding` 的 api 值写成了 `”dashscope-embedding”`（应该是具体模型名）
2. JSON 格式错误，比如多余的 `}` 或缺少逗号

“`
错误配置示例：
{
“providers”: {
“dashscope-embedding”: {
“api”: “dashscope-embedding” ❌ 这不是有效的模型名
}
}
}
“`

### ✅ 解决方案

**步骤 1：验证配置**
“`bash
# 在容器内执行
openclaw doctor –non-interactive
“`

**步骤 2：检查 JSON 格式**
“`bash
# 在容器内执行
jq . ~/.openclaw/openclaw.json
“`
如果格式正确，会看到彩色格式化的输出；如果有错误，会提示哪一行有问题。

**步骤 3：修复配置**
– 删除无效的 provider 配置
– 使用有效的选项（如 `openai-completions` 或 `ollama`）
– 修复 JSON 语法错误

### 🛡️ 如何避免（预防建议）

**1. 修改前先备份** 🟢
“`bash
# 修改配置文件前，先复制一份备份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
“`
这样改错了可以恢复：`cp ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json`

**2. 每次修改后都用 doctor 检查** 🟢
“`bash
# 养成习惯：改配置 → doctor 验证 → 重启
openclaw doctor –non-interactive
“`
就像开车前系安全带一样简单！

**3. 使用在线 JSON 检查工具** 🟢
– 网站：https://jsonlint.com/
– 把配置内容粘贴进去，自动检查语法错误
– 适合不确定 JSON 格式是否正确时

### 📊 问题诊断流程图

“`
容器不断重启？
│
▼
[1] 查看日志确认错误
docker logs openclaw-openclaw-gateway-1
│
▼
[2] 进入容器检查配置
docker exec -it a433fd453cf0 bash
│
▼
[3] 运行 doctor 诊断
openclaw doctor –non-interactive
│
▼
[4] 检查 JSON 格式
jq . ~/.openclaw/openclaw.json
│
▼
[5] 修复错误 → 重启容器
完成！✅
“`

### 📝 学习要点
– ✅ 修改配置前先用 `openclaw doctor –non-interactive` 验证
– ✅ JSON 语法检查工具：`jq . ~/.openclaw/openclaw.json`
– ✅ 备份是好习惯，改错了能恢复

—

## 📋 问题 2：Ollama Embedding IP 变化

### 🔍 问题现象
“`
突然无法连接 Ollama
日志显示连接超时
之前明明配置好了，怎么又不行了？
“`

### 🧐 原因分析

**问题 1：容器网络隔离**
“`
┌─────────────────────┐ ┌─────────────────────┐
│ OpenClaw 容器 │ │ 宿主机 │
│ │ │ │
│ 试图访问： │ │ Ollama 服务 │
│ host.docker. │ ❌ │ 端口：11434 │
│ internal:11434 │──────│ │
│ │ │ │
└─────────────────────┘ └─────────────────────┘
│ │
└───── 不同网络，无法直接访问 ─┘
“`

**问题 2：宿主机 IP 可能变化**
– 路由器重启后，分配的 IP 可能改变
– 比如从 `192.168.x.x` 变成 `192.168.x.x`

### ✅ 解决方案

**方案 1：使用固定的宿主机 IP** 🟢
“`json
{
“providers”: {
“ollama-embedding”: {
“api”: “http://192.168.x.x:11434”
}
}
}
“`

**方案 2：创建自动修复脚本** 🟢
“`bash
# 宿主机创建脚本：/home/george/Documents/my_linux_scripts/scripts/ai/fix_openclaw_ollama_ip.sh
#!/bin/bash
# 自动获取当前 IP 并更新配置
CURRENT_IP=$(hostname -I | awk ‘{print $1}’)
sed -i “s|http://[0-9.]*:11434|http://$CURRENT_IP:11434|g” ~/.openclaw/openclaw.json
docker restart openclaw-openclaw-gateway-1
“`

**方案 3：在 service.conf 中添加健康检查** 🟢
“`bash
# 定期检查连接状态，自动修复
*/5 * * * * /home/george/Documents/my_linux_scripts/scripts/ai/fix_openclaw_ollama_ip.sh
“`

### 🛡️ 如何避免（预防建议）

**1. 给宿主机设置静态 IP** 🟢
– 在路由器设置中，给电脑分配固定 IP
– 比如永远使用 `192.168.x.x`
– 这样重启后 IP 不会变

**2. 使用内网域名代替 IP** 🟢
– 如果路由器支持，设置内网域名
– 比如 `ollama.local:11434`
– 即使 IP 变了，域名解析会自动更新

**3. 定期运行健康检查脚本** 🟢
– 用 cron 定时任务每 5 分钟检查一次
– 自动发现并修复 IP 变化问题
– 防患于未然

### 📊 网络连接示意图

“`
┌─────────────────────────────────────────────────────────────┐
│ 宿主机 (192.168.x.x) │
│ ┌───────────────┐ │
│ │ Ollama │ 端口：11434 │
│ │ 服务 │ │
│ └───────┬───────┘ │
│ │ │
│ │ ✅ 使用实际 IP 访问 │
│ │ http://192.168.x.x:11434 │
│ │ │
│ ┌───────┴───────┐ ┌──────────────────────┐ │
│ │ Docker 容器 │←────│ openclaw.json 配置 │ │
│ │ a433fd453cf0 │ │ ollama-embedding │ │
│ └───────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
“`

### 📝 学习要点
– ✅ 容器网络隔离是常态，不要依赖 `host.docker.internal`
– ✅ 使用宿主机实际 IP 是最可靠的方式
– ✅ 自动修复脚本在容器重建后非常有用

—

## 📋 问题 3：Mem0 长期记忆配置

### 🔍 问题现象
“`
记忆功能不工作
插件加载失败
配置不生效
“`

### 🧐 原因分析

**问题 1：插件 ID 不匹配**
“`
❌ 错误：配置中写 “mem0”
✅ 正确：实际插件 ID 是 “openclaw-mem0”
“`

**问题 2：OSS 配置不完整**
Mem0 需要三个组件才能工作：
– **Embedder** (嵌入模型)：把文字变成数字向量
– **VectorStore** (向量数据库)：存储这些向量
– **LLM** (大语言模型)：理解和生成文字

“`
┌─────────────────────────────────────────────────────────────┐
│ Mem0 完整架构 │
│ │
│ 用户提问 ──→ [Embedder] ──→ 向量 ──→ [VectorStore] │
│ │ │
│ ▼ │
│ [LLM] ──→ 回答 + 记忆 │
│ │
│ 三个组件缺一不可！ │
└─────────────────────────────────────────────────────────────┘
“`

### ✅ 解决方案

**步骤 1：安装插件**
“`bash
# 在宿主机执行
docker exec a433fd453cf0 openclaw plugins install [工作区路径]/extensions/mem0 –link
“`

**步骤 2：正确配置 openclaw.json**
“`json
“openclaw-mem0”: {
“enabled”: true,
“config”: {
“mode”: “open-source”,
“userId”: “george”,
“autoCapture”: true,
“autoRecall”: true,
“oss”: {
“embedder”: {
“provider”: “ollama-embedding”,
“config”: { “model”: “nomic-embed-text” }
},
“vectorStore”: {
“provider”: “qdrant”,
“config”: { “host”: “host.docker.internal”, “port”: 6333 }
},
“llm”: {
“provider”: “dashscope-coding”,
“config”: { “model”: “qwen3.5-plus” }
}
}
}
}
“`

**步骤 3：验证配置**
“`bash
# 在容器内执行
openclaw status
# 应该看到 Mem0 已注册
“`

### 🛡️ 如何避免（预防建议）

**1. 插件 ID 必须与目录名一致** 🟢
– 检查扩展目录名称：`ls [工作区路径]/extensions/`
– 配置中的 key 必须完全匹配
– 比如目录是 `mem0`，配置就用 `”mem0″`

**2. 配置前画架构图** 🟢
– 先理解需要哪些组件
– Mem0 = Embedder + VectorStore + LLM
– 三个都配齐了再保存

**3. 使用模板配置** 🟢
– 保存一份正确的配置模板
– 需要时复制模板，只修改关键参数
– 避免拼写错误

### 📊 Mem0 工作流程图

“`
┌──────────────────────────────────────────────────────────────┐
│ Mem0 记忆工作流程 │
└──────────────────────────────────────────────────────────────┘

1️⃣ 用户发送消息
│
▼
2️⃣ [Embedder] 把文字转成向量
“今天天气不错” → [0.1, 0.5, 0.8, …]
│
▼
3️⃣ [VectorStore/Qdrant] 存储向量
向量 + 时间戳 + 上下文 → 数据库
│
▼
4️⃣ 用户再次提问
│
▼
5️⃣ [AutoRecall] 自动检索相关记忆
向量相似度匹配 → 找到相关记忆
│
▼
6️⃣ [LLM] 结合记忆生成回答
“根据之前的对话…” + 新知识 → 回答
│
▼
✅ 完成！用户得到个性化回答
“`

### 📝 学习要点
– ✅ 插件 ID 必须与扩展目录名称一致
– ✅ oss 配置需要完整：embedder + vectorStore + llm
– ✅ userId 用于区分不同用户的记忆

—

## 📋 问题 4：飞书 (Feishu) 配置错误

### 🔍 问题现象
“`
飞书机器人无法收发消息
日志显示模块找不到
配置好像没生效
“`

### 🧐 原因分析

**问题 1：缺少 Node.js 依赖**
“`
飞书扩展是 Node.js 写的
需要先安装依赖包才能运行
就像买车要加油一样
“`

**问题 2：配置重复**
“`json
❌ 错误：
{
“appId”: “[APPID_VALUE]”,
“appId”: “[APPID_VALUE]”, // 重复了！
“appSecret”: “[APPSECRET_VALUE]”
}
“`

**问题 3：不理解配置含义**
– `dmPolicy`: 一对一消息策略
– `groupPolicy`: 群聊策略
– `connectionMode`: 连接方式

### ✅ 解决方案

**步骤 1：安装依赖**
“`bash
# 在容器内执行
docker exec a433fd453cf0 sh -c “cd /app/extensions/feishu && npm install”
“`

**步骤 2：正确配置**
“`json
“feishu”: {
“enabled”: true,
“accounts”: {
“default”: {
“appId”: “[APPID_VALUE]”,
“appSecret”: “[APPSECRET_VALUE]”
}
},
“dmPolicy”: “pairing”,
“groupPolicy”: “open”,
“connectionMode”: “websocket”
}
“`

**步骤 3：理解配置含义**
“`json
{
“dmPolicy”: “pairing”, // 一对一：需要配对才能收消息
“groupPolicy”: “open”, // 群聊：开放，可以直接拉进群
“connectionMode”: “websocket” // 连接方式：WebSocket 长连接
}
“`

### 🛡️ 如何避免（预防建议）

**1. 安装扩展后先装依赖** 🟢
“`bash
# 养成习惯：安装扩展 → 进入目录 → npm install
cd /app/extensions/feishu
npm install
“`

**2. 使用 JSON 工具检查重复字段** 🟢
“`bash
# jq 会提示重复的 key
jq . ~/.openclaw/openclaw.json
“`

**3. 理解每个配置项的含义** 🟢
– 阅读扩展文档
– 不理解配置不要乱改
– 可以参考本文档的说明

### 📊 飞书消息流程图

“`
┌─────────────────────────────────────────────────────────────┐
│ 飞书消息处理流程 │
└─────────────────────────────────────────────────────────────┘

┌─────────────┐
│ 飞书用户 │
└──────┬──────┘
│
┌───────────┼───────────┐
│ │ │
▼ ▼ ▼
一对一消息 群聊消息 系统通知
│ │ │
│ dmPolicy groupPolicy
│ “pairing” “open”
│ │ │
│ 需要配对 ✅ 直接接收 ✅
│ │ │
└───────┴──────┬──────┘
│
▼
┌─────────────────┐
│ WebSocket 连接 │
│ (长连接，实时) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ OpenClaw 处理 │
│ 消息并回复 │
└─────────────────┘
“`

### 📝 学习要点
– ✅ Node.js 扩展需要先安装依赖
– ✅ appId 和 appSecret 只能出现一次
– ✅ dmPolicy: “pairing” 表示需要配对才能接收消息
– ✅ groupPolicy: “open” 表示开放群聊

—

## 📋 问题 5：Gateway Token 不匹配

### 🔍 问题现象
“`
CLI 命令无法执行
提示认证失败
连接被拒绝
“`

### 🧐 原因分析

**Token 是什么？**
“`
Token 就像门禁卡
Gateway 有门禁系统
CLI 需要刷卡才能进入
如果卡不对，就进不去
“`

**问题根源：**
– `.env` 文件有一个 Token
– `openclaw.json` 有另一个 Token
– 两个不一样，CLI 不知道该用哪个

“`
┌─────────────────────────────────────────────────────────────┐
│ Token 不匹配问题 │
│ │
│ .env 文件：GATEWAY_TOKEN = “abc123…” │
│ │ │
│ │ ❌ 不一致！ │
│ │ │
│ openclaw.json：token = “local-dev-token” │
│ │
│ 结果：CLI 不知道用哪个，连接失败 ❌ │
└─────────────────────────────────────────────────────────────┘
“`

### ✅ 解决方案

**步骤 1：找到权威 Token**
“`bash
# 在宿主机查看.env 文件
cat /media/george/AI/openclaw/.env | grep GATEWAY_TOKEN
# 输出：GATEWAY_TOKEN=[API_KEY_D53D3DE7]
“`

**步骤 2：更新 openclaw.json**
“`json
// 在容器内编辑 ~/.openclaw/openclaw.json
“remote”: {
“token”: “[API_KEY_D53D3DE7]”
},
“auth”: {
“token”: “[API_KEY_D53D3DE7]”
}
“`

**步骤 3：验证连接**
“`bash
# 在容器内执行
openclaw status
# 应该能正常显示状态
“`

### 🛡️ 如何避免（预防建议）

**1. .env 文件是权威来源** 🟢
– 永远以 `.env` 文件的 Token 为准
– 其他地方的 Token 都要跟它一致
– 修改时先改 `.env`，再同步其他地方

**2. 创建同步脚本** 🟢
“`bash
#!/bin/bash
# 自动同步 Token
TOKEN=$(grep GATEWAY_TOKEN /media/george/AI/openclaw/.env | cut -d’=’ -f2)
# 更新 openclaw.json 中的 token
sed -i “s|\”token\”: \”[^\”]*\”|\”token\”: \”$TOKEN\”|g” ~/.openclaw/openclaw.json
“`

**3. 修改配置后测试连接** 🟢
“`bash
# 每次改完 Token 都测试一下
openclaw status
# 确保 CLI 能连接 Gateway
“`

### 📊 Token 同步示意图

“`
┌─────────────────────────────────────────────────────────────┐
│ Token 同步流程 │
└─────────────────────────────────────────────────────────────┘

┌─────────────────┐
│ .env 文件 │ ← 权威来源 (Source of Truth)
│ GATEWAY_TOKEN │
└────────┬────────┘
│
│ ✅ 复制 Token
│
┌────────▼────────┐
│ openclaw.json │
│ remote.token │ ← 同步到这里
│ auth.token │ ← 也同步到这里
└────────┬────────┘
│
│ ✅ 三个地方一致
│
┌────────▼────────┐
│ CLI 正常连接 │
│ Gateway 认证通过 │
└─────────────────┘
“`

### 📝 学习要点
– ✅ `.env` 文件的 `GATEWAY_TOKEN` 是权威值
– ✅ `openclaw.json` 的 `remote.token` 和 `auth.token` 必须同步
– ✅ 不匹配会导致 CLI 无法连接 Gateway

—

## 📋 问题 6：MySQL DNS 解析失败

### 🔍 问题现象
“`
无法连接 MySQL 数据库
错误信息：getaddrinfo ENOTFOUND mysql
容器内 ping mysql 不通
“`

### 🧐 原因分析

**Docker 网络隔离**
“`
Docker 容器默认在自己独立的网络里
就像住在不同小区，不能直接串门

┌──────────────────┐ ┌──────────────────┐
│ OpenClaw 容器 │ │ MySQL 容器 │
│ │ │ │
│ 网络： │ │ 网络： │
│ openclaw_ │ │ shared_ │
│ default │ │ network │
│ │ │ │
│ 🏠 小区 A │ ❌ │ 🏠 小区 B │
│ │ 不通 │ │
└──────────────────┘ └──────────────────┘
“`

**DNS 解析失败的原因：**
– 容器 A 想访问容器 B
– 使用名字 `mysql` 而不是 IP
– 但两个网络不互通，DNS 解析不到

### ✅ 解决方案

**方案 1：临时解决（快速测试）**
“`bash
# 在宿主机执行
docker network connect shared_network a433fd453cf0
“`
这样 OpenClaw 容器就加入了 MySQL 的网络，可以互相访问了。

**方案 2：永久解决（最佳实践）**
“`yaml
# 修改 docker-compose.yml
services:
openclaw-gateway:
networks:
– openclaw_default # 原有网络
– shared_network # 新增：加入 MySQL 的网络

networks:
shared_network:
external: true # 使用外部网络
“`

**方案 3：使用 docker-compose 重建**
“`bash
# 修改 docker-compose.yml 后
cd /media/george/AI/openclaw
docker-compose down
docker-compose up -d
“`

### 🛡️ 如何避免（预防建议）

**1. 规划好网络架构** 🟢
– 启动前就设计好网络拓扑
– 哪些服务需要互通，提前规划
– 在 docker-compose.yml 中声明清楚

**2. 使用外部网络** 🟢
– 创建共享网络：`docker network create shared_network`
– 需要互通的服务都加入这个网络
– 这样即使容器重建，网络关系不变

**3. 测试网络连通性** 🟢
“`bash
# 进入容器测试
docker exec -it a433fd453cf0 bash
ping mysql
curl http://mysql:3306
“`
确保能通再继续配置

### 📊 Docker 网络架构图

“`
┌─────────────────────────────────────────────────────────────┐
│ Docker 网络连接方案 │
└─────────────────────────────────────────────────────────────┘

方案 A：临时连接 (适合测试)
┌──────────────────┐ ┌──────────────────┐
│ OpenClaw 容器 │────▶│ MySQL 容器 │
│ 临时加入网络 │ │ shared_network │
└──────────────────┘ └──────────────────┘
│ │
└────────────────────────┘
临时桥接 ✅

方案 B：永久连接 (推荐)
┌──────────────────┐ ┌──────────────────┐
│ OpenClaw 容器 │ │ MySQL 容器 │
│ networks: │ │ networks: │
│ – openclaw_ │ │ – shared_ │
│ – shared_ │ │ network │
└──────────────────┘ └──────────────────┘
│ │
└───────────┬────────────┘
│
┌─────────▼─────────┐
│ shared_network │
│ (共享网络) │
└───────────────────┘
永久互通 ✅
“`

### 📝 学习要点
– ✅ Docker 网络隔离是常见问题
– ✅ 跨网络访问需要显式连接
– ✅ docker-compose.yml 中声明多个网络是最佳实践

—

## 📊 当前服务状态

| 服务 | 状态 | 说明 |
|——|——|——|
| Gateway | ✅ 运行中 | 127.0.0.1:18789 |
| Telegram | ✅ 运行中 | @geo_openclaw_bot |
| Feishu | ✅ 运行中 | WebSocket 模式 |
| Mem0 | ✅ 已注册 | 长期记忆 |
| Ollama | ✅ 可连接 | 192.168.x.x:11434 |
| Qdrant | ✅ 运行中 | 6333 |
| MySQL | ✅ 可连接 | shared_network |

—

## 📁 重要文件位置

| 文件 | 位置 | 操作环境 |
|——|——|———|
| 配置文件 | `~/.openclaw/openclaw.json` | 🐳 容器内 |
| 环境变量 | `/media/george/AI/openclaw/.env` | 🖥️ 宿主机 |
| Docker Compose | `/media/george/AI/openclaw/docker-compose.yml` | 🖥️ 宿主机 |
| IP 修复脚本 | `/home/george/Documents/my_linux_scripts/scripts/ai/fix_openclaw_ollama_ip.sh` | 🖥️ 宿主机 |
| 服务配置 | `/home/george/Documents/my_linux_scripts/service.conf` | 🖥️ 宿主机 |

—

## 🔧 常用命令速查

### 宿主机命令
“`bash
# 查看容器状态
docker ps

# 进入容器
docker exec -it openclaw-openclaw-gateway-1 bash

# 查看日志
docker logs openclaw-openclaw-gateway-1 -f

# 重启容器
docker restart openclaw-openclaw-gateway-1

# 连接网络
docker network connect shared_network a433fd453cf0
“`

### 容器内命令
“`bash
# 验证配置
openclaw doctor –non-interactive

# 安装插件
openclaw plugins install [工作区路径]/extensions/mem0 –link

# 查看状态
openclaw status

# 检查 JSON 格式
jq . ~/.openclaw/openclaw.json
“`

—

## 🎯 小笔 ✍️ 和小智 🧠 的学习任务

### 小笔 ✍️ (文档专家)
1. ✅ 将这份文档整理成易懂的教程
2. ✅ 补充每个问题的”如何避免”部分
3. ✅ 添加截图和示意图
4. 📝 发布到 Blog

### 小智 🧠 (技术专家)
1. ✅ 深入理解每个问题的技术原理
2. ✅ 掌握所有诊断命令
3. ✅ 能够独立解决类似问题
4. ✅ 提出预防性措施

—

## 📚 学习心得（小笔 ✍️）

**完成时间：** 2026-03-09
**字数：** 约 350 字

通过这次学习，我对 OpenClaw 配置问题有了更深入的理解：

**关键收获 1：预防胜于治疗**
每个问题都有明确的预防措施。最重要的是养成好习惯：修改配置前备份、修改后用 doctor 验证、不理解时先查文档。这些看似简单的步骤能避免 80% 的问题。

**关键收获 2：理解架构才能解决问题**
之前只是机械地执行命令，现在明白了背后的原理。比如 Docker 网络隔离、Token 认证机制、Mem0 的三组件架构。理解了架构，问题就不再神秘。

**关键收获 3：可视化帮助理解**
绘制流程图和架构图让我更清楚地看到问题的本质。技术小白也能通过图示快速理解复杂的概念。这是今后文档写作的重要方法。

**下一步计划：**
– 将这些知识整理成系列博客文章
– 为每个问题制作视频教程
– 创建检查清单 (checklist) 供日常使用

—

_此文档由 George 提供原始内容 | 曹小兔 🐰 整理 | 小笔 ✍️ 完善 | 2026-03-09 16:49 UTC_

**版本历史：**
– v1.0 (2026-03-09 16:44) – George 提供原始内容
– v2.0 (2026-03-09 16:49) – 小笔 ✍️ 添加”如何避免”、示意图、学习心得