# Agent 多实例冲突问题排查指南

> **文档用途**：记录 Agent 多实例运行导致的冲突问题及解决方案
> **适用对象**：所有 Agent 运维人员
> **最后更新**：2026-03-19

—

## 📋 问题概述

**问题现象**：小智在飞书和 QQBot 频道出现 “access not configured” 错误，无法正常工作。

**根本原因**：**Linux 上的小智实例** 与 **当前运行的小智实例** 发生冲突，导致频道被两个相同的小智占用，引发匹配问题。

—

## 🔍 问题分析

### 冲突表现

当同一个 Agent 在多个地方运行时，会导致：

| 问题类型 | 具体表现 |
|———|———|
| 频道占用冲突 | 多个实例争夺同一个频道连接 |
| 配对状态混乱 | 消息路由到错误的实例 |
| 访问错误 | 出现 “access not configured” 错误 |

### 典型场景

“`
场景：小智同时运行在两处
├─ Linux 服务器实例
└─ 当前运行实例
↓
结果：飞书/QQBot 频道被重复占用
“`

—

## ✅ 解决方案

### 步骤 1：识别冲突实例

检查是否有多个相同 Agent 在运行：

“`bash
# 查看运行的 Agent 进程
ps aux | grep 小智

# 或检查 OpenClaw 状态
openclaw status
“`

### 步骤 2：关闭冲突实例

**操作**：关闭 Linux 上的小智实例

“`bash
# 停止 Linux 上的 Agent 服务
openclaw agent stop 小智

# 或终止相关进程
kill “`

### 步骤 3：验证修复

确认小智可以正常通过飞书和 QQBot 工作：

1. 发送测试消息到飞书小智
2. 发送测试消息到 QQBot 小智
3. 确认响应正常，无 “access not configured” 错误

—

## 🛡️ 预防措施

### 基本原则

> **确保每个 Agent 只在一个地方运行**

### 多平台运行方案

如果需要在多个平台运行，使用以下方法避免冲突：

| 方案 | 说明 |
|——|——|
| 不同 Agent ID | 为每个实例分配唯一 ID |
| 不同账户配置 | 使用独立的账户配置文件 |
| 单一主实例 | 只保留一个活跃实例，其他作为备份 |

### 检查清单

– [ ] 部署新实例前检查是否已有运行实例
– [ ] 定期审查运行的 Agent 列表
– [ ] 记录每个 Agent 的运行位置
– [ ] 设置监控告警检测重复实例

—

## 📚 相关文档

– [Agent 部署指南](./agent-deployment-guide.md)
– [OpenClaw 命令参考](./openclaw-cli-best-practices.md)
– [故障排查手册](./troubleshooting-guide.md)

—

## 📝 案例记录

| 时间 | Agent | 问题 | 解决方式 |
|——|——-|——|———|
| 2026-03-19 | 小智 | 飞书/QQBot access not configured | 关闭 Linux 上的重复实例 |

—

_文档维护：小笔 ✍️_
_更新日期：2026-03-19_