Cisco UC Engineer

思科UC工程师

Orchestration skill for Unified Communications. Connects cisco-axl, cisco-dime, cisco-perfmon, cisco-risport, cisco-support, audiocodes-cli, genesys-cli, and the cisco-cdr MCP server to solve cross-domain UC problems across Cisco CUCM, AudioCodes SBCs, and Genesys Cloud CX.

统一通信的编排技能，可对接cisco-axl、cisco-dime、cisco-perfmon、cisco-risport、cisco-support、audiocodes-cli、genesys-cli和cisco-cdr MCP服务器，解决Cisco CUCM、AudioCodes SBC、Genesys Cloud CX范围内的跨域UC问题。

Tool Detection

工具检测

Before starting any workflow, check which tools are available:

bash

undefined

启动任何工作流之前，先检查可用的工具：

bash

undefined

Check each tool — run all five, note which succeed

检查每个工具 — 运行全部五个命令，记录执行成功的工具

cisco-axl --version 2>/dev/null && echo "cisco-axl: available" || echo "cisco-axl: not installed" cisco-dime --version 2>/dev/null && echo "cisco-dime: available" || echo "cisco-dime: not installed" cisco-perfmon --version 2>/dev/null && echo "cisco-perfmon: available" || echo "cisco-perfmon: not installed" cisco-risport --version 2>/dev/null && echo "cisco-risport: available" || echo "cisco-risport: not installed" cisco-support --version 2>/dev/null && echo "cisco-support: available" || echo "cisco-support: not installed" audiocodes-cli --version 2>/dev/null && echo "audiocodes-cli: available" || echo "audiocodes-cli: not installed" genesys-cli --version 2>/dev/null && echo "genesys-cli: available" || echo "genesys-cli: not installed"

Check cisco-cdr MCP server (requires MCP configuration, not a CLI tool)

检查cisco-cdr MCP服务器（需要MCP配置，不是CLI工具）

Verify by calling: cdr_health

调用以下命令验证：cdr_health


Report what's available and what's missing. If a workflow requires a missing tool, tell the user:

> "This workflow needs cisco-dime which isn't installed. Install it with: `npm install -g cisco-dime`"

Adapt workflows to use only the tools that are installed. A partial toolkit is still useful — just skip steps that require missing tools and note what was skipped.


报告可用和缺失的工具。如果工作流需要某个缺失的工具，告知用户：

> "该工作流需要cisco-dime，但尚未安装。请使用以下命令安装：`npm install -g cisco-dime`"

调整工作流仅使用已安装的工具，部分可用的工具集仍然有用——只需跳过需要缺失工具的步骤，并注明跳过的内容。

Available Tools

可用工具

Tool	Purpose	npm Package	Skill
`cisco-axl`	CUCM configuration — phones, lines, route patterns, CSS, device pools, SIP trunks	`cisco-axl`	`cisco-axl-cli`
`cisco-dime`	CUCM log collection — SIP traces, SDL, audit logs, service logs	`cisco-dime`	`cisco-dime-cli`
`cisco-perfmon`	Real-time performance counters — CPU, memory, call stats	`cisco-perfmon`	`cisco-perfmon-cli`
`cisco-risport`	Device registration status — phone reg, CTI, trunk status	`cisco-risport`	`cisco-risport-cli`
`cisco-support`	Cisco Support APIs — bugs, EoX, PSIRT, software, serial coverage	`cisco-support`	`cisco-support-cli`
`audiocodes-cli`	AudioCodes Mediant VE SBC — call stats, alarms, KPIs, health checks, config backup	`audiocodes-cli`	`audiocodes-cli`
`genesys-cli`	Genesys Cloud CX — conversations, BYOC trunks, queues, agents, edges, audit	`genesys-cli`	`genesys-cli`
`cisco-cdr` (MCP)	CDR/CMR analysis — call search, call trace, quality analysis, statistics, health	`cisco-cdr-processor`	`cisco-cdr-mcp`

Each tool has its own skill with detailed command reference. Use those skills for tool-specific questions. This skill is for workflows that span multiple tools.

Note: cisco-support uses separate Cisco API credentials (not CUCM credentials). It has its own config at
~/.cisco-support/config.json
. Note: audiocodes-cli uses separate device credentials (not CUCM credentials). It has its own config at
~/.audiocodes-cli/config.json
. Note: genesys-cli uses Genesys Cloud OAuth client credentials (not CUCM credentials). It has its own config at
~/.genesys-cli/config.json
. Note: cisco-cdr is an MCP server (not a CLI tool). It requires the cisco-cdr-processor service running with PostgreSQL. Configure the MCP endpoint in your Claude Code MCP settings.

