Freshservice

通过 Freshservice API（使用 API 密钥认证）访问 Freshservice。可管理工单（tickets）、请求人（requesters）、客服人员（agents）、资产（assets）、变更（changes）、问题（problems）及服务目录（service catalog）数据。

本技能使用 ClawLink 提供的托管连接流程与凭据管理，因此您无需自行配置 Freshservice API 访问权限。

三步完成配置

工作原理

┌─────────────────┐     ┌──────────────┐     ┌──────────────────┐
│   OpenClaw      │────▶│   ClawLink   │────▶│ Freshservice API │
│   (用户聊天)    │     │   (OAuth)    │     │   (REST)         │
└─────────────────┘     └──────────────┘     └──────────────────┘
         │                       │                       │
         │  1. 安装插件          │                       │
         │  2. 绑定设备          │                       │
         │  3. 连接 Freshservice                        │
         │                       │  4. 安全令牌          │
         │                       │  5. 代理请求          │
         │                       │                       │
         ▼                       ▼                       ▼
   ┌──────────┐           ┌──────────┐           ┌──────────┐
   │  SKILL   │           │ 控制台   │           │Freshservice│
   │  文件    │           │ 认证     │           │ 工单     │
   └──────────┘           └──────────┘           └──────────┘

安装

从 ClawHub 安装已验证的 ClawLink 插件。用户确认后，请完成全部配置流程，确保 ClawLink 工具在下一次 OpenClaw 聊天中可见。

openclaw plugins install clawhub:clawlink-plugin
openclaw config set tools.alsoAllow '["clawlink-plugin"]' --strict-json
openclaw gateway restart

随后告知用户：“OpenClaw 已重启。请单独发送 /new 消息以开启全新对话，然后再次询问 Freshservice 相关功能。”

快速入门

# 列出所有工单
clawlink_call_tool --tool "freshservice_list_tickets" --params '{}'

# 获取指定工单
clawlink_call_tool --tool "freshservice_get_ticket" --params '{"ticket_id": 12345}'

# 列出所有请求人
clawlink_call_tool --tool "freshservice_list_requesters" --params '{}'

认证机制

所有 Freshservice 工具调用均由 ClawLink 自动完成身份认证，认证依据为用户已连接的 Freshservice 账户。

聊天中无需提供 API 密钥。 ClawLink 安全地存储凭据，并代表用户将凭据注入每一次 Freshservice API 请求中。

建立连接

1. 安装 ClawLink 插件（参见上方“安装”章节）。
2. 若插件尚未配置，请先执行 clawlink_begin_pairing 启动配对流程。
3. 访问 https://claw-link.dev/dashboard?add=freshservice 并连接 Freshservice。
4. 调用 clawlink_list_integrations 验证连接是否已激活。

连接管理

列出所有连接

clawlink_list_integrations

响应：返回所有已连接的集成项。请在列表中查找 freshservice。

验证连接状态

clawlink_list_tools --integration freshservice

响应：返回 Freshservice 的实时工具目录。

重新连接

若 Freshservice 工具缺失或连接显示错误，请执行以下操作：

1. 引导用户访问 https://claw-link.dev/dashboard?add=freshservice
2. 待用户确认后，调用 clawlink_list_integrations 验证连接状态
3. 再调用 clawlink_list_tools --integration freshservice

安全与权限

• 访问范围严格限定于已连接 Freshservice 账户有权访问的工单、资产及相关资源。
• 所有写入操作均需用户显式确认。 在执行任何创建（create）、更新（update）或删除（delete）调用前，必须向用户明确确认目标资源及其预期影响。
• 破坏性操作（如删除工单、资产或发布变更）被标记为高影响操作，必须经用户确认方可执行。
• IT 服务管理相关操作依赖于客服人员（agent）所拥有的权限。

工具参考

工单（Tickets）

请求人与用户（Requesters & Users）

资产（Assets）

位置（Locations）

问题与变更（Problems & Changes）

