一次 OpenClaw + MiniMax 多 Agent 系统部署踩坑全记录（含根因分析与重建方案）

## 一、背景与目标

本次部署的目标并不简单：

* 使用 **OpenClaw** 构建多 Agent 系统（约 7 个子 Agent）
* 主 Agent（main）统一调度
* 部分 Agent（如 it-biz / it-ops / planner）通过 **飞书群**协作
* 模型统一走 **MiniMax（M2.7 highspeed）**
* 要求：

* Agent 之间尽量隔离上下文
  * 稳定运行（无 401 / 403 / timeout）
  * 支持自动化任务（日报、调度等）

从设计上，这是一个**多 Agent + 外部通信 + LLM provider 接入**的复合系统。

---

## 二、问题演进（时间线复盘）

整个问题不是一次性出现的，而是**逐步叠加形成“状态污染”**。

### 阶段 1：模型异常切换（核心症状）

最早问题：

* 明明配置的是 `MiniMax-M2.7-highspeed`
* 实际运行中却出现：

* `Claude Opus`
  * `MiniMax-M2.5`
* 并伴随：

* 401 / 403
  * timeout

👉 初步判断：**fallback 机制 + provider 污染**

---

### 阶段 2：配置解析错误（JSON5 报错）

出现：

```text
JSON5 parse failed: invalid character
```

原因：

* 手工修改 `openclaw.json`
* 引入非法字符（如 `:`、`\`、中文路径转义等）

👉 结论：**配置文件结构被破坏**

---

### 阶段 3：provider 配置错误（关键误导点）

错误配置：

```json
"api": "chat"
```

导致：

```text
Invalid option: expected one of ...
```

正确应为：

```json
"api": "anthropic-messages"
```

👉 这是一个**关键分叉点错误**，导致后续所有请求路径不正确。

---

### 阶段 4：API 实际连通性验证

手动测试：

```bash
curl https://api.minimaxi.com/anthropic
```

```text
404 Not Found
```

但：

* TLS 正常
* DNS 正常
* 网络无阻断

👉 结论：

* 网络 OK
* endpoint path 只是不能直接 GET（正常行为）

---

### 阶段 5：Auth 池“自动复活”问题（核心坑）

关键现象：

> 手动修改 `auth-profiles.json`，过一会自动恢复

日志证据：

```text
[agents/auth-profiles] inherited auth-profiles from main agent
```

表现：

* 删除 `anthropic`
* 删除 `minimax-cn`
* 过一会全部回来

👉 根因：

> **OpenClaw 会把 main agent 的 auth profiles 作为 fallback 合并进所有 agent**

这意味着：

* 你改 `health-manager` 没用
* main 才是源头
* 且合并是 **additive（不可覆盖）**

---

### 阶段 6：环境变量失效（launchd 坑）

报错：

```text
missing env var "MINIMAX_API_KEY"
```

但 shell 中：

```bash
echo $MINIMAX_API_KEY
```

是有值的。

👉 根因：

> macOS `launchd` 不继承 shell 的 `.zshrc`

导致：

* CLI 有 key
* Gateway 没 key

---

### 阶段 7：Gateway 假运行（最迷惑点）

状态：

```text
gateway process is running
port is free
RPC probe failed
gateway closed (1006)
```

👉 本质：

* 进程在
* 服务没真正启动成功
* 健康检查失败

---

### 阶段 8：OAuth 失败（非核心问题）

```text
MiniMax OAuth failed: fetch failed
```

👉 原因：

* OpenClaw 的 OAuth 流程对 MiniMax 支持不稳定
* 与 API Key 模式冲突

👉 可直接忽略，使用 API Key

---

## 三、问题本质总结

这不是一个单点问题，而是**系统性状态污染**：

| 维度       | 问题                                 |
| -------- | ---------------------------------- |
| config   | JSON 被破坏 / provider 配置错误           |
| auth     | main agent 污染所有 agent              |
| provider | fallback 混入 anthropic / minimax-cn |
| runtime  | launchd 不读 env                     |
| gateway  | 假运行（未 ready）                       |
| cache    | session / auth / models 状态残留       |

👉 结论：

> ❌ 修修补补不可行
> ✅ 必须重置运行态

---

## 四、为什么最终选择“重装”

判断依据：

1. auth 池无法彻底清理（会自动继承）
2. provider 混乱（多来源）
3. gateway 状态异常（不可控）
4. config 已多次手改
5. 已无法确定当前状态来源

👉 这是典型的：

> **State Drift（状态漂移）**

---

## 五、重建方案（推荐路径）

核心原则：

> **只删除运行态，不动 workspace**

### 1）停止服务

```bash
launchctl bootout gui/$(id -u)/ai.openclaw.gateway
pkill -f openclaw
```

---

### 2）移走运行态

```bash
mv ~/.openclaw ~/.openclaw.bak-时间戳
mv ~/Library/LaunchAgents/ai.openclaw.gateway.plist ~/Library/LaunchAgents/*.bak
```

---

### 3）重新初始化

```bash
openclaw configure
```

关键策略：

* workspace 指向桌面独立目录
* 不导入旧配置
* 不走 OAuth

---

### 4）最小化启动

只保留：

* main
* health-manager

不要一次上 7 个 agent

---

### 5）API Key 处理策略

调试阶段：

```json
"apiKey": "sk-xxx"
```

不要用：

```json
"${MINIMAX_API_KEY}"
```

等稳定后再切 env

---

## 六、关键经验总结

### 1）OpenClaw 的 auth 是“中心化继承模型”

* main = 根节点
* 所有 agent 继承
* 无法真正隔离

---

### 2）不要在运行中频繁手改 config

尤其：

* JSON5 很脆弱
* doctor 会自动修复（但不可控）

---

### 3）launchd ≠ shell

* `.zshrc` 不生效
* env 必须显式注入

---

### 4）多 Agent 系统优先做“最小闭环”

错误做法：

> 一次性上 7 个 agent

正确做法：

> main → 1 个子 agent → 扩展

---

### 5）出现“自动恢复”=有上游源

不要反复改文件
要找：

> 谁在写这个文件？

---

## 七、最终结论

这次问题的本质不是：

> “OpenClaw 不稳定”

而是：

> **多组件系统在缺乏隔离机制时，状态会不可控叠加**

在这种情况下：

* 修补是无效的
* 重建是唯一低成本方案

---

## 八、后续优化方向

下一步建议：

1. 控制 Agent 数量（逐步扩展）
2. 明确 auth 单一来源（只保留 MiniMax）
3. 飞书接入单独验证（不要混在模型问题中）
4. 做一层 config 管控（避免手改 JSON）

---

## 九、附一句经验

> 当你开始怀疑“是不是我哪里没改对”的时候，
> 实际上通常是：**系统状态已经不可预测了。**

此时最优解往往是：

> **清空 → 重建 → 最小验证 → 再扩展**

一次 OpenClaw + MiniMax 多 Agent 系统部署踩坑全记录（含根因分析与重建方案）

分类

回到过去

友情链接

一次 OpenClaw + MiniMax 多 Agent 系统部署踩坑全记录（含根因分析与重建方案）

相关文章

标签云

分类

回到过去

友情链接