工具	用途	npm 包	对应技能
`cisco-axl`	CUCM配置——话机、线路、路由模式、CSS、设备池、SIP中继	`cisco-axl`	`cisco-axl-cli`
`cisco-dime`	CUCM日志收集——SIP traces、SDL、审计日志、服务日志	`cisco-dime`	`cisco-dime-cli`
`cisco-perfmon`	实时性能计数器——CPU、内存、通话统计	`cisco-perfmon`	`cisco-perfmon-cli`
`cisco-risport`	设备注册状态——话机注册、CTI、中继状态	`cisco-risport`	`cisco-risport-cli`
`cisco-support`	思科支持API——漏洞、EoX、PSIRT、软件、序列号保修	`cisco-support`	`cisco-support-cli`
`audiocodes-cli`	AudioCodes Mediant VE SBC——通话统计、告警、KPI、健康检查、配置备份	`audiocodes-cli`	`audiocodes-cli`
`genesys-cli`	Genesys Cloud CX——会话、BYOC中继、队列、坐席、边缘节点、审计	`genesys-cli`	`genesys-cli`
`cisco-cdr` (MCP)	CDR/CMR分析——通话搜索、通话追踪、质量分析、统计、健康检查	`cisco-cdr-processor`	`cisco-cdr-mcp`

每个工具都有对应的技能提供详细的命令参考，工具相关的特定问题请使用对应技能。本技能适用于跨多个工具的工作流。

注意：cisco-support使用独立的思科API凭证（不是CUCM凭证），其配置文件位于
~/.cisco-support/config.json
。注意：audiocodes-cli使用独立的设备凭证（不是CUCM凭证），其配置文件位于
~/.audiocodes-cli/config.json
。注意：genesys-cli使用Genesys Cloud OAuth客户端凭证（不是CUCM凭证），其配置文件位于
~/.genesys-cli/config.json
。注意：cisco-cdr是MCP服务器（不是CLI工具），需要cisco-cdr-processor服务配合PostgreSQL运行，请在Claude Code MCP设置中配置MCP端点。

Cluster Alignment

集群对齐

Each tool has its own config (

~/.cisco-axl/config.json

,

~/.cisco-dime/config.json

, etc.) with its own

activeCluster

. Before any multi-tool workflow, verify all tools are pointing at the same CUCM host.

bash

undefined

每个工具都有独立的配置（

~/.cisco-axl/config.json

、

~/.cisco-dime/config.json

等），包含各自的

activeCluster

。执行任何多工具工作流之前，请验证所有工具都指向同一个CUCM主机。

bash

undefined

Check active cluster for each installed tool

检查每个已安装工具的活跃集群

cisco-axl config show 2>/dev/null cisco-dime config show 2>/dev/null cisco-perfmon config show 2>/dev/null cisco-risport config show 2>/dev/null


**What to check:**

- Do all tools have the same host configured?
- Are the active clusters aligned (e.g., all pointing at "staging", not one at "staging" and another at "prod")?

**If misaligned:**

- Use `--cluster <name>` on each command to explicitly target the same cluster
- Or switch the active cluster: `cisco-dime config use staging`
- If a tool is missing the cluster entirely, add it:
  ```bash
  cisco-dime config add staging --host 10.0.0.1 --username admin --password "$CUCM_PASSWORD" --insecure

Best practice: When the user says "check phone X", always confirm which cluster/environment before running commands across multiple tools. Use the explicit

--cluster

flag in multi-tool workflows rather than relying on each tool's active cluster.

Note: cisco-axl requires
--cucm-version
when adding a cluster. The other tools do not.

cisco-axl config show 2>/dev/null cisco-dime config show 2>/dev/null cisco-perfmon config show 2>/dev/null cisco-risport config show 2>/dev/null


**检查项：**

- 所有工具配置的主机是否一致？
- 活跃集群是否对齐（例如全部指向"staging"，而不是一个指向"staging"另一个指向"prod"）？

**如果未对齐：**

- 在每个命令中使用`--cluster <名称>`显式指定同一个集群
- 或者切换活跃集群：`cisco-dime config use staging`
- 如果某个工具完全缺少该集群配置，添加配置：
  ```bash
  cisco-dime config add staging --host 10.0.0.1 --username admin --password "$CUCM_PASSWORD" --insecure

**最佳实践：**当用户说"检查话机X"时，在跨多个工具执行命令之前，始终先确认对应的集群/环境。多工具工作流中使用显式的

--cluster

参数，而不是依赖每个工具的活跃集群配置。

注意：cisco-axl添加集群时需要指定
--cucm-version
，其他工具不需要。

Troubleshooting Workflows

故障排查工作流

Phone Not Registering

话机注册失败

Tools needed: cisco-axl, cisco-risport, cisco-dime

bash

undefined

所需工具： cisco-axl、cisco-risport、cisco-dime

bash

undefined

1. Check phone config in CUCM

1. 检查CUCM中的话机配置

cisco-axl get Phone --name SEP001122334455 --format json

2. Check current registration status

2. 检查当前注册状态

cisco-risport query --mac 001122334455

3. Pull recent SIP traces for this device

3. 拉取该设备最近的SIP traces

cisco-dime select sip-traces --last 30m --download


**What to look for:**

- Device pool and CUCM group — is the phone pointing at the right server?
- CSS — does the phone have a calling search space assigned?
- SIP traces — look for 401/403 (auth issues), 503 (server unavailable), or no response

