Network AIops

network-aiops

免责声明：这是一个由社区维护的开源项目，**与 Cisco、Arista、Juniper、NetBox Labs 或任何网络供应商均无关联，也未获得其认可或赞助。**供应商和产品名称均为各自 所有者的商标。源代码可在 github.com/AIops-tools/Network-AIops 上公开审查，采用 MIT 许可证。

面向 AI Agent 的多供应商网络设备受治理操作——33 个 MCP 工具，每个工具都由内置的 @governed_tool 执行框架封装：在 ~/.network-aiops/ 下记录本地统一审计日志，限制令牌和运行预算，记录撤销令牌，并标注清晰的风险级别。凭据（设备密码和 NetBox 令牌）保存在加密存储（secrets.enc）中，不会以明文形式存储在磁盘上。

设备通过 NAPALM 连接；可选的 NetBox 模块会添加真实数据源查询功能。

独立运行：治理执行框架已内置于软件包中 （network_aiops.governance）——network-aiops 无需依赖外部技能系列。 覆盖范围侧重于常见设备操作，尚未涵盖所有操作。

验证状态：测试套件基于模拟；尚未在实际设备上验证——可使用 cEOS / vMX / containerlab 自行测试。请参阅 docs/VERIFICATION.md。

支持的功能

读取设备信息、接口（及计数器 / IP）、BGP/LLDP 邻居（摘要和详情）、ARP/MAC 表、VLAN、路由查询、硬件环境、光模块、NTP、用户、SNMP 信息、VRF，以及汇总的 device_health；运行只读的 RCA 诊断，标记接口断开 / 出错 / 状态抖动以及不健康的 BGP 邻居——每项发现都会注明触发判定的测量数值；备份运行配置、试运行配置差异，以及合并 / 替换 / 回滚配置——支持以下五种核心 NAPALM 平台。可选的 NetBox 查询（设备和接口）可在变更前确认预期状态。

NAPALM 并未在所有平台上实现每个 getter；不受支持的 getter 会返回说明性错误（“<driver> 驱动不支持”），而不会导致程序崩溃。不会返回机密信息——get_users 会隐藏密码哈希，get_snmp_information 会隐藏团体字符串。

支持的设备

平台	NAPALM 驱动	传输方式
Cisco IOS / IOS-XE	ios	SSH
Cisco Nexus NX-OS	nxos (NX-API) / nxos_ssh (SSH)	HTTPS / SSH
Cisco IOS-XR	iosxr	SSH (XML agent)
Arista EOS	eos	eAPI (HTTPS)
Juniper Junos	junos	NETCONF (SSH)

其他平台（Nokia SR OS / SR Linux、Huawei VRP 等）可通过 NAPALM 社区驱动连接，但未经本项目正式测试。需要支持某个平台？ 请参阅贡献与功能请求。

支持的操作

操作	工具	R/W	风险
设备信息（主机名/供应商/型号/OS/序列号/运行时间）	device_facts	R	低
接口（运行状态、速度、描述）	get_interfaces	R	低
接口流量和错误计数器	get_interfaces_counters	R	低
接口 IP 地址	get_interfaces_ip	R	低
BGP 邻居（摘要 / 详情）	get_bgp_neighbors / get_bgp_neighbors_detail	R	低
LLDP 邻居（摘要 / 详情）	get_lldp_neighbors / get_lldp_neighbors_detail	R	低
ARP 表	get_arp_table	R	低
MAC 地址表	get_mac_address_table	R	低
VLAN	get_vlans	R	低
路由查询	get_route_to	R	低
硬件环境（风扇/温度/电源/CPU/内存）	get_environment	R	低
光收发器电平	get_optics	R	低
NTP 服务器 / 同步统计信息	get_ntp_servers / get_ntp_stats	R	低
本地用户（哈希值已隐藏）	get_users	R	低
SNMP 信息（团体名已隐藏）	get_snmp_information	R	低
网络实例（VRF）	get_network_instances	R	低
设备健康状态汇总	device_health	R	低
接口健康状态 RCA（关闭 / 错误 / 丢弃 / 状态抖动）	interface_health_rca	R	低
BGP 邻居 RCA（关闭 / 管理性关闭 / 重置 / 无路由）	bgp_neighbor_rca	R	低
备份运行配置	config_backup	R	低
对候选配置进行差异比较（试运行）	config_diff	R	低
合并配置并提交	config_merge	W	中
替换完整配置并提交	config_replace	W	高
回滚上次提交	config_rollback	W	中
NetBox 设备列表	netbox_list_devices	R	低
NetBox 获取设备	netbox_get_device	R	低
NetBox 设备接口	netbox_device_interfaces	R	低
列出已记录的可逆写入操作	undo_list	R	低
应用已记录的逆操作（受控、单次使用，可进行试运行）	undo_apply	W	中

此工具会做什么，不会决定什么

它能够准确、高效地执行多厂商网络设备（NAPALM）和 NetBox 操作——读取和写入——并记录每一项操作。它不会决定是否允许执行写入操作。这取决于 Agent 的判断，或你用来连接的账户权限：使用只读权限级别的设备账户登录（并为 NetBox 提供只读 API 令牌），写入操作就会在服务器上失败——权限实际由服务器控制。

因此，无需配置只读开关、策略文件或审批关卡。此工具唯一能保证的是所有操作都有迹可循：每次调用，无论通过 MCP 还是 CLI，都将生成一条审计记录，写入 ~/.network-aiops/audit.db；破坏性写入仍会保存操作前的状态，并在存在逆操作时记录该操作。

