# Agent 多实例冲突问题排查指南\n\n> **文档用途**：记录 Agent 多实例运行导致的冲突问题及解决方案 \n> **适用对象**：所有 Agent 运维人员 \n> **最后更新**：2026-03-19\n\n—\n\n## 📋 问题概述\n\n**问题现象**：小智在飞书和 QQBot 频道出现 “access not configured” 错误，无法正常工作。\n\n**根本原因**：**Linux 上的小智实例** 与 **当前运行的小智实例** 发生冲突，导致频道被两个相同的小智占用，引发匹配问题。\n\n—\n\n## 🔍 问题分析\n\n### 冲突表现\n\n当同一个 Agent 在多个地方运行时，会导致：\n\n| 问题类型 | 具体表现 |\n|———|———|\n| 频道占用冲突 | 多个实例争夺同一个频道连接 |\n| 配对状态混乱 | 消息路由到错误的实例 |\n| 访问错误 | 出现 “access not configured” 错误 |\n\n### 典型场景\n\n\n\n—\n\n## ✅ 解决方案\n\n### 步骤 1：识别冲突实例\n\n检查是否有多个相同 Agent 在运行：\n\n\n\n### 步骤 2：关闭冲突实例\n\n**操作**：关闭 Linux 上的小智实例\n\n\n\n### 步骤 3：验证修复\n\n确认小智可以正常通过飞书和 QQBot 工作：\n\n1. 发送测试消息到飞书小智\n2. 发送测试消息到 QQBot 小智\n3. 确认响应正常，无 “access not configured” 错误\n\n—\n\n## 🛡️ 预防措施\n\n### 基本原则\n\n> **确保每个 Agent 只在一个地方运行**\n\n### 多平台运行方案\n\n如果需要在多个平台运行，使用以下方法避免冲突：\n\n| 方案 | 说明 |\n|——|——|\n| 不同 Agent ID | 为每个实例分配唯一 ID |\n| 不同账户配置 | 使用独立的账户配置文件 |\n| 单一主实例 | 只保留一个活跃实例，其他作为备份 |\n\n### 检查清单\n\n- [ ] 部署新实例前检查是否已有运行实例\n- [ ] 定期审查运行的 Agent 列表\n- [ ] 记录每个 Agent 的运行位置\n- [ ] 设置监控告警检测重复实例\n\n—\n\n## 📚 相关文档\n\n- [Agent 部署指南](./agent-deployment-guide.md)\n- [OpenClaw 命令参考](./openclaw-cli-best-practices.md)\n- [故障排查手册](./troubleshooting-guide.md)\n\n—\n\n## 📝 案例记录\n\n| 时间 | Agent | 问题 | 解决方式 |\n|——|——-|——|———|\n| 2026-03-19 | 小智 | 飞书/QQBot access not configured | 关闭 Linux 上的重复实例 |\n\n—\n\n_文档维护：小笔 ✍️_ \n_更新日期：2026-03-19_\n