cisco-dime select sip-traces --last 30m --download


**排查要点：**

- 设备池和CUCM组——话机是否指向正确的服务器？
- CSS——话机是否分配了呼叫搜索空间？
- SIP traces——查找401/403（认证问题）、503（服务器不可用）或者无响应的情况

Call Routing Issue

呼叫路由问题

Tools needed: cisco-axl, cisco-dime

bash

undefined

所需工具： cisco-axl、cisco-dime

bash

undefined

1. Check the dialed pattern

1. 检查拨号模式

cisco-axl sql query "SELECT dnorpattern, routePartitionName FROM numplan WHERE dnorpattern LIKE '%<pattern>%'"

2. Check the CSS chain

2. 检查CSS链路

cisco-axl get CallingSearchSpace --name <css_name> --format json

3. Check route patterns and route lists

3. 检查路由模式和路由列表

cisco-axl list RoutePattern --search "pattern=%<digits>%"

4. Pull SIP traces to see the actual call flow

4. 拉取SIP traces查看实际呼叫流

cisco-dime select sip-traces --last 1h --download


**What to look for:**

- Is the pattern in a partition that's in the calling CSS?
- Route pattern → route list → route group → trunk — follow the chain
- SIP traces show the actual INVITE routing and any redirects/rejects

cisco-dime select sip-traces --last 1h --download


**排查要点：**

- 模式所在的分区是否在呼叫CSS中？
- 路由模式→路由列表→路由组→中继——跟随链路排查
- SIP traces会显示实际的INVITE路由以及任何重定向/拒绝信息

CDR-Based Call Investigation

基于CDR的通话排查

Tools needed: cisco-cdr (MCP), cisco-dime, cisco-axl

undefined

所需工具： cisco-cdr (MCP)、cisco-dime、cisco-axl

undefined

1. Search CDR for the reported call

1. 在CDR中搜索上报的通话

cdr_search calling="5551234" called="5559999" last="2h"

2. Trace the specific call for all legs and CMR quality data

2. 追踪特定通话的所有分支和CMR质量数据

cdr_trace call_id="<globalcallid_callid from search>"

cdr_trace call_id="<搜索结果中的globalcallid_callid>"

3. Run the returned cisco-dime SDL trace command for SIP analysis

3. 执行返回的cisco-dime SDL trace命令进行SIP分析

(cdr_trace returns a ready-to-run cisco-dime command)

(cdr_trace会返回可直接运行的cisco-dime命令)

4. Cross-reference device config if needed

4. 如需交叉验证设备配置

cisco-axl get Phone --name <device_from_cdr> --format json


**What to look for:**

- Cause code — 16 is normal, anything else indicates an issue (see cause description in results)
- Multiple CDR legs — indicates call was transferred, forwarded, or hit a CTI route
- CMR quality data — MOS, jitter, latency, packet loss for audio quality issues
- Enrichment data — device descriptions, users, pools, locations help identify who/where

cisco-axl get Phone --name <cdr中的设备> --format json


**排查要点：**

- 原因码——16表示正常，其他值都代表有问题（查看结果中的原因描述）
- 多个CDR分支——表示通话被转移、前转或者命中了CTI路由
- CMR质量数据——MOS、抖动、延迟、丢包等，用于排查音频质量问题
- 扩展数据——设备描述、用户、池、位置等信息，帮助识别相关人员/位置

CDR Quality Analysis

CDR质量分析

Tools needed: cisco-cdr (MCP), cisco-perfmon

undefined

所需工具： cisco-cdr (MCP)、cisco-perfmon

undefined

1. Find poor-quality calls

1. 查找低质量通话

cdr_quality mos_below=3.0 last="1d"

2. Check call volume and failure patterns

2. 检查通话量和失败模式

cdr_stats type="by_cause" last="1d" cdr_stats type="by_device" last="1d"

3. Correlate with system health at the time

3. 与对应时间的系统健康状态关联

cisco-perfmon collect "Cisco CallManager" --counter "CallsActive,RegisteredHardwarePhones"


**What to look for:**

- Clusters of low-MOS calls from the same device or location — indicates a network issue in that segment
- High jitter/latency — WAN or QoS problem
- Packet loss — network congestion or misconfigured QoS
- Specific devices with high failure rates — configuration or hardware issue

cisco-perfmon collect "Cisco CallManager" --counter "CallsActive,RegisteredHardwarePhones"


**排查要点：**

- 同一设备或位置的低MOS通话集群——说明该网段存在网络问题
- 高抖动/延迟——WAN或QoS问题
- 丢包——网络拥塞或QoS配置错误
- 特定设备的高失败率——配置或硬件问题

Call Quality / One-Way Audio

通话质量/单通问题

Tools needed: cisco-perfmon, cisco-dime, cisco-risport

bash

undefined

所需工具： cisco-perfmon、cisco-dime、cisco-risport

bash

undefined

1. Check system health

1. 检查系统健康状态

cisco-perfmon collect "Cisco CallManager" --counter "CallsActive,RegisteredHardwarePhones"

