钉钉接入

将旗鱼接入钉钉后，你可以在钉钉中直接与 AI Agent 对话——发一条消息，Agent 就在你的电脑上执行任务并回复结果。

前置条件

• 钉钉账号
• 钉钉开放平台的开发者权限

配置步骤

第 1 步：创建钉钉应用

1. 打开 钉钉开放平台
2. 登录后进入「应用开发」
3. 点击「创建应用」
4. 填写以下信息：
   • 应用名称：如「旗鱼助手」
   • 应用描述：如「AI 智能助手」
   • 应用图标：上传一个图标

第 2 步：获取凭证

在应用的「凭证与基础信息」页面，记录下：

第 3 步：启用机器人能力

1. 在应用管理页面，进入「应用能力」
2. 添加「机器人」能力
3. 填写机器人信息：
   • 机器人名称：如「旗鱼助手」
   • 消息接收模式：选择 Stream 模式（长连接，无需公网 IP）

Stream 模式是推荐方式，由旗鱼主动连接钉钉服务器，不需要配置回调地址或公网 IP。

第 4 步：添加权限

在「权限管理」中根据需要添加以下权限：

第 5 步：发布应用

1. 在「版本管理与发布」中创建新版本
2. 设置可见范围（选择哪些人可以使用）
3. 提交发布

个人开发者创建的应用通常会自动通过审核。

第 6 步：连接旗鱼

1. 打开旗鱼 → 设置 → 即时通讯
2. 展开「钉钉」卡片
3. 填入 ClientID 和 ClientSecret
4. 点击「连接」
5. 等待状态变为 ✅「已连接」

可选：勾选「启动时自动连接」。

开始使用

私聊

在钉钉中搜索你创建的机器人名称（如「旗鱼助手」），打开对话直接发消息。

群聊

1. 将机器人添加到钉钉群组中
2. 在群里 @旗鱼助手 后输入消息
3. 机器人会在群内回复

消息格式

• 你发送的：纯文本消息
• Agent 回复的：Markdown 格式，支持标题、列表、代码块、链接等
• 文件发送：Agent 可以把文件发送到聊天中（20MB 以内）

使用示例

私聊中：

你: 帮我检查一下服务器磁盘空间
Agent: 📊 磁盘使用情况：
       / (根分区): 45.2GB / 100GB (45%)
       /data: 180GB / 500GB (36%)
       所有分区空间充足。

你: 看看 nginx 最近有没有报错
Agent: 检查了最近 1 小时的 error.log，发现 3 条错误：
       - 10:23 upstream timeout (2次)
       - 10:45 connection refused (1次)
       建议检查后端服务的响应时间。

常见问题

机器人不回复

• 确认应用已发布上线（版本管理中状态为「已上线」）
• 确认旗鱼中的连接状态为「已连接」
• 群聊场景需要 @机器人
• 检查旗鱼的 AI 模型配置是否正常

连接失败

• 检查 ClientID 和 ClientSecret 是否正确（注意不要有多余空格）
• 确认 Stream 模式已正确开启
• 检查网络是否能访问钉钉的服务器

消息被截断

• 钉钉对单条消息长度有限制（约 20000 字符）
• Agent 回复过长时会自动截断并提示

文件发送失败

• 确认文件大小不超过 20MB
• 检查旗鱼日志中的具体错误信息