每个工具都会声明一个 risk_level，并将其作为描述性级别（none/confirm/review）写入审计记录——审核人员可以一眼看出某条记录涉及高风险删除。这只是标签，不是关卡。

正在运行更小型 / 本地模型？请参阅 agent-guardrails.md——其中列出了此工具为你强制执行的防护措施（这样你就不必在提示词中重复说明），并提供了一个可直接使用的系统提示词，用于处理其余事项。

快速入门

作为 Claude Code 插件使用

一次安装即可为 Agent 同时提供 skill 和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install network-aiops@aiops-tools

MCP 服务通过 uv 获取，并固定为此插件声明的包版本，因此可以追溯审计记录对应的写入代码。凭据仍需通过 network-aiops init 配置——请参阅下文。

作为 OpenClaw 插件

同一套软件包也发布在 ClawHub 上，安装一次即可同时安装技能和 MCP 服务：

openclaw plugins install clawhub:@zw008/network-aiops
openclaw skills info network-aiops          # expect: Visible to model: yes

之后重启 OpenClaw 网关，使其加载插件。MCP 服务会通过 uv 获取，并固定到此确切版本，因此 uvx 必须位于 PATH 中——如果没有，技能仍会安装，但会报告 Visible to model: no。凭据配置如下。

作为 CLI 或独立 MCP 服务

uv tool install network-aiops
network-aiops init                                  # wizard: device + driver + host + encrypted password
network-aiops doctor
network-aiops device facts -t core-sw1
network-aiops device health -t core-sw1
network-aiops diagnose interface-health -t core-sw1   # worst-first interface RCA
network-aiops diagnose bgp -t core-sw1                # worst-first BGP-neighbor RCA
network-aiops config backup -t core-sw1 -o core-sw1.cfg

操作手册：修改配置前排查不稳定的上行链路

# 1. Ask the device what's actually wrong — findings are ranked worst-first and
#    each cites the measured value (error count, last-flap seconds, uptime).
network-aiops diagnose interface-health -t core-sw1
network-aiops diagnose bgp -t core-sw1

# 2. If interface-health flags a link admin-up/oper-down with climbing errors and
#    BGP shows the peer on that path recently reset, you have your root cause: a
#    physical-layer fault (cable/optic) resetting the session — not routing.

# 3. Confirm intended state, then remediate with the governed, audited path.
network-aiops device counters -t core-sw1
network-aiops config diff -t core-sw1 -f fix.cfg      # dry-run the change first

创建 ~/.network-aiops/config.yaml：

devices:
  - name: core-sw1            # used as -t core-sw1
    driver: eos               # ios | nxos | nxos_ssh | iosxr | eos | junos
    host: 10.0.0.1
    username: admin
    optional_args:            # passed verbatim to NAPALM (optional)
      secret: enable-pw       # enable/secret
      port: 443
# Optional source-of-truth:
netbox:
  url: https://netbox.example.com

密钥以加密形式存储在 ~/.network-aiops/secrets.enc 中（Fernet/AES + scrypt 派生密钥；chmod 600）——绝不会存放在 config.yaml 或明文 .env 中。设备密码以设备名称为键；NetBox 令牌使用保留名称 netbox-token：

network-aiops init                     # interactive wizard (recommended)
network-aiops secret set core-sw1      # store a device password (hidden prompt)
network-aiops secret set netbox-token  # store the NetBox API token
network-aiops secret list              # names only — values are never printed
network-aiops secret migrate           # import a legacy plaintext .env, then delete it

设置 NETWORK_AIOPS_MASTER_PASSWORD，即可在非交互模式下解锁存储（MCP 服务 / cron）。旧版明文环境变量（NETWORK_<TARGET_UPPER>_PASSWORD、NETWORK_NETBOX_TOKEN）仍作为已弃用的回退选项。使用基于密钥的 SSH 身份验证时，允许设备密码为空。

MCP

{
  "command": "network-aiops",
  "args": ["mcp"],
  "env": {
    "NETWORK_AIOPS_CONFIG": "~/.network-aiops/config.yaml",
    "NETWORK_AIOPS_MASTER_PASSWORD": "…"   // unlocks the encrypted secret store
  }
}

审计与安全

• 每次工具调用都会记录到 ~/.network-aiops/audit.db（本地 SQLite；通过 NETWORK_AIOPS_HOME 更改位置）。
• config_merge / config_replace 会捕获变更前的运行配置，并记录指向备份的反向 config_replace 撤销描述。
• config_replace 的 risk_level=high；CLI 破坏性命令（config merge/replace/rollback）需要二次确认，并支持 --dry-run（打印差异，但不提交变更）。
• 所有设备文本都会经过 sanitize() 处理（输出卫生：剥除控制字符 / 格式字符并截断）。
• 设备密码和 NetBox 令牌仅存放在加密的 secrets.enc 中（chmod 600）；工具绝不会返回密码、SNMP 社区字符串或哈希值。

详情请参阅 skills/network-aiops/SKILL.md 和 SECURITY.md。

配套技能

如果你需要……	使用
网络设备配置 / 信息（Cisco/Arista/Juniper）	network-aiops（本技能）
Kubernetes 集群运维	集群运维技能
虚拟机监控程序 VM 生命周期管理	虚拟机监控程序运维技能

贡献与功能请求

本项目有意专注于特定范围。**需要的设备或操作尚未支持？**欢迎在 github.com/AIops-tools/Network-AIops 提交 issue 或拉取请求——我们欢迎贡献、功能请求和评论。

许可证

MIT — github.com/AIops-tools/Network-AIops