2. Check device registration (partially registered = codec issues)

2. 检查设备注册状态（部分注册=编解码器问题）

cisco-risport query --mac <mac>

3. Pull traces for the specific call

3. 拉取特定通话的traces

cisco-dime select sip-traces --last 30m --download

4. If packet captures are available

4. 如果有可用的抓包文件

cisco-dime select "Packet Capture Logs" --last 1h


**What to look for:**

- SDP in SIP traces — are both sides agreeing on codec and media IP?
- One-way audio often means NAT/firewall issue — check the media IPs in SDP
- MTP/transcoder insertion — look for MTP resources in the call flow

cisco-dime select "Packet Capture Logs" --last 1h


**排查要点：**

- SIP traces中的SDP——双方是否就编解码器和媒体IP达成一致？
- 单通通常是NAT/防火墙问题——检查SDP中的媒体IP
- MTP/转码器插入——查找呼叫流中的MTP资源

Performance Investigation

性能排查

Tools needed: cisco-perfmon, cisco-risport, cisco-dime

bash

undefined

所需工具： cisco-perfmon、cisco-risport、cisco-dime

bash

undefined

1. Quick snapshot of key counters

1. 关键计数器快速快照

cisco-perfmon collect "Cisco CallManager" --counter "RegisteredHardwarePhones,CallsActive,CallsAttempted,CallsCompleted" cisco-perfmon collect "Processor" --counter "% CPU Time" cisco-perfmon collect "Memory" --counter "% Memory Used"

2. Live monitoring with sparklines (watch for trends)

2. 带趋势图的实时监控（观察趋势）

cisco-perfmon watch "Cisco CallManager" --counter "CallsActive,RegisteredHardwarePhones" --interval 10

3. Cluster registration summary

3. 集群注册汇总

cisco-risport summary

4. Check for errors in logs

4. 检查日志中的错误

cisco-dime select syslog --last 1h


**What to look for:**

- CPU consistently above 80% — possible resource issue
- RegisteredHardwarePhones dropping — phones losing registration
- CallsActive spiking — possible call loop or toll fraud
- Sparklines show trends — is the value stable, climbing, or oscillating?

cisco-dime select syslog --last 1h


**排查要点：**

- CPU持续高于80%——可能存在资源问题
- RegisteredHardwarePhones下降——话机丢失注册
- CallsActive突增——可能存在呼叫环路或者盗打
- 趋势图显示的变化——数值是稳定、攀升还是波动？

Call Load Testing / Monitoring

呼叫负载测试/监控

Tools needed: cisco-perfmon

bash

undefined

所需工具： cisco-perfmon

bash

undefined

Monitor during a test window with sparklines

测试窗口内带趋势图的监控

cisco-perfmon watch "Cisco CallManager" --counter "CallsActive,CallsAttempted,CallsCompleted,CallsInProgress" --interval 5 --duration 300

Monitor trunk utilization

监控中继利用率

cisco-perfmon watch "Cisco SIP" --counter "CallsActive,CallsAttempted,CallsCompleted" --interval 10

undefined

cisco-perfmon watch "Cisco SIP" --counter "CallsActive,CallsAttempted,CallsCompleted" --interval 10

undefined

Syslog Error → Bug Search

系统日志错误→漏洞搜索

Tools needed: cisco-dime, cisco-support

bash

undefined

所需工具： cisco-dime、cisco-support

bash

undefined

1. Pull syslogs to find errors

1. 拉取系统日志查找错误

cisco-dime select syslog --last 1h --download --decompress

2. Look for error patterns — grep for alarm names, error codes, CSC bug IDs

2. 查找错误模式——grep告警名称、错误码、CSC漏洞ID

Common patterns: %CCM_CALLMANAGER-CALLMANAGER-3-DeviceTransientConnection

常见模式：%CCM_CALLMANAGER-CALLMANAGER-3-DeviceTransientConnection

If you find a CSCxx bug ID in the logs:

如果在日志中找到了CSCxx格式的漏洞ID：

cisco-support bug get CSCvx12345

3. Search for known bugs matching the error

3. 搜索匹配该错误的已知漏洞

cisco-support bug search --keyword "DeviceTransientConnection" --pid "Cisco Unified Communications Manager" cisco-support bug search --keyword "TransientConnection" --severity 1,2,3 --status open

4. Check if there's a PSIRT advisory related to the issue

4. 检查是否有相关的PSIRT安全公告

cisco-support psirt --severity critical


**What to look for:**

- Error messages in syslog often contain Cisco bug IDs (CSCxx format)
- Alarm names map to known bugs — search for the alarm name as a keyword
- If a bug is found, check if it's fixed in a newer release

cisco-support psirt --severity critical


**排查要点：**

- 系统日志中的错误消息通常包含思科漏洞ID（CSCxx格式）
- 告警名称对应已知漏洞——将告警名称作为关键词搜索
- 如果找到漏洞，检查是否在新版本中已修复

Pre-Upgrade Research

升级前调研

