> 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.2_customer_support_agent.md).

# 13.2 实战案例：客户支持智能体

## 13.2.1 问题定义与场景约束

某B2B SaaS公司日均接收500多条客户支持请求，分布在电子邮件和在线聊天等多个渠道。现有6人客服团队平均响应时间为4小时。公司希望部署一个支持智能体来自动处理常见问题并加速响应。

核心需求：

* **FAQ自动回复**：自动解答密码重置、账单查询、API错误等常见问题
* **情感感知升级**：检测负面情绪，自动升级到人工客服处理
* **工单系统集成**：无法自动解决的问题自动创建Zendesk工单
* **多语言支持**：同时支持中文和英文

系统约束：

* 必须与现有Zendesk系统集成
* PII（个人身份信息）必须在进入 agent turn / LLM 之前由渠道接入层或插件预处理掩盖
* 负面情感检测后升级必须在2分钟内完成

## 13.2.2 最小闭环：单工具单渠道跑通

我们从最简单的配置开始：一个只负责检索知识库和升级人工工单的支持智能体。下面的内容应被视为**按当前 OpenClaw 设计思路整理的方案骨架**，而不是可直接照抄的完整 `openclaw.json`。

> \[!WARNING] 原始案例里使用的 `gateway.auth.requirePairing`、`agents.customer-support`、`systemPrompt`、旧 `memory.*` 字段和 `channels.webhook.agentId` 都属于明显过时的 schema 形态。实际落地时，请用当前 `config.schema` / Dashboard Config 页把这些设计意图映射到现行字段。

在继续看示例前，先把“设计意图”和“现行实现方向”分开：

| 设计意图                | 不要再照抄的旧写法                     | 现行实现方向                                                                                                                       |
| ------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 网关只允许受控入口访问         | `gateway.auth.requirePairing` | 以当前 gateway auth mode、设备配对和控制面来源校验为准                                                                                         |
| 支持智能体有稳定角色与回复准则     | `systemPrompt`                | 优先映射到当前 workspace files / agent persona / session context 体系                                                                 |
| 会话要保留短期上下文并控制膨胀     | `memory.*`                    | 通过当前 session / context / compaction 配置表达                                                                                     |
| Webhook 请求要路由到支持智能体 | `channels.webhook.agentId`    | Webhook hooks 用 `hooks.mappings[]` + `action: "agent"` + `agentId`；普通聊天渠道再用 channel routing / bindings / default target 机制表达 |

下面这段 JSON 仅用于展示“一个支持智能体需要哪些设计要素”，**不是当前版本可直接复制的 schema**。如果你只是想把系统跑通，建议先按表里的“现行实现方向”在 Dashboard Config 页或当前 `config.schema` 中逐项映射，而不是照抄旧字段名。

```jsonc
{
  "// gateway": "启用当前版本支持的 gateway auth mode，并限制支持入口来源",
  "// agent": "定义 customer-support 角色、默认模型和允许使用的工具集合",
  "// retrieval": "把 FAQ / 文档知识接入当前版本支持的知识库或检索工具",
  "// escalation": "把升级人工、创建工单和通知动作收敛成显式工具",
  "// channel": "Webhook hooks 通过 hooks.mappings[] action=agent/agentId 导向支持智能体；聊天渠道再通过 routing / bindings / default target 机制导向支持智能体",
  "// session": "使用当前 session / context / compaction 配置控制短期上下文与压缩策略"
}
```

**验收：**

1. 通过你当前版本支持的 Webhook / 渠道路由方式发送“如何重置密码”，验证机器人能返回知识库中的步骤。
2. 再发送“请帮我转人工客服”，验证系统会进入升级路径，而不是继续强行自动回答。

## 13.2.3 关键配置拆解

### 升级触发规则

当前 OpenClaw 不把 `escalation.triggers` 作为内建 agent schema。升级逻辑应落在可观测的 hook、路由规则或显式工具里：例如用 `message_received` 做关键词/情绪预判，用 `before_tool_call` 拦截高风险参数，用 `before_dispatch` / `message_sending` 调整外发，或用自定义工具把升级事件投递到客服系统。详见[第 7.3 章](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/07_multi_agent/7.3_routing_basics.md)和[第 8.1 章](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/08_automation_ops/8.1_hooks.md)。

```jsonc
{
  "// support_escalation_workflow": "设计意图，不是 agents.customer-support 的内建 schema",
  "triggers": [
    {
      "type": "sentiment_negative",
      "threshold": -0.7,
      "action": "escalate_to_human"
    },
    {
      "type": "request_human",
      "keywords": ["人工", "客服", "经理"],
      "action": "escalate_to_human"
    },
    {
      "type": "confidence_low",
      "threshold": 0.4,
      "action": "ask_for_confirmation"
    }
  ]
}
```

当用户的负面情绪评分低于 -0.7 或明确请求人工客服时，hook 或工具应创建升级事件，并把 `traceId`、会话摘要、用户可见上下文和 PII 脱敏状态一起传给人工队列。

### Zendesk工单集成

当前版本没有通用内建 `type: "zendesk"` 工具。应把 Zendesk 做成自定义插件工具，例如注册 `zendesk_ticket_create`，再在支持智能体的工具 allowlist 中显式放开。下面仍然是**工具契约示意**，重点在输入输出边界，而不是宣称当前版本一定就是这组配置键。详见[第五章](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/05_tools_skills.md)和[第 12.2 章](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/12_extension_engineering/12.2_custom_tools.md)。

```jsonc
{
  "name": "zendesk_ticket_create",
  "description": "创建 Zendesk 支持工单",
  "input": {
    "subject": "string",
    "comment": { "body": "string" },
    "priority": "low|normal|high|urgent",
    "tags": ["support", "automated"]
  },
  "// auth": "插件内部读取 SecretRef / 环境变量，不把 token 写进 openclaw.json"
}
```