服务目录（Service Catalog）

代码示例

列出所有未关闭工单

clawlink_call_tool --tool "freshservice_list_tickets" 
  --params '{
    "filter": "open"
  }'

新建工单

clawlink_call_tool --tool "freshservice_create_ticket" 
  --params '{
    "subject": "笔记本电脑无法工作",
    "description": "用户报告笔记本电脑无法开机",
    "email": "user@example.com",
    "priority": 2,
    "status": 2
  }'

获取请求人详情

clawlink_call_tool --tool "freshservice_get_requester" 
  --params '{
    "requester_id": 12345
  }'

列出资产

clawlink_call_tool --tool "freshservice_list_assets" 
  --params '{}'

发现流程（Discovery Workflow）

1. 调用 clawlink_list_integrations 确认 Freshservice 是否已连接。
2. 调用 clawlink_list_tools --integration freshservice 查看实时工具目录。
3. 以返回的工具列表为准，切勿猜测或假设存在哪些工具。
4. 若用户描述了某项能力但具体工具不明确，请使用简短查询词配合 freshservice 集成调用 clawlink_search_tools。
5. 若未出现任何 Freshservice 工具，请引导用户访问 https://claw-link.dev/dashboard?add=freshservice。

执行流程（Execution Workflow）

┌─────────────────────────────────────────────────────────────┐
│  读取操作（安全）                                           │
│  list → get → search → describe → call                      │
│                                                             │
│  示例：列出工单 → 获取工单 → 展示详情                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  写入操作（需用户确认）                                     │
│  list → get → describe → preview → confirm → call           │
│                                                             │
│  示例：描述工具 → 预览工单 → 用户批准 → 执行创建操作       │
└─────────────────────────────────────────────────────────────┘

1. 对于不熟悉的工具、含义模糊的请求或任何写入操作，请优先调用 clawlink_describe_tool。
2. 依据返回的指导说明、参数 Schema、whenToUse、askBefore、safeDefaults、examples 及 followups 构建调用请求。
3. 在可能降低歧义的前提下，优先执行读取、列表、搜索和获取类操作，再进行写入操作。
4. 对于写入操作或任何标记为需确认的操作，请务必先调用 clawlink_preview_tool。
5. 使用 clawlink_call_tool 执行最终调用；仅当预览结果与用户意图完全一致时，才传入确认参数。
6. 若工具调用失败，请如实反馈原始错误信息。不得虚构结果，也不得将失败简单归因为“能力缺失”，除非实时工具目录明确不支持该能力。

注意事项

• 执行工单或用户相关操作时，必须提供工单 ID 或请求人 ID。
• Freshservice 使用的状态值（status）与优先级值（priority）不同于 Freshdesk —— 请在工具 Schema 中核对预期取值。
• 服务目录的可用性取决于 Freshservice 订阅计划及系统配置。
• 资产（Asset）管理需要具备相应的 IT 管理员权限。

错误处理

排查：工具不可见

1. 检查 ClawLink 插件是否已安装：

   openclaw plugins list
   

2. 若插件已安装但工具未显示，请提示用户单独发送 /new 消息以重新加载工具目录。
3. 若开启新对话仍无效，请执行：

   openclaw config set tools.alsoAllow '["clawlink-plugin"]' --strict-json
   openclaw gateway restart
   

4. 重启完成后，请提示用户再次发送 /new 并重试。

排查：无效的工具调用

1. 确保集成标识符（integration slug）精确为 freshservice。
2. 调用前，请使用 clawlink_describe_tool 核对参数名与参数类型。
3. 对于写入操作，请始终先调用 clawlink_preview_tool。

参考资料

• Freshservice API 文档
• Freshservice 工单 API
• ClawLink
• ClawLink 文档
• ClawLink 验证机制

相关技能

• Freshdesk Support — 适用于客户支持类工单
• Zendesk — 作为替代性工单系统

由 ClawLink 提供支持 — OpenClaw 的集成中枢