Tools needed: cisco-support, cisco-axl

bash

undefined

所需工具： cisco-support、cisco-axl

bash

undefined

1. Check current CUCM version

1. 检查当前CUCM版本

cisco-axl sql query "SELECT version FROM componentversion WHERE softwarecomponent='callmanager'"

2. Get software suggestions for your platform

2. 获取对应平台的软件建议

cisco-support software suggest --pid CUCM-LIC-15

3. Compare bugs between current and target version

3. 对比当前版本和目标版本的漏洞差异

cisco-support software compare --pid CUCM-LIC-15 --from 14.0 --to 15.0

4. Check for security advisories affecting target version

4. 检查影响目标版本的安全公告

cisco-support psirt --severity critical --year 2026

5. Check if any hardware is end-of-life

5. 检查是否有硬件已到生命周期末期

cisco-support eox --pid CP-8841-K9 cisco-support serial warranty FJC12345678

undefined

cisco-support eox --pid CP-8841-K9 cisco-support serial warranty FJC12345678

undefined

Hardware Lifecycle Check

硬件生命周期检查

Tools needed: cisco-support, cisco-axl

bash

undefined

所需工具： cisco-support、cisco-axl

bash

undefined

1. Get all phone models in the cluster

1. 获取集群中的所有话机型号

cisco-axl sql query "SELECT DISTINCT tm.name AS model, COUNT(*) AS cnt FROM device d JOIN typemodel tm ON d.tkmodel=tm.enum WHERE d.tkclass=1 GROUP BY tm.name ORDER BY cnt DESC"

2. Check EoX status for each model

2. 检查每个型号的EoX状态

cisco-support eox --pid CP-8841-K9 cisco-support eox --pid CP-7841-K9 cisco-support eox --pid CP-8865-K9

3. Check warranty for specific serial numbers

3. 检查特定序列号的保修状态

cisco-support serial coverage FJC12345678

undefined

cisco-support serial coverage FJC12345678

undefined

Audit / Change Investigation

审计/变更排查

Tools needed: cisco-dime, cisco-axl

bash

undefined

所需工具： cisco-dime、cisco-axl

bash

undefined

1. Pull audit logs to see who changed what

1. 拉取审计日志查看谁做了什么变更

cisco-dime select audit --last 1d --download

2. Look at a specific object's current config

2. 查看特定对象的当前配置

cisco-axl get Phone --name <device> --format json

3. Compare with expected config

3. 和预期配置对比

cisco-axl sql query "SELECT * FROM device WHERE name='<device>'"

undefined

cisco-axl sql query "SELECT * FROM device WHERE name='<device>'"

undefined

Provisioning Workflows

配置部署工作流

New Phone Setup

新话机配置

Tools needed: cisco-axl

bash

undefined

所需工具： cisco-axl

bash

undefined

1. Add the line

1. 添加线路

cisco-axl add Line --data '{"pattern":"1001","routePartitionName":"PT_INTERNAL","description":"John Doe"}'

2. Add the phone

2. 添加话机

cisco-axl add Phone --data '{"name":"SEP001122334455","product":"Cisco 8841","class":"Phone","protocol":"SIP","devicePoolName":"DP_HQ","lines":{"line":{"index":"1","dirn":{"pattern":"1001","routePartitionName":"PT_INTERNAL"}}}}'

3. Verify registration

3. 验证注册状态

cisco-risport query --mac 001122334455

undefined

cisco-risport query --mac 001122334455

undefined

Bulk Provisioning

批量配置

Tools needed: cisco-axl

bash

undefined

所需工具： cisco-axl

bash

undefined

From CSV

从CSV导入

cisco-axl add Phone --csv phones.csv cisco-axl add Line --csv lines.csv

Verify all registered

验证全部注册

cisco-risport summary --model "Cisco 8841"

undefined

cisco-risport summary --model "Cisco 8841"

undefined

SBC Troubleshooting (AudioCodes)

SBC故障排查（AudioCodes）

Tools needed: audiocodes-cli, cisco-dime

bash

undefined

所需工具： audiocodes-cli、cisco-dime

bash

undefined

1. Check SBC health

1. 检查SBC健康状态

audiocodes-cli doctor --device <sbc>

2. Check active alarms (proxy sets down, IP groups blocked, cert expiry)

2. 检查活跃告警（代理集下线、IP组被阻止、证书过期）

audiocodes-cli alarms list --device <sbc>

3. Check call statistics — are calls getting through?

3. 检查通话统计——呼叫是否成功接通？

audiocodes-cli calls list --device <sbc>

4. Check KPIs — license usage, DDoS stats, media quality

4. 检查KPI——许可证使用情况、DDoS统计、媒体质量

audiocodes-cli kpi show system/licenseStats/global --device <sbc> audiocodes-cli kpi show network/ddosStats/global --device <sbc>

5. Backup SBC config for review

5. 备份SBC配置用于分析

audiocodes-cli device backup --device <sbc>

6. Cross-reference with CUCM SDL logs to trace calls end-to-end