在支持智能体的 `tools.allow` 中添加 `zendesk_ticket_create`，并用插件内部配置维护 Zendesk subdomain、邮箱、API token 和字段映射。

### PII掩盖处理

> **注意**：以下内容是私有插件内部伪代码，不是 OpenClaw 的内建 `openclaw.json` schema。PII 如果必须在 LLM 前被掩盖，应在渠道接入、pre-routing 或自定义插件的 agent turn 之前完成；日志脱敏、工具参数改写与外发前处理只能作为额外防线。详见[第 8.1 章](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/08_automation_ops/8.1_hooks.md)。

进入知识库检索、工单创建或外部请求前，也应在插件包装层再次做 PII 掩盖。若 FAQ 已导入 OpenClaw 记忆体系，先放开 `memory_search`；若接外部向量库，则注册一个自定义插件工具，例如 `support_kb_search`。

```jsonc
"support_kb_search": {
  "description": "在内部知识库中搜索文档和代码注释",
  "// implementation": "自定义插件工具；也可以用 memory_search 查询 OpenClaw 记忆",
  "// privatePluginPiiRedaction": {
    "indexPath": "./kb/docs",
    "preprocessPatterns": [
      {
        "regex": "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b",
        "replacement": "[EMAIL_MASKED]"
      },
      {
        "regex": "\\b\\d{11}\\b",
        "replacement": "[PHONE_MASKED]"
      }
    ]
  }
}
```

此示例表达“进入外部检索前先脱敏”的工程要求。真实落地时，应先证明脱敏发生在 agent turn / 外部请求之前；`logging.redactPatterns` / `logging.redactSensitive` 与 `before_tool_call` 只能降低日志、工具参数和外发阶段的泄露风险，不能替代 LLM 前的预处理。

### 多语言支持

当前没有通用的 `agents[customer-support].language` 内建配置。多语言支持应写入 agent persona / workspace 指令，或由 `message_received` hook 标注 `locale` 后交给提示词与工具处理。详见[第七章](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/07_multi_agent.md)。

```
回复语言策略：
- 默认使用用户消息语言回复。
- 只支持 zh/en；其他语言先用英文说明支持范围。
- 工单字段保留原文，并附带简短英文摘要。
```

目标行为是：hook、插件或提示词策略识别用户消息语言，并让回复保持同一语言；不要把它理解成当前 agent schema 中的固定 `language` 配置。

## 13.2.4 验收清单与常见失败点

验收步骤：

1. **FAQ自动回答是否工作** — 发送一个已知的FAQ问题（如“如何重置密码”），验证机器人返回了知识库中的答案。
2. **升级是否在负面情感时触发** — 发送一条愤怒的消息（如“这太糟糕了，我要找客服！”），验证系统创建了工单并升级给人工。
3. **PII是否被掩盖** — 发送包含电子邮件地址的消息，检查日志中是否显示为`[EMAIL_MASKED]`。
4. **Zendesk工单字段是否正确** — 检查 Zendesk 仪表板，验证自动创建的工单包含创建所需的 `comment`，并按插件/业务规则填写 `subject`、`priority`、tags/custom\_fields 等可写字段；不要把只读的 `description` 当作创建入参。

常见失败及解决：

| 失败症状     | 根本原因                                 | 修复方法                                                                                                         |
| -------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| 知识库检索无结果 | `memory_search` 索引未写入，或自定义检索插件认证/超时  | 先用 `memory_search` 验证 FAQ 是否可查；外部向量库则检查插件日志与认证；见第6.3.3节                                                      |
| 升级不触发    | hook / 工具阈值设置过严，或情绪分析缺乏上下文           | 调整升级 hook 的阈值并记录 `traceId`；确保至少有3句完整上下文                                                                      |
| PII泄露到日志 | 日志脱敏配置缺失，或插件在持久化前未预处理敏感字段            | 启用 `logging.redactPatterns`/`logging.redactSensitive` 并在插件写日志或外发前预处理；`before_tool_call` 只能覆盖工具参数，不能替代全链路日志脱敏 |
| 工单字段缺失   | 自定义 Zendesk 插件字段映射与 Zendesk 自定义字段不匹配 | 在 Zendesk 管理界面验证字段 ID、选项 tag 与 value 映射，更新插件内部 field mapping                                                 |

## 13.2.5 扩展到生产时再加什么

**扩展更多客服入口**：优先以官方 README、channels 文档和 `channels capabilities` 输出确认当前渠道状态，并区分 bundled、downloadable/external plugin 与第三方插件。WebChat / Control UI Chat 是 Gateway UI / 内部聊天入口，不是普通出站渠道；电子邮件或 Zendesk 原生聊天应通过 webhook、插件或外部集成桥接进入 OpenClaw，而不是假设内置存在 `channels.email` / `channels.zendesk_chat` 配置。

**知识库向量数据库**：从内存中的简单列表升级为Qdrant或Weaviate等持久化向量数据库，以支持更大的知识库和更快的检索。详见[第 6.3 章](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/06_context_memory/6.3_memory_mechanism.md)中的记忆与知识管理机制。

**性能调优与成本控制**：添加缓存策略、批量处理、请求去重和模型路由（如根据复杂度选择不同的LLM）。详见[第十四章](/openclaw_guide/di-si-bu-fen-shi-zhan-yu-you-hua-shen-du-zhi-nan/14_performance_cost.md)的性能优化与成本控制策略。

**审计和合规日志**：实施完整的消息日志记录、加密存储和访问审计，以满足GDPR或其他数据保护法规。详见[第十一章](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/11_reliability_security.md)的安全与合规部分。