> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-si-bu-fen-shi-zhan-yu-you-hua-shen-du-zhi-nan/13_practical_cases/13.1_lark_slack_workbot.md). # 13.1 实战案例：企业飞书群工作助手 ## 13.1.1 问题定义与场景约束 一个 30 人规模的工程团队日常通过飞书（Lark）协作，希望在群里有一个智能助手，具备以下能力： * 回答关于内部文档和代码仓库的问题 * 总结每日 GitHub PR 活动 * 通过自然语言创建和查询 Jira 工单 * 根据用户角色实施权限控制（工程师 vs 访客） 约束条件：必须在现有飞书群内运行，无需新增基础设施（仅通过 OpenClaw Gateway）。 ## 13.1.2 最小闭环：单工具单渠道跑通 从最简单的配置开始，验证群机器人的基本工作流程。我们用一个知识库搜索工具、一个飞书渠道，先画出一份**按当前配置思路整理的示意骨架**。 > \[!WARNING] 下面这段配置**不是可直接粘贴运行的完整现成文件**。飞书/Slack 一类案例在不同版本中的字段演进很快，尤其是 agent、channel、plugin 与 auth 结构。动手前请一定先对照当前 `openclaw config schema` / Dashboard Config 页，把这里的“设计意图”映射到你本地版本的真实字段。 下面是一个面向当前 `agents.list` / `channels.feishu` 思路的最小化配置骨架。工具定义仍是业务侧示意，实际应通过插件或已有工具实现。 ```jsonc { "profile": "default", "version": "1.0.0", "agents": { "list": [ { "id": "group_assistant", "name": "群工作助手", "instructions": "你是企业工程团队的群助手。\n用户会在飞书群里提问，你的职责是：\n1. 搜索内部知识库，回答常见问题\n2. 保持回复简洁、专业\n3. 如果知识库里没有答案，诚实地说 \"我找不到相关文档\"", "model": "", "tools": { "allow": ["knowledge_base_search"] } } ] }, "tools": { "knowledge_base_search": { "description": "在内部知识库中搜索文档和代码注释", "// implementation": "用自定义插件工具或 memory_search 包装实现；这里仅表示工具契约" } }, "channels": { "feishu": { "enabled": true, "domain": "feishu", "accounts": { "main": { "appId": "${LARK_APP_ID}", "appSecret": "${LARK_APP_SECRET}", "groupPolicy": "allowlist", "groupAllowFrom": [""], "requireMention": true } }, "dmPolicy": "pairing" } } } ``` 按照[第七章 7.2 飞书专项接入指南](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/07_multi_agent/7.2_lark_integration.md)的步骤完成飞书应用配置和 OpenClaw 端的绑定后，运行网关： ```bash openclaw gateway start ``` 然后在飞书群里 @ 机器人或按当前 group policy 触发它，机器人应该会搜索知识库并生成回复。当前群聊/频道的普通最终回复通常是内部/私密响应，不一定会直接投递到房间；需要房间可见输出时，应让智能体显式调用 `message(action=send)`，或在全局 `messages.groupChat.visibleReplies: "automatic"` 中配置自动可见回复。 验证步骤：在群里 @ 机器人并发送一条消息（例如“如何重置密码”），确认日志里出现一次命中该群的 agent turn；若要求群内可见回复，确认 `message` 工具调用或自动可见回复配置确实生效。如果没有回复，检查[第七章 7.2](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/07_multi_agent/7.2_lark_integration.md)中的“常见失败点速查”。 ## 13.1.3 关键配置拆解 现在逐步添加复杂功能。每一层都只展示增量部分，完整配置见前一小节。 ### 1. 增加工具：GitHub PR 分析与 Jira 工单管理 修改上面配置中 `agents.list[].tools.allow` 的列表，添加两个工具： ```json { "tools": { "allow": [ "knowledge_base_search", "github_pr_analyzer", "jira_issue_manager" ] } } ``` 然后在插件或工具注册层补充这些工具契约。下面仍是业务侧示意，不代表当前版本存在 `builtin:github` 或 `builtin:jira` 这类内建类型： ```jsonc "tools": { "knowledge_base_search": { "// implementation": "memory_search 包装或自定义知识库插件" }, "github_pr_analyzer": { "description": "分析 GitHub 仓库中过去 24 小时的 PR 活动", "// implementation": "自定义插件工具，token 通过 SecretRef / 环境变量读取" }, "jira_issue_manager": { "description": "创建和查询 Jira 工单", "// implementation": "自定义插件工具，字段映射在插件内部维护" } } ``` 详见[第五章 工具入门](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/05_tools_skills.md)。 ### 2. 添加权限控制：基于角色的访问策略 角色权限不要写成顶层 `profiles` / `guardrails` 的旧 schema。更稳妥的做法是把“工程师 vs 访客”的差异映射到渠道 sender 策略、agent 工具 allowlist 或 hook。下面只表达授权矩阵： ``` engineer: knowledge_base_search, github_pr_analyzer, jira_issue_manager guest: knowledge_base_search ``` 落地时要区分渠道能力：Slack 可使用 channel / group 层的 `toolsBySender` 为工程师账号 `alsoAllow` 高权限工具；Feishu 当前应先用 `channels.feishu.groupSenderAllowFrom` 或 `groups..allowFrom` 控制谁能触发群机器人，再用 `groups..tools` 控制群级工具集合。Feishu sender-specific 高风险授权更适合放在全局/agent 工具策略或 `before_tool_call` hook 中，按 sender、群 ID 与企业目录查询结果做动态拒绝。详见[第五章 5.2 工具策略](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/05_tools_skills/5.2_tool_policy.md)与[第十一章 11.4 守卫与隔离](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/11_reliability_security/11.4_guardrails.md)。 ### 3. 添加定时任务：每日 PR 摘要 如果要做“每日 PR 摘要”这类任务，当前版本应优先把它映射到 Gateway 的 Cron 作业。下面的内容只表达**作业意图**，不再把 `cron_tasks` 写成现行配置字段： ```json { "job_spec_example": { "daily_pr_summary": { "schedule": "0 16 * * *", "agent": "group_assistant", "tool": "github_pr_analyzer", "channel": "feishu", "instruction": "生成过去 24 小时的 PR 活动摘要，列出：1) 新开的 PR 数量、2) 已合并的 PR 数量、3) 待审核 PR 列表。用简洁的 Markdown 格式。", "timezone": "Asia/Shanghai" } } } ``` 这会在每天下午 16:00（由 `timezone: "Asia/Shanghai"` 指定为北京时间）触发 PR 摘要任务；若使用 CLI 创建同类 cron，应显式传入 `--tz Asia/Shanghai`，否则会按 Gateway 主机时区解释。若要投递到飞书群，需要显式配置 delivery/announce、`channel: "feishu"` 和目标群 `to: ""`，或在任务中调用 `message(action=send)`。详见[第八章 自动化与定时任务](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/08_automation_ops.md)。 ## 13.1.4 验收清单与常见失败点 逐项验证配置的正确性： 1. **机器人处理群消息** → 在飞书群中 @ 机器人或按 group policy 触发，确认日志中有 agent turn；若需要房间可见回复，确认作业或工具显式投递到群里 2. **知识库搜索有结果** → 提问一个文档中确实存在的问题（例如“API 文档在哪里”），确认搜索返回相关内容 3. **权限控制生效** → 用访客账户在群里发送“请分析最近的 PR”，验证机器人回复“您没有权限使用此功能”或类似拒绝提示 4. **定时任务正常触发** → 检查日志确认任务在预期时间（北京时间 16:00）执行 常见失败及排查方案： | 问题 | 可能原因 | 排查步骤 | | ------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | “机器人不回复” | 飞书应用权限、事件订阅顺序、渠道配置字段与当前版本不匹配 | 查看[第七章 7.2](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/07_multi_agent/7.2_lark_integration.md)“防坑预警”；优先对照当前 `config.schema` 与 Dashboard Config 页，而不是直接照抄旧字段 | | “知识库没有结果” | OpenClaw memory 索引未写入，或自定义检索插件配置与实际暴露路径不一致 | 若使用 OpenClaw 记忆体系，检查 `memory_search` / memory-core 索引与 embedding 配置；若使用自定义 `knowledge_base_search` 插件，检查该插件实际暴露的配置路径和日志 | | “访客仍能调用高权限工具” | `toolsBySender`、工具策略或自定义 hook 未命中 | 用 `openclaw sandbox explain` 检查有效工具策略；条件化访问应放在 `toolsBySender` 或 `before_tool_call` hook 中，不要把 `condition` 写进 `tools.deny` | | “定时任务不执行” | 时区配置错误或 cron 表达式语法错误 | 检查 `timezone` 字段是否为有效的 IANA 时区名称（如 `Asia/Shanghai`）；验证 `schedule` 是标准 5 字段 cron 格式 | ## 13.1.5 扩展到生产时再加什么 当从测试环境迁移到生产时，需要补充以下几个方面（配置细节参见相应章节）： **Kubernetes 部署** - 不再用 `openclaw gateway start` 本地运行，而是部署成 Pod，支持多副本和自动扩展。详见[第十二章 12.4 生产落地蓝图](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/12_extension_engineering/12.4_production_blueprint.md)。 **监控和告警** - 接入 Prometheus 或 DataDog 监控机器人的响应时间、错误率、工具调用频率。详见[第十二章 12.4.5 监控与告警](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/12_extension_engineering/12.4_production_blueprint.md)。 **多渠道支持** - 同时接入 Slack、Discord、Telegram、WhatsApp、Feishu/Lark 等渠道时，以官方 README、channels 文档与 `channels capabilities` 输出为准，区分 bundled、downloadable/external plugin 与第三方插件。WebChat / Control UI Chat 属于 Gateway UI / 内部聊天入口，不应按普通出站渠道配置。 **审计日志** - 记录所有工具调用、用户操作和权限检查结果。详见[第十一章 11.4 守卫与隔离](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/11_reliability_security/11.4_guardrails.md)。 完整的 Kubernetes 部署配置与监控告警设置，参见[第十二章生产落地蓝图](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/12_extension_engineering/12.4_production_blueprint.md)。