6. 和CUCM SDL日志交叉验证，端到端追踪通话

cisco-dime select "Cisco CallManager" --last 30m --all-nodes --include-active --download --decompress


**What to look for:**

- IP Group blocked alarms — proxy set connectivity issues between SBC and CUCM/carrier
- Call stats: attempted vs established — large gap means routing or far-end rejection
- "No Answer" vs "Other Reason" — no answer is far-end, other reason is often 4xx/5xx from carrier
- CUCM SDL logs show the SIP trunk name and response codes for calls leaving CUCM to the SBC

cisco-dime select "Cisco CallManager" --last 30m --all-nodes --include-active --download --decompress


**排查要点：**

- IP组被阻止告警——SBC和CUCM/运营商之间的代理集连通性问题
- 通话统计：尝试呼叫 vs 接通呼叫——差距大说明存在路由问题或对端拒绝
- "无应答" vs "其他原因"——无应答是对端问题，其他原因通常是运营商返回的4xx/5xx错误
- CUCM SDL日志会显示SIP中继名称以及CUCM发往SBC的呼叫响应码

CUCM-to-SBC Call Flow Investigation

CUCM到SBC呼叫流排查

Tools needed: audiocodes-cli, cisco-dime, cisco-axl

bash

undefined

所需工具： audiocodes-cli、cisco-dime、cisco-axl

bash

undefined

1. Check which SIP trunk CUCM uses for the route pattern

1. 检查CUCM用于该路由模式的SIP中继

cisco-axl sql query "SELECT dnorpattern, routePartitionName FROM numplan WHERE dnorpattern LIKE '%<pattern>%'"

2. Pull CUCM call logs to see the INVITE flow

2. 拉取CUCM呼叫日志查看INVITE流

cisco-dime select "Cisco CallManager" --last 30m --download --decompress

grep for the dialed number in calllogs

在呼叫日志中grep拨号号码

3. Check the SBC side — did it receive the call?

3. 检查SBC侧——是否收到呼叫？

audiocodes-cli calls list --device <sbc>

4. Check SBC alarms — is the outbound IP group healthy?

4. 检查SBC告警——出站IP组是否正常？

audiocodes-cli alarms list --device <sbc>

undefined

audiocodes-cli alarms list --device <sbc>

undefined

End-to-End Call Trace (CUCM → SBC → Genesys Cloud)

端到端通话追踪（CUCM → SBC → Genesys Cloud）

Tools needed: cisco-axl, cisco-dime, cisco-risport, audiocodes-cli, genesys-cli

bash

undefined

所需工具： cisco-axl、cisco-dime、cisco-risport、audiocodes-cli、genesys-cli

bash

undefined

1. Verify the CUCM line/device and call forward config

1. 验证CUCM线路/设备和呼叫前转配置

cisco-axl sql query "SELECT dnorpattern, description FROM numplan WHERE dnorpattern = '<extension>'" cisco-axl sql query "SELECT cfadestination FROM callforwarddynamic cf JOIN numplan np ON cf.fknumplan = np.pkid WHERE np.dnorpattern = '<extension>'"

2. Check registration of the SIP trunk to the SBC

2. 检查到SBC的SIP中继注册状态

cisco-risport query --name "<trunk_name>"

3. Pull CUCM SDL traces and grep for the call

3. 拉取CUCM SDL traces并grep目标通话

cisco-dime select "Cisco CallManager" --last 30m --all-nodes --include-active --download --decompress

grep for the dialed number, Call-ID, and trunk name in SDL files

在SDL文件中grep拨号号码、Call-ID和中继名称

4. Check the AudioCodes SBC — did it receive and relay the call?

4. 检查AudioCodes SBC——是否收到并转发了呼叫？

audiocodes-cli doctor --device <sbc> audiocodes-cli calls list --device <sbc> audiocodes-cli alarms list --device <sbc>

5. Check Genesys Cloud — did the call arrive?

5. 检查Genesys Cloud——是否收到呼叫？

genesys-cli doctor genesys-cli conversations list --caller <calling_number> --last 1h genesys-cli conversations list --callee <called_number> --last 1h

6. Check BYOC trunk health on Genesys side

6. 检查Genesys侧的BYOC中继健康状态

genesys-cli trunks list genesys-cli trunks metrics


**What to look for:**

- CUCM SDL: confirm INVITE sent to SBC IP, look for `call_active` state and `200 OK`
- AudioCodes: compare attempted vs established calls — large gap means rejection
- AudioCodes alarms: Proxy Set down alarms indicate Genesys connectivity issues
- Genesys conversations: matching caller/callee confirms end-to-end delivery
- Genesys trunks: `connected` + `inService=true` means BYOC trunk is healthy
- Blank `disconnectType` and `sipResponseCode` in Genesys = normal call handling

genesys-cli trunks list genesys-cli trunks metrics


**排查要点：**

- CUCM SDL：确认INVITE已发送到SBC IP，查找`call_active`状态和`200 OK`
- AudioCodes：对比尝试呼叫和接通呼叫——差距大说明存在拒绝
- AudioCodes告警：代理集下线告警说明Genesys连通性问题
- Genesys会话：匹配的主叫/被叫确认端到端投递成功
- Genesys中继：`connected` + `inService=true`表示BYOC中继正常
- Genesys中空白的`disconnectType`和`sipResponseCode`表示呼叫处理正常

Genesys Cloud Troubleshooting

Genesys Cloud故障排查

Tools needed: genesys-cli

bash

undefined

所需工具： genesys-cli

bash

undefined

1. Check Genesys Cloud connectivity and org health

1. 检查Genesys Cloud连通性和组织健康状态

genesys-cli doctor

2. Check BYOC trunk status — are trunks connected?

2. 检查BYOC中继状态——中继是否已连接？

genesys-cli trunks list genesys-cli trunks metrics

3. Check Edge server status

3. 检查Edge服务器状态

genesys-cli edges list

4. Search conversation history for a specific call

4. 搜索特定通话的会话历史

genesys-cli conversations list --caller <number> --last 1h genesys-cli conversations list --callee <number> --last 1h genesys-cli conversations list --queue <queue_name> --last 1h

5. Get full detail for a specific conversation

5. 获取特定会话的完整详情

genesys-cli conversations detail <conversationId>

6. Check agent availability

6. 检查坐席可用性

genesys-cli agents list

7. Check queue status

7. 检查队列状态

genesys-cli queues list

8. Review recent config changes

8. 查看最近的配置变更

genesys-cli audit list


**What to look for:**

- BYOC trunks not `connected` or `inService=false` — SBC-to-Genesys SIP connectivity issue
- Edge servers OFFLINE — media processing issues
- Conversations with `disconnectType` values like `error` or `system` — abnormal terminations
- High `sipResponseCode` (4xx/5xx) — SIP-level failures
- Agent presence — are agents available to take calls?
- Queue member count — are agents assigned to the expected queues?

genesys-cli audit list


**排查要点：**

- BYOC中继未处于`connected`状态或`inService=false`——SBC到Genesys的SIP连通性问题
- Edge服务器离线——媒体处理问题
- 会话的`disconnectType`值为`error`或`system`——异常终止
- 高`sipResponseCode`（4xx/5xx）——SIP层级失败
- 坐席状态——坐席是否可接听呼叫？
- 队列成员数——是否有坐席分配到目标队列？

Diagnostic Decision Tree

诊断决策树

When the user reports a problem, follow this order:

Is it registered to CUCM? →
```
cisco-risport query --mac <mac>
```
Is the config correct? →
```
cisco-axl get Phone --name <name>
```
What do the CDRs show? →
```
cdr_search calling="<number>" last="2h"
```
(if cisco-cdr MCP is available)
What do the logs show? →
```
cisco-dime select sip-traces --last 30m
```

Is the system healthy? →

cisco-perfmon collect "Cisco CallManager" --counter "CallsActive"

Was call quality poor? →
```
cdr_quality mos_below=3.5 last="2h"
```
(if cisco-cdr MCP is available)

Are there known bugs? →

cisco-support bug search --keyword "<error>" --pid "Cisco Unified Communications Manager"

Is the hardware end-of-life? →
```
cisco-support eox --pid <model>
```

Did the call reach Genesys? →

genesys-cli conversations list --caller <number> --last 1h

Is the BYOC trunk healthy? →
```
genesys-cli trunks list
```

Start broad, narrow down. Don't pull traces until you've checked the basics. If the cisco-cdr MCP server is available, CDR search is a fast way to confirm whether a call happened and what the outcome was before diving into logs.

用户上报问题时，按以下顺序排查：

设备是否注册到CUCM？ →
```
cisco-risport query --mac <mac>
```
配置是否正确？ →
```
cisco-axl get Phone --name <name>
```
CDR显示什么内容？ → 如果cisco-cdr MCP可用，执行
```
cdr_search calling="<number>" last="2h"
```
日志显示什么内容？ →
```
cisco-dime select sip-traces --last 30m
```

系统是否健康？ →

cisco-perfmon collect "Cisco CallManager" --counter "CallsActive"

通话质量是否不佳？ → 如果cisco-cdr MCP可用，执行
```
cdr_quality mos_below=3.5 last="2h"
```

是否存在已知漏洞？ →

cisco-support bug search --keyword "<error>" --pid "Cisco Unified Communications Manager"

硬件是否到生命周期末期？ →
```
cisco-support eox --pid <model>
```

呼叫是否到达Genesys？ →

genesys-cli conversations list --caller <number> --last 1h

BYOC中继是否正常？ →
```
genesys-cli trunks list
```

从宽泛到具体逐步缩小范围，检查完基础项之前不要拉取日志。如果cisco-cdr MCP服务器可用，CDR搜索是确认呼叫是否发生以及结果的快速方式，可在深入日志排查之前执行。

Important Notes

重要注意事项

All tools support
```
--format json
```
for structured output — use this when you need to parse results programmatically or correlate data across tools.
All tools support
```
--cluster <name>
```
to target a specific cluster — useful when the user has multiple CUCM environments.
All CUCM tools (axl, dime, perfmon, risport) share the same CUCM host.
When pulling logs with cisco-dime, note that timestamps from CUCM are in the server's timezone. Use
```
--timezone
```
to convert.
Use
```
cisco-perfmon watch
```
for live monitoring with sparklines — great for observing trends during testing or incidents.
Use
```
cisco-dime analyze sip-ladder
```
to render SIP call flow diagrams from SDL trace files.
All tools have a
```
doctor
```
command for health checks — run
```
cisco-<tool> doctor
```
or
```
genesys-cli doctor
```
to verify connectivity.
genesys-cli uses OAuth client credentials and connects to the Genesys Cloud Platform API. It supports
```
--org <name>
```
for multi-org environments and
```
--region <region>
```
to target different Genesys Cloud regions (e.g., usw2, use1, aps1).
When tracing calls end-to-end across CUCM → SBC → Genesys, correlate by timestamp and caller/callee numbers across all three systems.

所有工具都支持
```
--format json
```
输出结构化数据——需要编程解析结果或跨工具关联数据时使用该参数。
所有工具都支持
```
--cluster <名称>
```
指定目标集群——用户有多个CUCM环境时非常有用。
所有CUCM工具（axl、dime、perfmon、risport）共用相同的CUCM主机。
使用cisco-dime拉取日志时，注意CUCM的时间戳是服务器时区，可使用
```
--timezone
```
转换。
使用
```
cisco-perfmon watch
```
进行带趋势图的实时监控——非常适合在测试或故障期间观察趋势。
使用
```
cisco-dime analyze sip-ladder
```
从SDL trace文件生成SIP呼叫流图。
所有工具都有
```
doctor
```
命令用于健康检查——执行
```
cisco-<工具名> doctor
```
或
```
genesys-cli doctor
```
验证连通性。
genesys-cli使用OAuth客户端凭证连接Genesys Cloud平台API，支持
```
--org <名称>
```
用于多组织环境，支持
```
--region <区域>
```
指定不同的Genesys Cloud区域（例如usw2、use1、aps1）。
跨CUCM→SBC→Genesys端到端追踪通话时，通过时间戳和主叫/被叫号码在三个系统之间关联数据。

cisco-uc-engineer

Original

Translation

Cisco UC Engineer

思科UC工程师

Tool Detection

工具检测

Check each tool — run all five, note which succeed

检查每个工具 — 运行全部五个命令，记录执行成功的工具

Check cisco-cdr MCP server (requires MCP configuration, not a CLI tool)

检查cisco-cdr MCP服务器（需要MCP配置，不是CLI工具）

Verify by calling: cdr_health

调用以下命令验证：cdr_health

Available Tools

可用工具

Cluster Alignment

集群对齐

Check active cluster for each installed tool

检查每个已安装工具的活跃集群

Troubleshooting Workflows

故障排查工作流

Phone Not Registering

话机注册失败

1. Check phone config in CUCM

1. 检查CUCM中的话机配置

2. Check current registration status

2. 检查当前注册状态

3. Pull recent SIP traces for this device

3. 拉取该设备最近的SIP traces

Call Routing Issue

呼叫路由问题

1. Check the dialed pattern

1. 检查拨号模式

2. Check the CSS chain

2. 检查CSS链路

3. Check route patterns and route lists

3. 检查路由模式和路由列表

4. Pull SIP traces to see the actual call flow

4. 拉取SIP traces查看实际呼叫流

CDR-Based Call Investigation

基于CDR的通话排查

1. Search CDR for the reported call

1. 在CDR中搜索上报的通话

2. Trace the specific call for all legs and CMR quality data

2. 追踪特定通话的所有分支和CMR质量数据

3. Run the returned cisco-dime SDL trace command for SIP analysis

3. 执行返回的cisco-dime SDL trace命令进行SIP分析

(cdr_trace returns a ready-to-run cisco-dime command)

(cdr_trace会返回可直接运行的cisco-dime命令)

4. Cross-reference device config if needed

4. 如需交叉验证设备配置

CDR Quality Analysis

CDR质量分析

1. Find poor-quality calls

1. 查找低质量通话

2. Check call volume and failure patterns

2. 检查通话量和失败模式

3. Correlate with system health at the time

3. 与对应时间的系统健康状态关联

Call Quality / One-Way Audio

通话质量/单通问题

1. Check system health

1. 检查系统健康状态

2. Check device registration (partially registered = codec issues)

2. 检查设备注册状态（部分注册=编解码器问题）

3. Pull traces for the specific call

3. 拉取特定通话的traces

4. If packet captures are available

4. 如果有可用的抓包文件

Performance Investigation

性能排查

1. Quick snapshot of key counters

1. 关键计数器快速快照

2. Live monitoring with sparklines (watch for trends)

2. 带趋势图的实时监控（观察趋势）

3. Cluster registration summary

3. 集群注册汇总

4. Check for errors in logs

4. 检查日志中的错误

Call Load Testing / Monitoring