{"id":"ff4a48c1-e2fd-4247-b04e-adcf3b798208","entityType":"agent","slug":"clawhub-zw008-proxy-aiops","name":"proxy-aiops","canonicalUrl":"https://www.xpersona.co/agent/clawhub-zw008-proxy-aiops","canonicalPath":"/agent/clawhub-zw008-proxy-aiops","generatedAt":"2026-10-10T21:43:28.536Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:07:11.725Z","emptyReason":null},"description":"Use this skill whenever the user needs to operate a Traefik, Caddy or HAProxy reverse proxy / load balancer — a one-shot overview, routes (routers / caddy routes / frontends) with host/path matching, services and server-level upstream health, middlewares, TLS certificate inventory with an expiry sweep, traffic and 5xx error counters, config snapshot/search, four flagship RCAs (backend health, cert expiry, error rate, route conflicts), and governed writes (caddy config set/delete/load with prior-config capture; haproxy server drain/maint/ready and weight). Always use this skill for \"Traefik\", \"Caddy\", \"HAProxy\", \"reverse proxy\", \"load balancer\", \"upstream down\", \"502/503/504 errors\", \"bad gateway\", \"cert expiring\", \"TLS certificate\", \"route not matching\", \"which route serves this host\", \"drain a server\", \"server weight\", \"redirect loop\" when the context is a Traefik/Caddy/HAProxy edge. Do NOT use when the target is something other than a Traefik/Caddy/HAProxy proxy (a hypervisor, storage appliance, backup product, container-orchestration cluster, multi-vendor router/switch config, or OT/industrial equipment) — route those to the appropriate other AIops-tools skill. Do NOT use for firewall rules — use firewall-aiops. Managed cloud load balancers are out of scope. Governed proxy operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers). Behaviour is validated by a mock-based test suite; see docs/VERIFICATION.md for the live-verification checklist.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.3K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:proxy-aiops","sourceUrl":"https://clawhub.ai/zw008/proxy-aiops","homepage":"https://clawhub.ai/zw008/skills/proxy-aiops","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/zw008/proxy-aiops","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/zw008/skills/proxy-aiops","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"proxy-aiops technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:07:11.725Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:07:11.725Z","emptyReason":null},"stars":null,"forks":null,"downloads":1326,"packageName":null,"latestVersion":"0.9.4","tractionLabel":"1.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:07:11.725Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T17:07:11.725Z","lastCrawledAt":"2026-10-10T17:07:11.725Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T17:07:11.725Z","lastVerifiedAt":null,"highlights":[{"version":"0.9.4","createdAt":"2026-09-16T23:26:31.173Z","changelog":"proxy-aiops 0.9.4 - Updated agent-guardrails documentation. - Removed the skill-card.md file.","fileCount":7,"zipByteSize":19027},{"version":"0.9.3","createdAt":"2026-09-15T06:18:15.482Z","changelog":"- Removed the file skill-card.md. - No feature or functionality changes in this release.","fileCount":7,"zipByteSize":18599},{"version":"0.9.2","createdAt":"2026-09-12T14:41:48.908Z","changelog":"- Removed the redundant skill-card.md file to streamline documentation. - Minor update to SKILL.md: example OpenClaw plugin install command updated from @a to @z.","fileCount":7,"zipByteSize":18442},{"version":"0.9.1","createdAt":"2026-09-12T10:25:21.396Z","changelog":"proxy-aiops 0.9.1 - Documentation updated: SKILL.md revised with new installation instructions including OpenClaw plugin setup. - File cleanup: skill-card.md was removed. - No functional changes to the skill's features or compatibility.","fileCount":7,"zipByteSize":18476},{"version":"0.9.0","createdAt":"2026-09-12T01:13:07.727Z","changelog":"proxy-aiops v0.9.0 - Updated binaries requirement in metadata: now supports either proxy-aiops or uvx. - Clarified and simplified environment variable and metadata configuration. - Removed unnecessary skill-card.md file for easier maintenance. - Improved compatibility documentation and clarified credential handling. - Minor corrections and edits to SKILL.md for clarity and up-to-date guidance.","fileCount":7,"zipByteSize":18532},{"version":"0.8.0","createdAt":"2026-08-10T06:53:49.747Z","changelog":"- Removed the file skill-card.md. - No other changes to documentation or functionality.","fileCount":7,"zipByteSize":18200},{"version":"0.7.0","createdAt":"2026-08-03T05:54:43.050Z","changelog":"proxy-aiops 0.7.0 - Removed the file: skill-card.md - No feature or behavioral changes; this is a minor cleanup.","fileCount":7,"zipByteSize":18416},{"version":"0.6.0","createdAt":"2026-08-02T09:41:30.044Z","changelog":"- Removed the sample file skill-card.md. - No changes to functionality or documentation content. - Maintenance update with minor cleanup.","fileCount":7,"zipByteSize":18498}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:proxy-aiops","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:proxy-aiops` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/zw008/proxy-aiops before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxy-aiops/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxy-aiops/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxy-aiops/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxy-aiops/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxy-aiops/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxy-aiops/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T21:43:28.532Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxy-aiops/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxy-aiops/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxy-aiops/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxy-aiops/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:07:11.725Z","emptyReason":null},"readme":"Skill: proxy-aiops\n\nOwner: zw008\n\nSummary: Use this skill whenever the user needs to operate a Traefik, Caddy or HAProxy reverse proxy / load balancer — a one-shot overview, routes (routers / caddy routes / frontends) with host/path matching, services and server-level upstream health, middlewares, TLS certificate inventory with an expiry sweep, traffic and 5xx error counters, config snapshot/search, four flagship RCAs (backend health, cert expiry, error rate, route conflicts), and governed writes (caddy config set/delete/load with prior-config capture; haproxy server drain/maint/ready and weight). Always use this skill for \"Traefik\", \"Caddy\", \"HAProxy\", \"reverse proxy\", \"load balancer\", \"upstream down\", \"502/503/504 errors\", \"bad gateway\", \"cert expiring\", \"TLS certificate\", \"route not matching\", \"which route serves this host\", \"drain a server\", \"server weight\", \"redirect loop\" when the context is a Traefik/Caddy/HAProxy edge. Do NOT use when the target is something other than a Traefik/Caddy/HAProxy proxy (a hypervisor, storage appliance, backup product, container-orchestration cluster, multi-vendor router/switch config, or OT/industrial equipment) — route those to the appropriate other AIops-tools skill. Do NOT use for firewall rules — use firewall-aiops. Managed cloud load balancers are out of scope. Governed proxy operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers). Behaviour is validated by a mock-based test suite; see docs/VERIFICATION.md for the live-verification checklist.\n\nTags: latest:0.9.4\n\nVersion history:\n\nv0.9.4 | 2026-09-16T23:26:31.173Z | auto\n\nproxy-aiops 0.9.4\n\n- Updated agent-guardrails documentation.\n- Removed the skill-card.md file.\n\nv0.9.3 | 2026-09-15T06:18:15.482Z | auto\n\n- Removed the file skill-card.md.\n- No feature or functionality changes in this release.\n\nv0.9.2 | 2026-09-12T14:41:48.908Z | auto\n\n- Removed the redundant skill-card.md file to streamline documentation.\n- Minor update to SKILL.md: example OpenClaw plugin install command updated from @a to @z.\n\nv0.9.1 | 2026-09-12T10:25:21.396Z | auto\n\nproxy-aiops 0.9.1\n\n- Documentation updated: SKILL.md revised with new installation instructions including OpenClaw plugin setup.\n- File cleanup: skill-card.md was removed.\n- No functional changes to the skill's features or compatibility.\n\nv0.9.0 | 2026-09-12T01:13:07.727Z | auto\n\nproxy-aiops v0.9.0\n\n- Updated binaries requirement in metadata: now supports either proxy-aiops or uvx.\n- Clarified and simplified environment variable and metadata configuration.\n- Removed unnecessary skill-card.md file for easier maintenance.\n- Improved compatibility documentation and clarified credential handling.\n- Minor corrections and edits to SKILL.md for clarity and up-to-date guidance.\n\nv0.8.0 | 2026-08-10T06:53:49.747Z | auto\n\n- Removed the file skill-card.md.\n- No other changes to documentation or functionality.\n\nv0.7.0 | 2026-08-03T05:54:43.050Z | auto\n\nproxy-aiops 0.7.0\n\n- Removed the file: skill-card.md\n- No feature or behavioral changes; this is a minor cleanup.\n\nv0.6.0 | 2026-08-02T09:41:30.044Z | auto\n\n- Removed the sample file skill-card.md.\n- No changes to functionality or documentation content.\n- Maintenance update with minor cleanup.\n\nv0.5.0 | 2026-07-21T09:42:50.754Z | auto\n\nproxy-aiops 0.5.0\n\n- Governance harness: improved risk-tier handling—high-risk writes now require dry run and double CLI confirmation.\n- Undoable writes: Undo system refined; all reversible ops now accurately capture before-state and allow parameterized reversal.\n- Documentation updates: Compatibility and governance sections clarified; policy/undo explanations improved.\n- File cleanup: Removed obsolete skill-card.md file.\n- CLI guidance: Instructions now note platform selection and secret handling improvements.\n\nv0.4.0 | 2026-07-20T11:17:13.643Z | auto\n\n- Removed the file `skill-card.md`.\n- No other user-facing changes.\n\nv0.3.1 | 2026-07-20T04:08:11.775Z | auto\n\n- Removed the file skill-card.md from the project.\n- No functional or user-facing changes.  \n- Internal documentation cleanup only.\n\nv0.3.0 | 2026-07-20T03:08:24.748Z | auto\n\n- Removed the skill documentation file (skill-card.md).\n- No changes to functionality or features; this is a documentation/packaging cleanup.\n\nv0.2.0 | 2026-07-19T03:53:11.773Z | auto\n\nproxy-aiops 0.2.0\n\n- Added agent guardrails documentation (references/agent-guardrails.md)\n- Introduced undo functionality: new undo_list and undo_apply tools (total tool count: 28)\n- Improved documentation, including updated tool matrix and governance test coverage references\n- Removed deprecated skill-card.md\n- Minor metadata and description updates for clarity and consistency\n\nv0.1.0 | 2026-07-17T05:57:23.290Z | auto\n\nInitial preview release: governed reverse-proxy operations for Traefik, Caddy, and HAProxy.\n\n- Provides a unified toolset (26 tools) for overview, route/service inspection, upstream health, middleware, TLS certificate inventory, traffic/error stats, and runtime config management.\n- Includes root cause analyses for backend health, certificate expiry, 5xx error rate, and route conflicts.\n- Write operations are governed: enforced audit log, policy/risk-tiers, undo tokens, and token budgets.\n- Credentials are stored encrypted; full local governance by default.\n- Only mock-validated for now — not run against live proxies. All three platforms supported for read/write where APIs permit.\n- Focused strictly on Traefik, Caddy, and HAProxy; excludes managed cloud balancers, firewalls, or non-proxy appliances.\n\nArchive index:\n\nArchive v0.9.4: 7 files, 19027 bytes\n\nFiles: references/agent-guardrails.md (8175b), references/capabilities.md (5569b), references/cli-reference.md (3069b), references/setup-guide.md (3153b), skill-card.md (2970b), SKILL.md (17439b), _meta.json (130b)\n\nFile v0.9.4:SKILL.md\n\n---\nname: proxy-aiops\nslug: proxy-aiops\ndisplayName: \"Proxy AIops\"\nsummary: \"Governed Traefik + Caddy + HAProxy ops: routes, upstreams, certs, 5xx RCA. 28 tools.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxy-AIops\ntags: [aiops, mcp, governance, proxy]\ndescription: >\n  Use this skill whenever the user needs to operate a Traefik, Caddy or HAProxy reverse proxy / load balancer — a one-shot overview, routes (routers / caddy routes / frontends) with host/path matching, services and server-level upstream health, middlewares, TLS certificate inventory with an expiry sweep, traffic and 5xx error counters, config snapshot/search, four flagship RCAs (backend health, cert expiry, error rate, route conflicts), and governed writes (caddy config set/delete/load with prior-config capture; haproxy server drain/maint/ready and weight).\n  Always use this skill for \"Traefik\", \"Caddy\", \"HAProxy\", \"reverse proxy\", \"load balancer\", \"upstream down\", \"502/503/504 errors\", \"bad gateway\", \"cert expiring\", \"TLS certificate\", \"route not matching\", \"which route serves this host\", \"drain a server\", \"server weight\", \"redirect loop\" when the context is a Traefik/Caddy/HAProxy edge.\n  Do NOT use when the target is something other than a Traefik/Caddy/HAProxy proxy (a hypervisor, storage appliance, backup product, container-orchestration cluster, multi-vendor router/switch config, or OT/industrial equipment) — route those to the appropriate other AIops-tools skill. Do NOT use for firewall rules — use firewall-aiops. Managed cloud load balancers are out of scope.\n  Governed proxy operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers). Behaviour is validated by a mock-based test suite; see docs/VERIFICATION.md for the live-verification checklist.\ninstaller:\n  kind: uv\n  package: proxy-aiops\nargument-hint: \"[a route/service/backend name, a hostname, or describe your proxy task]\"\nallowed-tools:\n  - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"proxy-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"PROXY_AIOPS_CONFIG\",\"PROXY_AIOPS_MASTER_PASSWORD\"]},\"homepage\":\"https://github.com/AIops-tools/Proxy-AIops\",\"emoji\":\"🔀\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n  Standalone, self-governed reverse-proxy operations across Traefik (API /api/..., metrics-text counters via /metrics), Caddy (admin API, default localhost:2019 — carries the write surface) and HAProxy (Data Plane API v2 /v2/..., HTTP Basic auth). Each target in the config names its own platform, and a name-keyed platform registry selects the API shape; an explicit support matrix raises teaching errors for ops a platform cannot do (traefik writes → its providers; caddy error counters → access logs; haproxy certs → the .pem pipeline), never a silent no-op. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency.\n  All write operations are audited to a local SQLite DB under ~/.proxy-aiops/ (relocatable via PROXY_AIOPS_HOME).\n  Credentials: the HAProxy Data Plane API password (required) or an optional Basic-auth credential for Traefik/Caddy is stored ENCRYPTED in ~/.proxy-aiops/secrets.enc (Fernet/AES-128 + scrypt-derived key) — never plaintext on disk. Traefik and Caddy usually run unauthenticated on localhost, so their secret is optional (no store entry = no auth header). Run 'proxy-aiops init' to onboard (it asks for the platform), or 'proxy-aiops secret set <target>'. The store is unlocked by a master password from PROXY_AIOPS_MASTER_PASSWORD (non-interactive/MCP/CI) or an interactive prompt (CLI on a TTY). A legacy plaintext env var PROXY_<TARGET_NAME_UPPER>_SECRET is still honoured as a fallback with a deprecation warning (migrate with 'proxy-aiops secret migrate'). Secrets are never logged or echoed.\n  State-changing operations pass through the @governed_tool decorator (budget guard + audit + risk-tier labelling). delete_config_path and load_config (full config replace) are risk=high with dry_run + double confirmation at the CLI. Reversible writes (set_config_value, delete_config_path, load_config, set_server_state, set_server_weight) capture the real fetched before-state and record an inverse undo descriptor whose params replay against the tool's own signature.\n  Webhooks: none — no outbound network calls beyond the configured proxy APIs, plus (only when the operator runs the cert sweep with probing) a bounded TLS handshake per inventoried domain.\n  SSL: verify_ssl defaults to true; disable only for self-signed lab certs.\n  Transitive dependencies: httpx (HTTP client), cryptography (secret store + cert parsing), and the MCP SDK. No post-install scripts or background services.\n---\n\n# Proxy AIops\n\n> **Disclaimer**: Community-maintained open-source project, **not affiliated with, endorsed by, or sponsored by Traefik Labs, the Caddy project, HAProxy Technologies, or the HAProxy project.** Traefik, Caddy and HAProxy are trademarks of their respective owners. Source at [github.com/AIops-tools/Proxy-AIops](https://github.com/AIops-tools/Proxy-AIops) under the MIT license.\n\nGoverned reverse-proxy operations — **28 MCP tools** across **Traefik** (API +\n`/metrics`), **Caddy** (admin API) and **HAProxy** (Data Plane API v2), every\none wrapped with the bundled `@governed_tool` harness: a local unified audit\nlog under `~/.proxy-aiops/`, policy engine, token/runaway budget guard,\nundo-token recording, and descriptive risk tiers. A per-target\n`platform` field selects the API shape, so the same tools work on all three\nproxies and one config can span a mixed edge. An explicit **support matrix**\nraises teaching errors for ops a platform cannot do — never a silent no-op.\nCredentials are stored **encrypted** (`~/.proxy-aiops/secrets.enc`, Fernet +\nscrypt) — never plaintext on disk; Traefik/Caddy secrets are optional\n(unauthenticated localhost is the common case).\n\n> **Standalone**: the governance harness is bundled in the package\n> (`proxy_aiops.governance`) — no external skill-family dependency. Behaviour is\n> covered by a mock-based test suite; `docs/VERIFICATION.md` is the checklist for a\n> live run (all three platforms are free/self-hostable, so a small lab is enough).\n\n## What This Skill Does\n\n| Group | Tools | Count | R/W |\n|-------|-------|:-----:|:---:|\n| **Status** | proxy_overview, version_info, list_entrypoints | 3 | read |\n| **Routes** | list_routes, route_detail, find_route | 3 | read |\n| **Services** | list_services, service_detail, list_upstreams, upstream_detail, list_middlewares | 5 | read |\n| **Certificates** | list_certificates | 1 | read |\n| **Traffic** | traffic_stats, error_counters | 2 | read |\n| **Config** | config_snapshot, search_config, get_config_value | 3 | read |\n| **Flagship analyses** | backend_health_rca, cert_expiry_sweep, error_rate_rca, route_conflict_analysis | 4 | read |\n| **Writes (caddy)** | set_config_value (med), delete_config_path (**high**), load_config (**high**) | 3 | write |\n| **Writes (haproxy)** | set_server_state, set_server_weight | 2 | write (med) |\n| **Undo** | undo_list, undo_apply | 2 | read / write |\n\nThe four flagship analyses are transparent heuristics that report their\nnumbers, never a black-box verdict: `backend_health_rca` groups down upstreams\nper service and maps the health-check failure class (connection refused / L4\ntimeout / TLS / L7 / DNS / maint) to a cause + action; `cert_expiry_sweep`\nbuckets certs by days-to-expiry with per-platform renewal hints;\n`error_rate_rca` ranks services by 5xx share vs the fleet baseline and maps\nthe dominant code (502/503/504/500) to a cause; `route_conflict_analysis`\nfinds shadowed routes, dead routes, and redirect loops.\n\n## Quick Install\n\n```bash\nuv tool install proxy-aiops\nproxy-aiops init       # wizard: pick platform (traefik/caddy/haproxy) + optional encrypted secret\nproxy-aiops doctor\n```\n\nOr as an OpenClaw plugin, which installs this skill and its MCP server together:\n\n```bash\nopenclaw plugins install clawhub:@zw008/proxy-aiops\nopenclaw skills info proxy-aiops          # expect: Visible to model: yes\n```\n\nNeeds `uvx` on `PATH`: the MCP server is fetched with uv, pinned to this release.\n\n## When to Use This Skill\n\n- Get a one-shot snapshot (`overview` / `version_info` / `list_entrypoints`)\n- Investigate 502/503/504 spikes (`error_rate_rca`) → dominant code → cause\n- Find why an upstream/backend is down (`list_upstreams`, `backend_health_rca`)\n- Sweep TLS cert expiry across the edge (`certs --sweep` / `cert_expiry_sweep`)\n- Audit routing hygiene (`route_conflict_analysis` — shadowed/dead routes,\n  redirect loops) and answer \"which route serves this host?\" (`find_route`)\n- Safely drain/return an haproxy server (`set_server_state`, reversible +\n  undo-recorded) or adjust its weight (`set_server_weight`)\n- Safely edit caddy config (`set_config_value` / `delete_config_path` /\n  `load_config` — prior config captured, undo replays the restore)\n\n**Do NOT use when** the target is not a Traefik/Caddy/HAProxy proxy — route\nhypervisor, storage, backup, cluster, network-device, or OT/industrial work to\nthe appropriate other AIops-tools skill. Do NOT use for firewall rules — use\nfirewall-aiops.\n\n## Related Skills — Skill Routing\n\n| If the user wants… | Use |\n|--------------------|-----|\n| Traefik / Caddy / HAProxy proxy ops | **proxy-aiops** (this skill) |\n| Firewall rules / NAT / gateway health | **firewall-aiops** |\n| A non-proxy platform (hypervisor, storage, backup, cluster, network devices, OT edge) | the appropriate **other AIops-tools** skill |\n| Managed cloud load balancers | out of scope for this tool |\n\n## Common Workflows\n\n### 1. A 5xx spike — is it the app or the backend?\n\n1. `proxy-aiops doctor` → confirm the proxy's API is reachable before you trust any\n   number that follows.\n2. `proxy-aiops overview` → the one-shot picture: platform/version, entrypoints, and\n   route/service counts, so you know the blast radius.\n3. `proxy-aiops analyze errors --rate 5 --min-requests 100` → services ranked by 5xx\n   share against the fleet baseline, with the **dominant status code mapped to a cause**\n   (503 no upstream available / 502 connection failed / 504 timeout / 500 app error).\n   The `--min-requests` floor keeps a single failed request on a quiet service from\n   outranking a real incident.\n4. `proxy-aiops analyze health --service <name>` → the same service from the backend\n   side: which servers are failing their health check and what class of failure it is.\n   If the servers are healthy, the 5xx is coming from **the application**, and no amount\n   of proxy work will fix it — hand it off.\n5. If one server is the problem, take it out of rotation gracefully:\n   `proxy-aiops services upstreams <backend>` to get the exact server name, then\n   `proxy-aiops server state <backend> <server> drain --dry-run` and re-run for real\n   (double-confirm; the prior state is captured as the undo descriptor). `drain` lets\n   in-flight connections finish — reach for `maint` only when you need it out *now*.\n6. Re-run `proxy-aiops analyze errors` to confirm the rate dropped.\n7. **Failure branch**: if draining one server just moves the load onto the next one to\n   fall over, you are shedding capacity you do not have — put it straight back with\n   `proxy-aiops undo list` → `undo apply <id>` (restores the **prior** state, not a\n   hardcoded `ready`) before you drain a second. Note `server state` / `server weight`\n   are **haproxy runtime** operations; on a traefik or caddy target the tool raises a\n   teaching error naming the right mechanism rather than silently doing nothing.\n\n### 2. Certificates about to expire\n\n1. `proxy-aiops certs --sweep --warn-days 30 --critical-days 7` → the TLS domain\n   inventory with each cert **live-probed** on port 443 and bucketed\n   expired / critical / warning, plus a renewal hint.\n2. `proxy-aiops certs --sweep --port 8443` for any entrypoint not on 443 —\n   the sweep probes one port at a time, so a non-standard listener needs its own pass.\n3. `proxy-aiops overview` and `proxy-aiops routes list` → map each expiring domain back\n   to the routes that actually serve it, so you renew what is in use and ignore what is\n   not.\n4. Renew through the platform's own mechanism (ACME for traefik/caddy), then re-run the\n   sweep to confirm the new expiry date.\n5. **Failure branch**: on a **haproxy** target the sweep returns a teaching note rather\n   than results — haproxy serves certs from `.pem` files on disk, outside this tool's\n   API surface, so check those with your file-level tooling. If a probe fails to connect,\n   distinguish \"cert is bad\" from \"port is closed\" with\n   `proxy-aiops routes find <host>` before assuming a certificate problem.\n\n### 3. \"Why is this hostname hitting the wrong backend?\"\n\n1. `proxy-aiops routes find <host> --path /api` → best-matching routes, most specific\n   first. This is the direct answer to \"who serves this request\".\n2. `proxy-aiops routes show <route-id>` → the full rule, priority, middlewares, and the\n   service it points at.\n3. `proxy-aiops analyze conflicts` → **shadowed** routes (fully covered by an earlier or\n   higher-priority route), **dead** routes (the service is missing, or has zero servers\n   up), and redirect loops — each finding names the covering route or the missing\n   service rather than just flagging a number.\n4. `proxy-aiops services show <service>` and `proxy-aiops services upstreams <service>`\n   → confirm the service the route resolves to actually has healthy servers behind it.\n5. Fix the ordering/priority at its source: on **caddy** via `proxy-aiops config set`\n   (recipe 4); on **traefik**, in the provider that generated the route (labels, file\n   provider, CRD) — traefik's API is read-only, and the tool says so explicitly instead\n   of pretending to write.\n6. **Failure branch**: if `routes find` returns nothing, the request is not matching any\n   route at all — check `proxy-aiops overview` for the entrypoints and confirm the\n   listener you think you are hitting exists. A \"dead route\" finding whose service is\n   missing usually means a config was applied referencing a service that was never\n   created; fixing the route without creating the service just moves the 404.\n\n### 4. Edit a caddy config subtree, reversibly\n\n1. `proxy-aiops config snapshot` → the whole current config; take this **before** you\n   change anything, so you have an out-of-band copy independent of the undo store.\n2. `proxy-aiops config search <needle>` → locate the config path holding the value you\n   want (searching beats guessing at caddy's nested JSON paths).\n3. `proxy-aiops config get <path>` → read the exact current subtree you are about to\n   replace.\n4. `proxy-aiops config set <path> '<json>' --dry-run` → preview the write.\n5. Re-run without `--dry-run` (double-confirm) — the prior subtree is fetched and\n   captured, and an inverse undo descriptor is recorded with an `_undo_id`.\n6. Validate: `proxy-aiops routes list`, `proxy-aiops analyze conflicts`, and\n   `proxy-aiops analyze errors` → confirm the edit did what you meant and did not\n   shadow an existing route.\n7. **Failure branch**: `proxy-aiops undo list` → `undo apply <id>` restores the captured\n   subtree exactly. If the config is too broken for a targeted undo, the\n   `config snapshot` from step 1 is your fallback via `load_config` — but note\n   `load_config` and `config delete` are **risk=high** with `--dry-run` + double\n   confirmation at the CLI. `load_config` replaces the *entire* config, so it is a\n   last resort, not a first instinct.\n\n## Governance & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide\nwhether a write is permitted. That is your agent's judgement, or the permission\nof the account you connect it with (a read-only HAProxy Data Plane API role, a\nscoped Traefik/Caddy admin API — writes then fail at the server). There is no\nread-only switch, policy file, or approval gate.\n\n- **Audit is the guarantee, and it is not bypassable.** Every operation — MCP and CLI alike — is logged to `~/.proxy-aiops/audit.db` (relocatable via `PROXY_AIOPS_HOME`): params (secrets redacted), result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- `PROXY_AUDIT_APPROVED_BY` / `PROXY_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Runaway guard** — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with `PROXY_RUNAWAY_MAX=0`.\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI; CLI writes execute through the same governed tools, so they are audited + undo-recorded.\n- Reversible writes capture the real fetched before-state and record an inverse descriptor that replays against the tool's own signature.\n- Traefik targets accept no writes at all — the support matrix teaches you to\n  edit the provider source instead.\n\n## References\n\n- `references/capabilities.md` — full tool + platform + API-path reference\n- `references/cli-reference.md` — CLI command reference\n- `references/setup-guide.md` — onboarding, credentials, and connectivity\n- `docs/VERIFICATION.md` — live-verification checklist (what the mock suite covers, and what a real-proxy run must prove)\n\nFile v0.9.4:_meta.json\n\n{\n  \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n  \"slug\": \"proxy-aiops\",\n  \"version\": \"0.9.4\",\n  \"publishedAt\": 1789601191173\n}\n\nFile v0.9.4:references/agent-guardrails.md\n\n# Agent guardrails — running proxy-aiops with a smaller / local model\n\nIf you drive these tools with a local model (Llama, Qwen, Mistral … via Goose,\nOllama, LM Studio, or any OpenAI-compatible runtime), you will get noticeably\nbetter results with a short system prompt. This page gives you one, and — more\nimportantly — tells you which guardrails you **no longer need to write**, because\nthe tool now enforces them itself.\n\nThe distinction matters. A guardrail in a prompt is a request. A guardrail in the\nharness is a guarantee. Anything below that we could move into the harness, we did.\n\n## Authorization is not this tool's job — decide it where it belongs\n\nWhether a write should happen is your decision, or the account's. The tool does\nnot gate it — there is no read-only switch and no approval prompt to configure.\nThe two right places to control read vs write:\n\n- **The account you connect with.** Give the HAProxy Data Plane API a read-only\n  role, or point the tool at a Traefik/Caddy admin API you have scoped down. A\n  write then fails at the server, which is the only place the permission actually\n  lives — a revoked permission cannot be argued around by a model, but a skill-side\n  flag can.\n- **Your agent's system prompt.** If you want an observe-only session, tell the\n  model not to call the write tools (they are clearly tagged `[WRITE]`).\n\nWhat the tool *does* guarantee is that you can always see what happened:\n\n## What the tool enforces — do not waste prompt budget on these\n\n| You might be tempted to prompt | Why you don't need to |\n|---|---|\n| \"Don't invent a value when a field is missing\" | Traefik, Caddy and HAProxy express the same concepts differently, so a field one platform has and another does not comes back as `null`, never as `\"\"`. A Caddy route's `raw` rule string is `null` — Caddy matches on a match list and has no such string — rather than a misleading empty rule. |\n| \"Tell me if the output was cut off\" | `search_config`, `traffic_stats` and `error_counters` return `{\"matches\"/\"services\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}` — one convention across the repo. Truncation is measured (the config walk deliberately overshoots by one) and not guessed from the count reaching the cap. |\n| \"Make it show the number it judged on\" | `error_rate_rca` returns `errorRatePct`, `vsBaselineX` against the fleet baseline and a `severity` of `critical`/`warning` on every flagged service; `cert_expiry_sweep` returns `daysToExpiry` and a `bucket` per certificate, and orders by `daysToExpiry`. Both orderings are therefore checkable from the payload itself. |\n| \"Confirm before anything destructive\" | `delete_config_path` and `load_config` require a `--dry-run`-able preview plus double confirmation at the CLI. Config writes capture the prior value so the undo token can restore it. |\n| \"Log what you did\" | Every governed call is audited to `~/.proxy-aiops/audit.db` regardless of what the model says it did — and the CLI writes the same row the MCP path does, so there is no unaudited entry point. |\n| \"Don't get stuck retrying\" | The runaway guard trips a circuit breaker if the same call is hammered in a tight loop — a stuck agent is stopped rather than left to burn calls and time. |\n\n## What still needs a prompt\n\nThese are model-behaviour problems the harness cannot fix from the outside.\n\n⚠️ **Two of the four orderings cannot be checked, for different reasons.**\n`backend_health_rca` sorts its `findings` worst-first on an internal score that is removed\nbefore the payload is returned, and its findings carry neither a `rank` nor a `severity`.\n`route_conflict_analysis` is ordered by the proxy's own **evaluation order** (route priority,\nwhich is not returned) — that is match order, not severity: a shadowed route appearing first\nsays nothing about how bad the shadowing is. `error_rate_rca` and `cert_expiry_sweep` are\ndifferent: they sort on `errorRatePct` and `daysToExpiry`, both of which are in the payload.\n\nCopy this into your agent's system prompt:\n\n```text\nYou operate a Traefik, Caddy or HAProxy reverse proxy through the proxy-aiops\nMCP tools.\n\nTOOL USE\n- Before answering any question about the current proxy, you MUST call a tool.\n  Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n  emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n  a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n  field that is true, say so and narrow the query instead of treating the\n  partial result as complete.\n- `backend_health_rca` findings and `route_conflict_analysis` results are not ordered by\n  severity — the latter is in the proxy's match order. Weigh `backend_health_rca` findings on\n  their own `serversTotal`/`up`/`down`/`maint` counts. `route_conflict_analysis` results carry\n  no number at all — read `shadowedBy`, `reason` or `chain` and say which one you acted on.\n- A null field means this platform does not express that concept, or did not\n  report it. Report it as \"not available\" — never infer it.\n- An \"unsupported\" field is a capability statement about the platform, not an\n  error and not a finding. Say the platform does not expose it; do not report\n  it as a problem with the proxy.\n- Report values exactly as returned. Traffic counters are cumulative since the\n  proxy started — compare rates, never quote a raw total as \"requests today\".\n\nSCOPE\n- Separate observation from interpretation. State what the tools returned, then\n  any interpretation, clearly marked as such.\n- Do not claim a backend is down unless a health/upstream result says so. A\n  route existing does not mean it resolves.\n- Do not confuse a route with a service, a service with an upstream server, or\n  an entrypoint with a route. One route names one service; one service has many\n  upstream servers.\n- The three platforms differ. The target's platform is in every result — do not\n  suggest a Traefik router rule on Caddy, or a Caddy config path on HAProxy.\n- On Traefik, /api/rawdata is the merged read-only view. Config changes belong\n  to the provider (the Docker labels, the file provider), not to this tool —\n  do not offer to edit what the tool cannot write.\n```\n\n## Recommended setup for a local model\n\nStart with a connection that *cannot* write, verify, and widen the account's\npermission only when you trust the setup — a proxy is the one component where a\nbad config change takes down everything behind it at once, and `load_config`\nreplaces the whole tree:\n\n```bash\n# e.g. give the HAProxy Data Plane API a read-only role, or point the tool at a\n# Traefik/Caddy admin API you have scoped down. Then:\nproxy-aiops doctor\n```\n\nOptionally annotate the audit trail with who is operating and why — recorded on\nevery row, never required:\n\n```bash\nexport PROXY_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport PROXY_AUDIT_RATIONALE=\"draining web-02 for maintenance\"\n```\n\n## If your model still struggles\n\nSome behaviours are model-capacity limits rather than prompt problems:\n\n- **Multi-tool workflows time out or drift.** Prefer the RCA tools —\n  `backend_health_rca` and `error_rate_rca` do the correlation inside one call,\n  so the model does not have to chain `list_services`, `list_upstreams` and\n  `error_counters` and keep service names straight.\n- **The model ignores later tool results in a long context.** The config\n  snapshot is the big payload here. Prefer `search_config` with a narrow query\n  over pulling the whole tree and asking the model to find things in it.\n- **The model describes calls instead of making them.** This is usually a\n  runtime/tool-calling-format mismatch, not a prompt problem — check that your\n  client advertises the tools in the format your model was trained on.\n\nFeedback on running this with a specific local model is genuinely useful —\nopen an issue at\n[github.com/AIops-tools/Proxy-AIops](https://github.com/AIops-tools/Proxy-AIops/issues)\nwith the model, runtime, and what went wrong.\n\nFile v0.9.4:references/capabilities.md\n\n# proxy-aiops — capabilities reference\n\n## Platforms\n\n| Platform | API | Auth | Default base_url |\n|----------|-----|------|------------------|\n| `traefik` | Traefik API (`/api/...`) + `/metrics` text | none, or optional HTTP Basic (username + stored secret) | `http://localhost:8080` |\n| `caddy` | Admin API (`/config/`, `/load`, `/reverse_proxy/upstreams`) | none, or optional HTTP Basic | `http://localhost:2019` |\n| `haproxy` | Data Plane API v2 (`/v2/...`) | HTTP Basic (username + stored secret, **required**) | `http://localhost:5555` |\n\nA per-target `platform` field selects the shape; the ops/CLI/MCP layers are\nplatform-neutral. Unsupported ops raise **teaching errors** (what to use\ninstead), never silent empties.\n\n## Support matrix\n\n| Capability | traefik | caddy | haproxy |\n|------------|:-------:|:-----:|:-------:|\n| version_info | ✅ `/api/version` | teaching note (no version endpoint) | ✅ `/v2/info` |\n| list_entrypoints | ✅ `/api/entrypoints` | ✅ server listen addresses | ✅ frontends |\n| list_routes / route_detail / find_route | ✅ routers (rule parsed) | ✅ routes (name = config path) | ✅ frontends (ACLs not parsed) |\n| list_services / service_detail | ✅ services + serverStatus | ✅ reverse_proxy routes + upstreams | ✅ backends + stats |\n| list_upstreams / upstream_detail | ✅ serverStatus map | ✅ `/reverse_proxy/upstreams` (fails→down) | ✅ stats server rows (status + check_status) |\n| list_middlewares | ✅ | teaching (inline handlers) | teaching (haproxy.cfg) |\n| list_certificates / cert_expiry_sweep | ✅ TLS routers + tls.domains | ✅ TLS listeners + automation subjects | teaching (.pem files) |\n| traffic_stats / error_counters | ✅ `/metrics` per-code | teaching (no per-route counters) | ✅ stats (`req_tot`, `hrsp_*`) |\n| config_snapshot / search_config | ✅ `/api/rawdata` (read-only) | ✅ `/config/` | teaching |\n| get/set_config_value, delete_config_path, load_config | teaching (edit the provider) | ✅ (the write surface) | teaching (use runtime writes) |\n| set_server_state / set_server_weight | teaching (provider) | teaching (config tree) | ✅ runtime servers |\n\n## MCP tools (28)\n\n### Reads (21)\n\n| Tool | Returns |\n|------|---------|\n| `proxy_overview` | platform/version + route/service counts + upstream up/down |\n| `version_info` | version/build info |\n| `list_entrypoints` | listeners: {name, address} |\n| `list_routes(host?)` | normalised routes: {name, hosts, paths, priority, service, tls, enabled, redirectTo} |\n| `route_detail(name)` | one route's full detail |\n| `find_route(host, path)` | routes that would serve a host/path, best first |\n| `list_services` | services/backends: {name, serversTotal, serversUp} |\n| `service_detail(name)` | one service's detail (+ haproxy servers) |\n| `list_upstreams(service?)` | server rows: {service, server, address, status up/down/maint/drain, checkInfo, weight} |\n| `upstream_detail(service, server)` | one server row |\n| `list_middlewares` | traefik middlewares (teaching elsewhere) |\n| `list_certificates(probe?, port?)` | TLS domain inventory (+ live expiry when probed) |\n| `traffic_stats` | per-service requests/latency/rate/sessions |\n| `error_counters` | per-service status-code counters |\n| `config_snapshot` | live config tree / merged dynamic state (sanitised) |\n| `search_config(query)` | matching config paths |\n| `get_config_value(path)` | one caddy config subtree |\n| `backend_health_rca(upstreams?)` | per-service outage/degraded findings + cause + action |\n| `cert_expiry_sweep(warn_days?, critical_days?, certs?)` | expiry buckets + renewal hints |\n| `error_rate_rca(error_rate_pct?, min_requests?, counters?)` | flagged services, dominant-code cause, vs-fleet baseline |\n| `route_conflict_analysis(routes?, services?)` | shadowed/dead routes, redirect loops |\n\nAll four analyses accept injected rows for pure offline analysis.\n\n### Writes (5) — all take `dry_run`, all capture prior state\n\n| Tool | Platform | Risk | Undo |\n|------|----------|:----:|------|\n| `set_config_value(path, value)` | caddy | medium | restore prior subtree (or delete a created path) |\n| `delete_config_path(path)` | caddy | **high** | re-create the captured subtree |\n| `load_config(config)` | caddy | **high** | re-load the snapshotted full config |\n| `set_server_state(backend, server, state)` | haproxy | medium | restore prior admin state (ready/drain/maint) |\n| `set_server_weight(backend, server, weight)` | haproxy | medium | restore prior weight (0-256) |\n\n### Undo (2)\n\n| Tool | Returns |\n|------|---------|\n| `undo_list(limit?)` | recorded undo descriptors, newest first, with their `_undo_id` |\n| `undo_apply(undo_id, dry_run?)` | replays the recorded inverse (governed like any other write) |\n\n`undo_apply` is governed like any other write (audited, capturing a before-state\nwhere the inverse is itself reversible). Undo descriptors are recorded to\n`~/.proxy-aiops/undo.db`; their params match each tool's own signature\n(replayable as-is).\n\n## Modelled API paths (mock-validated)\n\n- traefik: `/api/version`, `/api/overview`, `/api/entrypoints`,\n  `/api/http/routers[/{name}]`, `/api/http/services[/{name}]`,\n  `/api/http/middlewares`, `/api/rawdata`, `/metrics`\n- caddy: `/config/[{path}]`, `/load`, `/reverse_proxy/upstreams`\n- haproxy: `/v2/info`, `/v2/services/haproxy/configuration/{frontends|backends|servers|binds}`,\n  `/v2/services/haproxy/runtime/servers[/{name}]?backend=...`,\n  `/v2/services/haproxy/stats/native`\n\nEvery substituted path value is percent-encoded centrally; caddy config paths\nreject dot-segments.\n\nFile v0.9.4:references/cli-reference.md\n\n# proxy-aiops — CLI reference\n\nGlobal option on most commands: `--target/-t <name>` (default: first target in\nconfig).\n\n## Setup & health\n\n```bash\nproxy-aiops init                 # interactive wizard: platform, base_url, TLS verify, encrypted secret\nproxy-aiops doctor               # config + secrets + connectivity (probe per platform)\nproxy-aiops doctor --skip-auth   # skip the connectivity probe\nproxy-aiops overview             # one-shot: version + routes/services + upstream health\n```\n\n## Reads\n\n```bash\nproxy-aiops routes list [--host app.example.com]\nproxy-aiops routes show <name>              # traefik router name / caddy config path / haproxy frontend\nproxy-aiops routes find <host> [--path /]   # which routes would serve host/path\nproxy-aiops services list\nproxy-aiops services show <name>\nproxy-aiops services upstreams [--service <name>]\nproxy-aiops certs [--sweep] [--warn-days 30] [--critical-days 7] [--port 443]\nproxy-aiops config snapshot\nproxy-aiops config search <query>\nproxy-aiops config get <path>\n```\n\n## Flagship analyses\n\n```bash\nproxy-aiops analyze health [--service <name>]   # backend/upstream health RCA\nproxy-aiops analyze errors [--rate 5.0] [--min-requests 30]   # 5xx error-rate RCA\nproxy-aiops analyze conflicts                   # shadowed/dead routes, redirect loops\n```\n\n## Governed writes (dry-run + double-confirm; audited + undo-recorded)\n\n```bash\n# caddy config (teaching error on traefik/haproxy targets)\nproxy-aiops config set <path> '<json>' [--dry-run]\nproxy-aiops config delete <path> [--dry-run]        # risk=high, double-confirm\n\n# haproxy runtime servers (teaching error on traefik/caddy targets)\nproxy-aiops server state <backend> <server> ready|drain|maint [--dry-run]\nproxy-aiops server weight <backend> <server> <0-256> [--dry-run]\n```\n\nHigh-risk writes prompt for double confirmation at the CLI. Optionally export\n`PROXY_AUDIT_APPROVED_BY` (and `PROXY_AUDIT_RATIONALE`) to annotate the audit\nrow with who/why — never required.\n\n## Secrets\n\n```bash\nproxy-aiops secret set <target>      # store encrypted (hidden prompt)\nproxy-aiops secret list              # names only, never values\nproxy-aiops secret rm <target>\nproxy-aiops secret migrate           # import legacy plaintext .env\nproxy-aiops secret rotate-password   # re-encrypt under a new master password\n```\n\n## MCP server\n\n```bash\nproxy-aiops mcp        # stdio transport (or: proxy-aiops-mcp)\n```\n\n## Environment variables\n\n| Variable | Purpose |\n|----------|---------|\n| `PROXY_AIOPS_MASTER_PASSWORD` | unlock secrets.enc non-interactively (MCP/CI) |\n| `PROXY_AIOPS_CONFIG` | alternate config.yaml path (MCP server) |\n| `PROXY_AIOPS_HOME` | relocate config/audit/undo state dir |\n| `PROXY_AUDIT_APPROVED_BY` / `PROXY_AUDIT_RATIONALE` | optional approver/rationale annotations recorded on the audit row |\n| `PROXY_MAX_TOOL_CALLS` / `PROXY_MAX_TOOL_SECONDS` | per-process budget ceilings |\n| `PROXY_RUNAWAY_MAX` / `PROXY_RUNAWAY_WINDOW_SEC` | runaway circuit-breaker tuning |\n| `PROXY_<TARGET>_SECRET` | legacy plaintext fallback (deprecated) |\n\nFile v0.9.4:references/setup-guide.md\n\n# proxy-aiops — setup guide\n\n## 1. Enable each platform's API\n\n- **traefik** — expose the API: `--api=true` with a router on `api@internal`\n  (or `--api.insecure=true` in a lab, which serves it on `:8080`). For\n  error-rate analysis also enable the metrics endpoint\n  (Traefik's metrics provider serves `/metrics`).\n- **caddy** — the admin API is on `localhost:2019` by default (the `admin`\n  key in the config controls the listener). proxy-aiops needs plain HTTP\n  reachability to it; keep it bound to localhost or an internal network.\n- **haproxy** — run the **Data Plane API** sidecar (`dataplaneapi`) pointing at\n  haproxy.cfg, with a userlist user. Note the listen address (default `:5555`)\n  and the user/password.\n\n## 2. Onboard\n\n```bash\nuv tool install proxy-aiops\nproxy-aiops init\n```\n\nThe wizard asks for: target name → platform (`traefik` / `caddy` / `haproxy`)\n→ API base URL (per-platform default offered) → TLS verification (default ON;\nanswer No only for self-signed lab certs) → credentials:\n\n- **haproxy**: Data Plane API username + password (password stored encrypted —\n  required).\n- **traefik / caddy**: optional Basic-auth username/password — leave both\n  empty for the common unauthenticated-localhost case (no store entry means no\n  auth header is sent).\n\n## 3. Verify\n\n```bash\nproxy-aiops doctor\n```\n\nDoctor checks config, the encrypted store (and its permissions), per-target\nsecrets (respecting which platforms need one), then probes each target's cheap\nhealth/info endpoint: traefik `/api/version`, caddy `/config/`, haproxy\n`/v2/info`.\n\n## 4. Wire up an MCP client\n\n```json\n{\n  \"mcpServers\": {\n    \"proxy-aiops\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"proxy-aiops\", \"proxy-aiops-mcp\"],\n      \"env\": { \"PROXY_AIOPS_MASTER_PASSWORD\": \"your-master-password\" }\n    }\n  }\n}\n```\n\nMCP clients do not inherit your shell profile: set\n`PROXY_AIOPS_MASTER_PASSWORD` in the `env` block whenever any target has a\nstored secret, and `PROXY_AIOPS_CONFIG` / `PROXY_AIOPS_HOME` if you relocated\nstate.\n\n## Config file\n\n`~/.proxy-aiops/config.yaml`:\n\n```yaml\ntargets:\n  - name: edge1\n    platform: traefik\n    base_url: http://192.0.2.10:8080\n    verify_ssl: true\n  - name: caddy1\n    platform: caddy\n    base_url: http://127.0.0.1:2019\n  - name: lb1\n    platform: haproxy\n    base_url: http://192.0.2.20:5555\n    username: dpapi\n```\n\nSecrets never live here — only in `secrets.enc` (or the deprecated\n`PROXY_<TARGET>_SECRET` env fallback).\n\n## Troubleshooting\n\n- **401/403** — haproxy: wrong Data Plane API user/password; traefik/caddy: a\n  Basic-auth layer is in front (store a secret) or a stale secret is stored\n  (remove it with `proxy-aiops secret rm <target>`).\n- **404 on every call** — the API is not enabled (traefik `api@internal`\n  router missing; caddy admin listener disabled; dataplaneapi not running).\n- **Connection refused** — check `base_url` (scheme + port) and that the\n  endpoint is bound beyond localhost if proxy-aiops runs on another host.\n- **cert sweep returns unknowns** — the probe needs TCP reach to each domain\n  on the TLS port (default 443, max 25 domains, 5s each).\n\nFile v0.9.4:skill-card.md\n\n## Description:\n\nproxy-aiops helps agents inspect and operate Traefik, Caddy, and HAProxy reverse proxies, including routes, upstream health, certificates, traffic errors, RCA workflows, and governed configuration or server-state writes.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[zw008](https://clawhub.ai/user/zw008)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers and operations engineers use this skill to observe, troubleshoot, and change self-hosted Traefik, Caddy, or HAProxy reverse-proxy environments. It supports route and service inspection, TLS expiry sweeps, 5xx and backend-health RCA, configuration lookup, audited Caddy config changes, and audited HAProxy server state or weight changes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Write-capable tools can change live proxy routing, configuration, or backend server state without an enforced skill-side approval gate.\n\nMitigation: Start with read-only or tightly scoped proxy API accounts, enable write-capable credentials only when live changes are intended, and require the agent operator to review proposed writes before execution.\n\nRisk: Exposed Traefik, Caddy, or HAProxy admin APIs can broaden the blast radius of agent or credential misuse.\n\nMitigation: Keep proxy admin APIs on localhost or trusted networks, verify TLS by default, and avoid disabling certificate checks except in controlled labs.\n\nRisk: Shared or broadly readable MCP configuration can expose the master password used to unlock encrypted proxy credentials.\n\nMitigation: Store MCP environment configuration with restrictive permissions and avoid putting the master password in shared config files.\n\nRisk: Audit and undo records help recovery but do not prevent an unsafe change from being attempted.\n\nMitigation: Treat audit and undo as recovery mechanisms, use dry-run previews for writes, and keep independent configuration snapshots for high-risk Caddy changes.\n\n## Reference(s):\n\n- [proxy-aiops homepage](https://github.com/AIops-tools/Proxy-AIops)\n- [Capabilities reference](references/capabilities.md)\n- [CLI reference](references/cli-reference.md)\n- [Setup guide](references/setup-guide.md)\n- [Agent guardrails](references/agent-guardrails.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and operational findings]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May return proxy observations, RCA summaries, dry-run previews, and configuration or state-change guidance.]\n\n## Skill Version(s):\n\n0.9.4 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.9.3: 7 files, 18599 bytes\n\nFiles: references/agent-guardrails.md (7072b), references/capabilities.md (5569b), references/cli-reference.md (3069b), references/setup-guide.md (3153b), skill-card.md (2987b), SKILL.md (17439b), _meta.json (130b)\n\nFile v0.9.3:SKILL.md\n\n---\nname: proxy-aiops\nslug: proxy-aiops\ndisplayName: \"Proxy AIops\"\nsummary: \"Governed Traefik + Caddy + HAProxy ops: routes, upstreams, certs, 5xx RCA. 28 tools.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxy-AIops\ntags: [aiops, mcp, governance, proxy]\ndescription: >\n  Use this skill whenever the user needs to operate a Traefik, Caddy or HAProxy reverse proxy / load balancer — a one-shot overview, routes (routers / caddy routes / frontends) with host/path matching, services and server-level upstream health, middlewares, TLS certificate inventory with an expiry sweep, traffic and 5xx error counters, config snapshot/search, four flagship RCAs (backend health, cert expiry, error rate, route conflicts), and governed writes (caddy config set/delete/load with prior-config capture; haproxy server drain/maint/ready and weight).\n  Always use this skill for \"Traefik\", \"Caddy\", \"HAProxy\", \"reverse proxy\", \"load balancer\", \"upstream down\", \"502/503/504 errors\", \"bad gateway\", \"cert expiring\", \"TLS certificate\", \"route not matching\", \"which route serves this host\", \"drain a server\", \"server weight\", \"redirect loop\" when the context is a Traefik/Caddy/HAProxy edge.\n  Do NOT use when the target is something other than a Traefik/Caddy/HAProxy proxy (a hypervisor, storage appliance, backup product, container-orchestration cluster, multi-vendor router/switch config, or OT/industrial equipment) — route those to the appropriate other AIops-tools skill. Do NOT use for firewall rules — use firewall-aiops. Managed cloud load balancers are out of scope.\n  Governed proxy operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers). Behaviour is validated by a mock-based test suite; see docs/VERIFICATION.md for the live-verification checklist.\ninstaller:\n  kind: uv\n  package: proxy-aiops\nargument-hint: \"[a route/service/backend name, a hostname, or describe your proxy task]\"\nallowed-tools:\n  - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"proxy-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"PROXY_AIOPS_CONFIG\",\"PROXY_AIOPS_MASTER_PASSWORD\"]},\"homepage\":\"https://github.com/AIops-tools/Proxy-AIops\",\"emoji\":\"🔀\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n  Standalone, self-governed reverse-proxy operations across Traefik (API /api/..., metrics-text counters via /metrics), Caddy (admin API, default localhost:2019 — carries the write surface) and HAProxy (Data Plane API v2 /v2/..., HTTP Basic auth). Each target in the config names its own platform, and a name-keyed platform registry selects the API shape; an explicit support matrix raises teaching errors for ops a platform cannot do (traefik writes → its providers; caddy error counters → access logs; haproxy certs → the .pem pipeline), never a silent no-op. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency.\n  All write operations are audited to a local SQLite DB under ~/.proxy-aiops/ (relocatable via PROXY_AIOPS_HOME).\n  Credentials: the HAProxy Data Plane API password (required) or an optional Basic-auth credential for Traefik/Caddy is stored ENCRYPTED in ~/.proxy-aiops/secrets.enc (Fernet/AES-128 + scrypt-derived key) — never plaintext on disk. Traefik and Caddy usually run unauthenticated on localhost, so their secret is optional (no store entry = no auth header). Run 'proxy-aiops init' to onboard (it asks for the platform), or 'proxy-aiops secret set <target>'. The store is unlocked by a master password from PROXY_AIOPS_MASTER_PASSWORD (non-interactive/MCP/CI) or an interactive prompt (CLI on a TTY). A legacy plaintext env var PROXY_<TARGET_NAME_UPPER>_SECRET is still honoured as a fallback with a deprecation warning (migrate with 'proxy-aiops secret migrate'). Secrets are never logged or echoed.\n  State-changing operations pass through the @governed_tool decorator (budget guard + audit + risk-tier labelling). delete_config_path and load_config (full config replace) are risk=high with dry_run + double confirmation at the CLI. Reversible writes (set_config_value, delete_config_path, load_config, set_server_state, set_server_weight) capture the real fetched before-state and record an inverse undo descriptor whose params replay against the tool's own signature.\n  Webhooks: none — no outbound network calls beyond the configured proxy APIs, plus (only when the operator runs the cert sweep with probing) a bounded TLS handshake per inventoried domain.\n  SSL: verify_ssl defaults to true; disable only for self-signed lab certs.\n  Transitive dependencies: httpx (HTTP client), cryptography (secret store + cert parsing), and the MCP SDK. No post-install scripts or background services.\n---\n\n# Proxy AIops\n\n> **Disclaimer**: Community-maintained open-source project, **not affiliated with, endorsed by, or sponsored by Traefik Labs, the Caddy project, HAProxy Technologies, or the HAProxy project.** Traefik, Caddy and HAProxy are trademarks of their respective owners. Source at [github.com/AIops-tools/Proxy-AIops](https://github.com/AIops-tools/Proxy-AIops) under the MIT license.\n\nGoverned reverse-proxy operations — **28 MCP tools** across **Traefik** (API +\n`/metrics`), **Caddy** (admin API) and **HAProxy** (Data Plane API v2), every\none wrapped with the bundled `@governed_tool` harness: a local unified audit\nlog under `~/.proxy-aiops/`, policy engine, token/runaway budget guard,\nundo-token recording, and descriptive risk tiers. A per-target\n`platform` field selects the API shape, so the same tools work on all three\nproxies and one config can span a mixed edge. An explicit **support matrix**\nraises teaching errors for ops a platform cannot do — never a silent no-op.\nCredentials are stored **encrypted** (`~/.proxy-aiops/secrets.enc`, Fernet +\nscrypt) — never plaintext on disk; Traefik/Caddy secrets are optional\n(unauthenticated localhost is the common case).\n\n> **Standalone**: the governance harness is bundled in the package\n> (`proxy_aiops.governance`) — no external skill-family dependency. Behaviour is\n> covered by a mock-based test suite; `docs/VERIFICATION.md` is the checklist for a\n> live run (all three platforms are free/self-hostable, so a small lab is enough).\n\n## What This Skill Does\n\n| Group | Tools | Count | R/W |\n|-------|-------|:-----:|:---:|\n| **Status** | proxy_overview, version_info, list_entrypoints | 3 | read |\n| **Routes** | list_routes, route_detail, find_route | 3 | read |\n| **Services** | list_services, service_detail, list_upstreams, upstream_detail, list_middlewares | 5 | read |\n| **Certificates** | list_certificates | 1 | read |\n| **Traffic** | traffic_stats, error_counters | 2 | read |\n| **Config** | config_snapshot, search_config, get_config_value | 3 | read |\n| **Flagship analyses** | backend_health_rca, cert_expiry_sweep, error_rate_rca, route_conflict_analysis | 4 | read |\n| **Writes (caddy)** | set_config_value (med), delete_config_path (**high**), load_config (**high**) | 3 | write |\n| **Writes (haproxy)** | set_server_state, set_server_weight | 2 | write (med) |\n| **Undo** | undo_list, undo_apply | 2 | read / write |\n\nThe four flagship analyses are transparent heuristics that report their\nnumbers, never a black-box verdict: `backend_health_rca` groups down upstreams\nper service and maps the health-check failure class (connection refused / L4\ntimeout / TLS / L7 / DNS / maint) to a cause + action; `cert_expiry_sweep`\nbuckets certs by days-to-expiry with per-platform renewal hints;\n`error_rate_rca` ranks services by 5xx share vs the fleet baseline and maps\nthe dominant code (502/503/504/500) to a cause; `route_conflict_analysis`\nfinds shadowed routes, dead routes, and redirect loops.\n\n## Quick Install\n\n```bash\nuv tool install proxy-aiops\nproxy-aiops init       # wizard: pick platform (traefik/caddy/haproxy) + optional encrypted secret\nproxy-aiops doctor\n```\n\nOr as an OpenClaw plugin, which installs this skill and its MCP server together:\n\n```bash\nopenclaw plugins install clawhub:@zw008/proxy-aiops\nopenclaw skills info proxy-aiops          # expect: Visible to model: yes\n```\n\nNeeds `uvx` on `PATH`: the MCP server is fetched with uv, pinned to this release.\n\n## When to Use This Skill\n\n- Get a one-shot snapshot (`overview` / `version_info` / `list_entrypoints`)\n- Investigate 502/503/504 spikes (`error_rate_rca`) → dominant code → cause\n- Find why an upstream/backend is down (`list_upstreams`, `backend_health_rca`)\n- Sweep TLS cert expiry across the edge (`certs --sweep` / `cert_expiry_sweep`)\n- Audit routing hygiene (`route_conflict_analysis` — shadowed/dead routes,\n  redirect loops) and answer \"which route serves this host?\" (`find_route`)\n- Safely drain/return an haproxy server (`set_server_state`, reversible +\n  undo-recorded) or adjust its weight (`set_server_weight`)\n- Safely edit caddy config (`set_config_value` / `delete_config_path` /\n  `load_config` — prior config captured, undo replays the restore)\n\n**Do NOT use when** the target is not a Traefik/Caddy/HAProxy proxy — route\nhypervisor, storage, backup, cluster, network-device, or OT/industrial work to\nthe appropriate other AIops-tools skill. Do NOT use for firewall rules — use\nfirewall-aiops.\n\n## Related Skills — Skill Routing\n\n| If the user wants… | Use |\n|--------------------|-----|\n| Traefik / Caddy / HAProxy proxy ops | **proxy-aiops** (this skill) |\n| Firewall rules / NAT / gateway health | **firewall-aiops** |\n| A non-proxy platform (hypervisor, storage, backup, cluster, network devices, OT edge) | the appropriate **other AIops-tools** skill |\n| Managed cloud load balancers | out of scope for this tool |\n\n## Common Workflows\n\n### 1. A 5xx spike — is it the app or the backend?\n\n1. `proxy-aiops doctor` → confirm the proxy's API is reachable before you trust any\n   number that follows.\n2. `proxy-aiops overview` → the one-shot picture: platform/version, entrypoints, and\n   route/service counts, so you know the blast radius.\n3. `proxy-aiops analyze errors --rate 5 --min-requests 100` → services ranked by 5xx\n   share against the fleet baseline, with the **dominant status code mapped to a cause**\n   (503 no upstream available / 502 connection failed / 504 timeout / 500 app error).\n   The `--min-requests` floor keeps a single failed request on a quiet service from\n   outranking a real incident.\n4. `proxy-aiops analyze health --service <name>` → the same service from the backend\n   side: which servers are failing their health check and what class of failure it is.\n   If the servers are healthy, the 5xx is coming from **the application**, and no amount\n   of proxy work will fix it — hand it off.\n5. If one server is the problem, take it out of rotation gracefully:\n   `proxy-aiops services upstreams <backend>` to get the exact server name, then\n   `proxy-aiops server state <backend> <server> drain --dry-run` and re-run for real\n   (double-confirm; the prior state is captured as the undo descriptor). `drain` lets\n   in-flight connections finish — reach for `maint` only when you need it out *now*.\n6. Re-run `proxy-aiops analyze errors` to confirm the rate dropped.\n7. **Failure branch**: if draining one server just moves the load onto the next one to\n   fall over, you are shedding capacity you do not have — put it straight back with\n   `proxy-aiops undo list` → `undo apply <id>` (restores the **prior** state, not a\n   hardcoded `ready`) before you drain a second. Note `server state` / `server weight`\n   are **haproxy runtime** operations; on a traefik or caddy target the tool raises a\n   teaching error naming the right mechanism rather than silently doing nothing.\n\n### 2. Certificates about to expire\n\n1. `proxy-aiops certs --sweep --warn-days 30 --critical-days 7` → the TLS domain\n   inventory with each cert **live-probed** on port 443 and bucketed\n   expired / critical / warning, plus a renewal hint.\n2. `proxy-aiops certs --sweep --port 8443` for any entrypoint not on 443 —\n   the sweep probes one port at a time, so a non-standard listener needs its own pass.\n3. `proxy-aiops overview` and `proxy-aiops routes list` → map each expiring domain back\n   to the routes that actually serve it, so you renew what is in use and ignore what is\n   not.\n4. Renew through the platform's own mechanism (ACME for traefik/caddy), then re-run the\n   sweep to confirm the new expiry date.\n5. **Failure branch**: on a **haproxy** target the sweep returns a teaching note rather\n   than results — haproxy serves certs from `.pem` files on disk, outside this tool's\n   API surface, so check those with your file-level tooling. If a probe fails to connect,\n   distinguish \"cert is bad\" from \"port is closed\" with\n   `proxy-aiops routes find <host>` before assuming a certificate problem.\n\n### 3. \"Why is this hostname hitting the wrong backend?\"\n\n1. `proxy-aiops routes find <host> --path /api` → best-matching routes, most specific\n   first. This is the direct answer to \"who serves this request\".\n2. `proxy-aiops routes show <route-id>` → the full rule, priority, middlewares, and the\n   service it points at.\n3. `proxy-aiops analyze conflicts` → **shadowed** routes (fully covered by an earlier or\n   higher-priority route), **dead** routes (the service is missing, or has zero servers\n   up), and redirect loops — each finding names the covering route or the missing\n   service rather than just flagging a number.\n4. `proxy-aiops services show <service>` and `proxy-aiops services upstreams <service>`\n   → confirm the service the route resolves to actually has healthy servers behind it.\n5. Fix the ordering/priority at its source: on **caddy** via `proxy-aiops config set`\n   (recipe 4); on **traefik**, in the provider that generated the route (labels, file\n   provider, CRD) — traefik's API is read-only, and the tool says so explicitly instead\n   of pretending to write.\n6. **Failure branch**: if `routes find` returns nothing, the request is not matching any\n   route at all — check `proxy-aiops overview` for the entrypoints and confirm the\n   listener you think you are hitting exists. A \"dead route\" finding whose service is\n   missing usually means a config was applied referencing a service that was never\n   created; fixing the route without creating the service just moves the 404.\n\n### 4. Edit a caddy config subtree, reversibly\n\n1. `proxy-aiops config snapshot` → the whole current config; take this **before** you\n   change anything, so you have an out-of-band copy independent of the undo store.\n2. `proxy-aiops config search <needle>` → locate the config path holding the value you\n   want (searching beats guessing at caddy's nested JSON paths).\n3. `proxy-aiops config get <path>` → read the exact current subtree you are about to\n   replace.\n4. `proxy-aiops config set <path> '<json>' --dry-run` → preview the write.\n5. Re-run without `--dry-run` (double-confirm) — the prior subtree is fetched and\n   captured, and an inverse undo descriptor is recorded with an `_undo_id`.\n6. Validate: `proxy-aiops routes list`, `proxy-aiops analyze conflicts`, and\n   `proxy-aiops analyze errors` → confirm the edit did what you meant and did not\n   shadow an existing route.\n7. **Failure branch**: `proxy-aiops undo list` → `undo apply <id>` restores the captured\n   subtree exactly. If the config is too broken for a targeted undo, the\n   `config snapshot` from step 1 is your fallback via `load_config` — but note\n   `load_config` and `config delete` are **risk=high** with `--dry-run` + double\n   confirmation at the CLI. `load_config` replaces the *entire* config, so it is a\n   last resort, not a first instinct.\n\n## Governance & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide\nwhether a write is permitted. That is your agent's judgement, or the permission\nof the account you connect it with (a read-only HAProxy Data Plane API role, a\nscoped Traefik/Caddy admin API — writes then fail at the server). There is no\nread-only switch, policy file, or approval gate.\n\n- **Audit is the guarantee, and it is not bypassable.** Every operation — MCP and CLI alike — is logged to `~/.proxy-aiops/audit.db` (relocatable via `PROXY_AIOPS_HOME`): params (secrets redacted), result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- `PROXY_AUDIT_APPROVED_BY` / `PROXY_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Runaway guard** — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with `PROXY_RUNAWAY_MAX=0`.\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI; CLI writes execute through the same governed tools, so they are audited + undo-recorded.\n- Reversible writes capture the real fetched before-state and record an inverse descriptor that replays against the tool's own signature.\n- Traefik targets accept no writes at all — the support matrix teaches you to\n  edit the provider source instead.\n\n## References\n\n- `references/capabilities.md` — full tool + platform + API-path reference\n- `references/cli-reference.md` — CLI command reference\n- `references/setup-guide.md` — onboarding, credentials, and connectivity\n- `docs/VERIFICATION.md` — live-verification checklist (what the mock suite covers, and what a real-proxy run must prove)\n\nFile v0.9.3:_meta.json\n\n{\n  \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n  \"slug\": \"proxy-aiops\",\n  \"version\": \"0.9.3\",\n  \"publishedAt\": 1789453095482\n}\n\nFile v0.9.3:references/agent-guardrails.md\n\n# Agent guardrails — running proxy-aiops with a smaller / local model\n\nIf you drive these tools with a local model (Llama, Qwen, Mistral … via Goose,\nOllama, LM Studio, or any OpenAI-compatible runtime), you will get noticeably\nbetter results with a short system prompt. This page gives you one, and — more\nimportantly — tells you which guardrails you **no longer need to write**, because\nthe tool now enforces them itself.\n\nThe distinction matters. A guardrail in a prompt is a request. A guardrail in the\nharness is a guarantee. Anything below that we could move into the harness, we did.\n\n## Authorization is not this tool's job — decide it where it belongs\n\nWhether a write should happen is your decision, or the account's. The tool does\nnot gate it — there is no read-only switch and no approval prompt to configure.\nThe two right places to control read vs write:\n\n- **The account you connect with.** Give the HAProxy Data Plane API a read-only\n  role, or point the tool at a Traefik/Caddy admin API you have scoped down. A\n  write then fails at the server, which is the only place the permission actually\n  lives — a revoked permission cannot be argued around by a model, but a skill-side\n  flag can.\n- **Your agent's system prompt.** If you want an observe-only session, tell the\n  model not to call the write tools (they are clearly tagged `[WRITE]`).\n\nWhat the tool *does* guarantee is that you can always see what happened:\n\n## What the tool enforces — do not waste prompt budget on these\n\n| You might be tempted to prompt | Why you don't need to |\n|---|---|\n| \"Don't invent a value when a field is missing\" | Traefik, Caddy and HAProxy express the same concepts differently, so a field one platform has and another does not comes back as `null`, never as `\"\"`. A Caddy route's `raw` rule string is `null` — Caddy matches on a match list and has no such string — rather than a misleading empty rule. |\n| \"Tell me if the output was cut off\" | `search_config`, `traffic_stats` and `error_counters` return `{\"matches\"/\"services\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}` — one convention across the repo. Truncation is measured (the config walk deliberately overshoots by one) and not guessed from the count reaching the cap. |\n| \"Preserve the ordering / tell me what's most urgent\" | `backend_health_rca`, `error_rate_rca`, `route_conflict_analysis` and `cert_expiry_sweep` rank findings worst-first with the measured number attached. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | `delete_config_path` and `load_config` require a `--dry-run`-able preview plus double confirmation at the CLI. Config writes capture the prior value so the undo token can restore it. |\n| \"Log what you did\" | Every governed call is audited to `~/.proxy-aiops/audit.db` regardless of what the model says it did — and the CLI writes the same row the MCP path does, so there is no unaudited entry point. |\n| \"Don't get stuck retrying\" | The runaway guard trips a circuit breaker if the same call is hammered in a tight loop — a stuck agent is stopped rather than left to burn calls and time. |\n\n## What still needs a prompt\n\nThese are model-behaviour problems the harness cannot fix from the outside.\nCopy this into your agent's system prompt:\n\n```text\nYou operate a Traefik, Caddy or HAProxy reverse proxy through the proxy-aiops\nMCP tools.\n\nTOOL USE\n- Before answering any question about the current proxy, you MUST call a tool.\n  Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n  emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n  a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n  field that is true, say so and narrow the query instead of treating the\n  partial result as complete.\n- A null field means this platform does not express that concept, or did not\n  report it. Report it as \"not available\" — never infer it.\n- An \"unsupported\" field is a capability statement about the platform, not an\n  error and not a finding. Say the platform does not expose it; do not report\n  it as a problem with the proxy.\n- Report values exactly as returned. Traffic counters are cumulative since the\n  proxy started — compare rates, never quote a raw total as \"requests today\".\n\nSCOPE\n- Separate observation from interpretation. State what the tools returned, then\n  any interpretation, clearly marked as such.\n- Do not claim a backend is down unless a health/upstream result says so. A\n  route existing does not mean it resolves.\n- Do not confuse a route with a service, a service with an upstream server, or\n  an entrypoint with a route. One route names one service; one service has many\n  upstream servers.\n- The three platforms differ. The target's platform is in every result — do not\n  suggest a Traefik router rule on Caddy, or a Caddy config path on HAProxy.\n- On Traefik, /api/rawdata is the merged read-only view. Config changes belong\n  to the provider (the Docker labels, the file provider), not to this tool —\n  do not offer to edit what the tool cannot write.\n```\n\n## Recommended setup for a local model\n\nStart with a connection that *cannot* write, verify, and widen the account's\npermission only when you trust the setup — a proxy is the one component where a\nbad config change takes down everything behind it at once, and `load_config`\nreplaces the whole tree:\n\n```bash\n# e.g. give the HAProxy Data Plane API a read-only role, or point the tool at a\n# Traefik/Caddy admin API you have scoped down. Then:\nproxy-aiops doctor\n```\n\nOptionally annotate the audit trail with who is operating and why — recorded on\nevery row, never required:\n\n```bash\nexport PROXY_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport PROXY_AUDIT_RATIONALE=\"draining web-02 for maintenance\"\n```\n\n## If your model still struggles\n\nSome behaviours are model-capacity limits rather than prompt problems:\n\n- **Multi-tool workflows time out or drift.** Prefer the RCA tools —\n  `backend_health_rca` and `error_rate_rca` do the correlation inside one call,\n  so the model does not have to chain `list_services`, `list_upstreams` and\n  `error_counters` and keep service names straight.\n- **The model ignores later tool results in a long context.** The config\n  snapshot is the big payload here. Prefer `search_config` with a narrow query\n  over pulling the whole tree and asking the model to find things in it.\n- **The model describes calls instead of making them.** This is usually a\n  runtime/tool-calling-format mismatch, not a prompt problem — check that your\n  client advertises the tools in the format your model was trained on.\n\nFeedback on running this with a specific local model is genuinely useful —\nopen an issue at\n[github.com/AIops-tools/Proxy-AIops](https://github.com/AIops-tools/Proxy-AIops/issues)\nwith the model, runtime, and what went wrong.\n\nFile v0.9.3:references/capabilities.md\n\n# proxy-aiops — capabilities reference\n\n## Platforms\n\n| Platform | API | Auth | Default base_url |\n|----------|-----|------|------------------|\n| `traefik` | Traefik API (`/api/...`) + `/metrics` text | none, or optional HTTP Basic (username + stored secret) | `http://localhost:8080` |\n| `caddy` | Admin API (`/config/`, `/load`, `/reverse_proxy/upstreams`) | none, or optional HTTP Basic | `http://localhost:2019` |\n| `haproxy` | Data Plane API v2 (`/v2/...`) | HTTP Basic (username + stored secret, **required**) | `http://localhost:5555` |\n\nA per-target `platform` field selects the shape; the ops/CLI/MCP layers are\nplatform-neutral. Unsupported ops raise **teaching errors** (what to use\ninstead), never silent empties.\n\n## Support matrix\n\n| Capability | traefik | caddy | haproxy |\n|------------|:-------:|:-----:|:-------:|\n| version_info | ✅ `/api/version` | teaching note (no version endpoint) | ✅ `/v2/info` |\n| list_entrypoints | ✅ `/api/entrypoints` | ✅ server listen addresses | ✅ frontends |\n| list_routes / route_detail / find_route | ✅ routers (rule parsed) | ✅ routes (name = config path) | ✅ frontends (ACLs not parsed) |\n| list_services / service_detail | ✅ services + serverStatus | ✅ reverse_proxy routes + upstreams | ✅ backends + stats |\n| list_upstreams / upstream_detail | ✅ serverStatus map | ✅ `/reverse_proxy/upstreams` (fails→down) | ✅ stats server rows (status + check_status) |\n| list_middlewares | ✅ | teaching (inline handlers) | teaching (haproxy.cfg) |\n| list_certificates / cert_expiry_sweep | ✅ TLS routers + tls.domains | ✅ TLS listeners + automation subjects | teaching (.pem files) |\n| traffic_stats / error_counters | ✅ `/metrics` per-code | teaching (no per-route counters) | ✅ stats (`req_tot`, `hrsp_*`) |\n| config_snapshot / search_config | ✅ `/api/rawdata` (read-only) | ✅ `/config/` | teaching |\n| get/set_config_value, delete_config_path, load_config | teaching (edit the provider) | ✅ (the write surface) | teaching (use runtime writes) |\n| set_server_state / set_server_weight | teaching (provider) | teaching (config tree) | ✅ runtime servers |\n\n## MCP tools (28)\n\n### Reads (21)\n\n| Tool | Returns |\n|------|---------|\n| `proxy_overview` | platform/version + route/service counts + upstream up/down |\n| `version_info` | version/build info |\n| `list_entrypoints` | listeners: {name, address} |\n| `list_routes(host?)` | normalised routes: {name, hosts, paths, priority, service, tls, enabled, redirectTo} |\n| `route_detail(name)` | one route's full detail |\n| `find_route(host, path)` | routes that would serve a host/path, best first |\n| `list_services` | services/backends: {name, serversTotal, serversUp} |\n| `service_detail(name)` | one service's detail (+ haproxy servers) |\n| `list_upstreams(service?)` | server rows: {service, server, address, status up/down/maint/drain, checkInfo, weight} |\n| `upstream_detail(service, server)` | one server row |\n| `list_middlewares` | traefik middlewares (teaching elsewhere) |\n| `list_certificates(probe?, port?)` | TLS domain inventory (+ live expiry when probed) |\n| `traffic_stats` | per-service requests/latency/rate/sessions |\n| `error_counters` | per-service status-code counters |\n| `config_snapshot` | live config tree / merged dynamic state (sanitised) |\n| `search_config(query)` | matching config paths |\n| `get_config_value(path)` | one caddy config subtree |\n| `backend_health_rca(upstreams?)` | per-service outage/degraded findings + cause + action |\n| `cert_expiry_sweep(warn_days?, critical_days?, certs?)` | expiry buckets + renewal hints |\n| `error_rate_rca(error_rate_pct?, min_requests?, counters?)` | flagged services, dominant-code cause, vs-fleet baseline |\n| `route_conflict_analysis(routes?, services?)` | shadowed/dead routes, redirect loops |\n\nAll four analyses accept injected rows for pure offline analysis.\n\n### Writes (5) — all take `dry_run`, all capture prior state\n\n| Tool | Platform | Risk | Undo |\n|------|----------|:----:|------|\n| `set_config_value(path, value)` | caddy | medium | restore prior subtree (or delete a created path) |\n| `delete_config_path(path)` | caddy | **high** | re-create the captured subtree |\n| `load_config(config)` | caddy | **high** | re-load the snapshotted full config |\n| `set_server_state(backend, server, state)` | haproxy | medium | restore prior admin state (ready/drain/maint) |\n| `set_server_weight(backend, server, weight)` | haproxy | medium | restore prior weight (0-256) |\n\n### Undo (2)\n\n| Tool | Returns |\n|------|---------|\n| `undo_list(limit?)` | recorded undo descriptors, newest first, with their `_undo_id` |\n| `undo_apply(undo_id, dry_run?)` | replays the recorded inverse (governed like any other write) |\n\n`undo_apply` is governed like any other write (audited, capturing a before-state\nwhere the inverse is itself reversible). Undo descriptors are recorded to\n`~/.proxy-aiops/undo.db`; their params match each tool's own signature\n(replayable as-is).\n\n## Modelled API paths (mock-validated)\n\n- traefik: `/api/version`, `/api/overview`, `/api/entrypoints`,\n  `/api/http/routers[/{name}]`, `/api/http/services[/{name}]`,\n  `/api/http/middlewares`, `/api/rawdata`, `/metrics`\n- caddy: `/config/[{path}]`, `/load`, `/reverse_proxy/upstreams`\n- haproxy: `/v2/info`, `/v2/services/haproxy/configuration/{frontends|backends|servers|binds}`,\n  `/v2/services/haproxy/runtime/servers[/{name}]?backend=...`,\n  `/v2/services/haproxy/stats/native`\n\nEvery substituted path value is percent-encoded centrally; caddy config paths\nreject dot-segments.\n\nFile v0.9.3:references/cli-reference.md\n\n# proxy-aiops — CLI reference\n\nGlobal option on most commands: `--target/-t <name>` (default: first target in\nconfig).\n\n## Setup & health\n\n```bash\nproxy-aiops init                 # interactive wizard: platform, base_url, TLS verify, encrypted secret\nproxy-aiops doctor               # config + secrets + connectivity (probe per platform)\nproxy-aiops doctor --skip-auth   # skip the connectivity probe\nproxy-aiops overview             # one-shot: version + routes/services + upstream health\n```\n\n## Reads\n\n```bash\nproxy-aiops routes list [--host app.example.com]\nproxy-aiops routes show <name>              # traefik router name / caddy config path / haproxy frontend\nproxy-aiops routes find <host> [--path /]   # which routes would serve host/path\nproxy-aiops services list\nproxy-aiops services show <name>\nproxy-aiops services upstreams [--service <name>]\nproxy-aiops certs [--sweep] [--warn-days 30] [--critical-days 7] [--port 443]\nproxy-aiops config snapshot\nproxy-aiops config search <query>\nproxy-aiops config get <path>\n```\n\n## Flagship analyses\n\n```bash\nproxy-aiops analyze health [--service <name>]   # backend/upstream health RCA\nproxy-aiops analyze errors [--rate 5.0] [--min-requests 30]   # 5xx error-rate RCA\nproxy-aiops analyze conflicts                   # shadowed/dead routes, redirect loops\n```\n\n## Governed writes (dry-run + double-confirm; audited + undo-recorded)\n\n```bash\n# caddy config (teaching error on traefik/haproxy targets)\nproxy-aiops config set <path> '<json>' [--dry-run]\nproxy-aiops config delete <path> [--dry-run]        # risk=high, double-confirm\n\n# haproxy runtime servers (teaching error on traefik/caddy targets)\nproxy-aiops server state <backend> <server> ready|drain|maint [--dry-run]\nproxy-aiops server weight <backend> <server> <0-256> [--dry-run]\n```\n\nHigh-risk writes prompt for double confirmation at the CLI. Optionally export\n`PROXY_AUDIT_APPROVED_BY` (and `PROXY_AUDIT_RATIONALE`) to annotate the audit\nrow with who/why — never required.\n\n## Secrets\n\n```bash\nproxy-aiops secret set <target>      # store encrypted (hidden prompt)\nproxy-aiops secret list              # names only, never values\nproxy-aiops secret rm <target>\nproxy-aiops secret migrate           # import legacy plaintext .env\nproxy-aiops secret rotate-password   # re-encrypt under a new master password\n```\n\n## MCP server\n\n```bash\nproxy-aiops mcp        # stdio transport (or: proxy-aiops-mcp)\n```\n\n## Environment variables\n\n| Variable | Purpose |\n|----------|---------|\n| `PROXY_AIOPS_MASTER_PASSWORD` | unlock secrets.enc non-interactively (MCP/CI) |\n| `PROXY_AIOPS_CONFIG` | alternate config.yaml path (MCP server) |\n| `PROXY_AIOPS_HOME` | relocate config/audit/undo state dir |\n| `PROXY_AUDIT_APPROVED_BY` / `PROXY_AUDIT_RATIONALE` | optional approver/rationale annotations recorded on the audit row |\n| `PROXY_MAX_TOOL_CALLS` / `PROXY_MAX_TOOL_SECONDS` | per-process budget ceilings |\n| `PROXY_RUNAWAY_MAX` / `PROXY_RUNAWAY_WINDOW_SEC` | runaway circuit-breaker tuning |\n| `PROXY_<TARGET>_SECRET` | legacy plaintext fallback (deprecated) |\n\nFile v0.9.3:references/setup-guide.md\n\n# proxy-aiops — setup guide\n\n## 1. Enable each platform's API\n\n- **traefik** — expose the API: `--api=true` with a router on `api@internal`\n  (or `--api.insecure=true` in a lab, which serves it on `:8080`). For\n  error-rate analysis also enable the metrics endpoint\n  (Traefik's metrics provider serves `/metrics`).\n- **caddy** — the admin API is on `localhost:2019` by default (the `admin`\n  key in the config controls the listener). proxy-aiops needs plain HTTP\n  reachability to it; keep it bound to localhost or an internal network.\n- **haproxy** — run the **Data Plane API** sidecar (`dataplaneapi`) pointing at\n  haproxy.cfg, with a userlist user. Note the listen address (default `:5555`)\n  and the user/password.\n\n## 2. Onboard\n\n```bash\nuv tool install proxy-aiops\nproxy-aiops init\n```\n\nThe wizard asks for: target name → platform (`traefik` / `caddy` / `haproxy`)\n→ API base URL (per-platform default offered) → TLS verification (default ON;\nanswer No only for self-signed lab certs) → credentials:\n\n- **haproxy**: Data Plane API username + password (password stored encrypted —\n  required).\n- **traefik / caddy**: optional Basic-auth username/password — leave both\n  empty for the common unauthenticated-localhost case (no store entry means no\n  auth header is sent).\n\n## 3. Verify\n\n```bash\nproxy-aiops doctor\n```\n\nDoctor checks config, the encrypted store (and its permissions), per-target\nsecrets (respecting which platforms need one), then probes each target's cheap\nhealth/info endpoint: traefik `/api/version`, caddy `/config/`, haproxy\n`/v2/info`.\n\n## 4. Wire up an MCP client\n\n```json\n{\n  \"mcpServers\": {\n    \"proxy-aiops\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"proxy-aiops\", \"proxy-aiops-mcp\"],\n      \"env\": { \"PROXY_AIOPS_MASTER_PASSWORD\": \"your-master-password\" }\n    }\n  }\n}\n```\n\nMCP clients do not inherit your shell profile: set\n`PROXY_AIOPS_MASTER_PASSWORD` in the `env` block whenever any target has a\nstored secret, and `PROXY_AIOPS_CONFIG` / `PROXY_AIOPS_HOME` if you relocated\nstate.\n\n## Config file\n\n`~/.proxy-aiops/config.yaml`:\n\n```yaml\ntargets:\n  - name: edge1\n    platform: traefik\n    base_url: http://192.0.2.10:8080\n    verify_ssl: true\n  - name: caddy1\n    platform: caddy\n    base_url: http://127.0.0.1:2019\n  - name: lb1\n    platform: haproxy\n    base_url: http://192.0.2.20:5555\n    username: dpapi\n```\n\nSecrets never live here — only in `secrets.enc` (or the deprecated\n`PROXY_<TARGET>_SECRET` env fallback).\n\n## Troubleshooting\n\n- **401/403** — haproxy: wrong Data Plane API user/password; traefik/caddy: a\n  Basic-auth layer is in front (store a secret) or a stale secret is stored\n  (remove it with `proxy-aiops secret rm <target>`).\n- **404 on every call** — the API is not enabled (traefik `api@internal`\n  router missing; caddy admin listener disabled; dataplaneapi not running).\n- **Connection refused** — check `base_url` (scheme + port) and that the\n  endpoint is bound beyond localhost if proxy-aiops runs on another host.\n- **cert sweep returns unknowns** — the probe needs TCP reach to each domain\n  on the TLS port (default 443, max 25 domains, 5s each).\n\nFile v0.9.3:skill-card.md\n\n## Description:\n\nProxy AIops helps agents operate Traefik, Caddy, and HAProxy reverse proxies and load balancers by inspecting routes, upstreams, certificates, traffic, configuration, and common failure modes, with governed write support for Caddy configuration and HAProxy runtime changes.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[zw008](https://clawhub.ai/user/zw008)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, SREs, and operators use this skill to diagnose and manage Traefik, Caddy, and HAProxy edge proxies, including route lookup, upstream health RCA, TLS expiry checks, 5xx analysis, configuration inspection, and governed operational changes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can perform high-impact proxy changes using stored credentials.\n\nMitigation: Use read-only or tightly scoped proxy API accounts by default, require dry-run review before writes, and widen permissions only for approved operational changes.\n\nRisk: Authenticated management endpoints exposed beyond loopback can increase operational and credential risk.\n\nMitigation: Require HTTPS for non-loopback endpoints, keep proxy admin APIs on localhost or internal networks where possible, and keep TLS verification enabled outside self-signed labs.\n\nRisk: Persistent MCP configuration and local proxy-aiops state can expose sensitive secrets, audit history, or undo data.\n\nMitigation: Avoid hardcoding PROXY_AIOPS_MASTER_PASSWORD in persistent config and protect ~/.proxy-aiops or any relocated state directory as sensitive material.\n\nRisk: Installing an unreviewed package version can introduce unvetted proxy-control behavior.\n\nMitigation: Pin proxy-aiops to a reviewed version or hash before installing it in production-facing agent environments.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/zw008/skills/proxy-aiops)\n- [Project homepage from ClawHub metadata](https://github.com/AIops-tools/Proxy-AIops)\n- [Capabilities reference](references/capabilities.md)\n- [CLI reference](references/cli-reference.md)\n- [Setup guide](references/setup-guide.md)\n- [Agent guardrails](references/agent-guardrails.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with CLI commands, MCP tool-use recommendations, proxy analysis findings, and configuration-change instructions.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include risk-tiered write guidance, dry-run reminders, audit and undo references, and scoped proxy-operation recommendations.]\n\n## Skill Version(s):\n\n0.9.3 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.9.2: 7 files, 18442 bytes\n\nFiles: references/agent-guardrails.md (7072b), references/capabilities.md (5569b), references/cli-reference.md (3069b), references/setup-guide.md (3153b), skill-card.md (2639b), SKILL.md (17439b), _meta.json (130b)\n\nFile v0.9.2:SKILL.md\n\n---\nname: proxy-aiops\nslug: proxy-aiops\ndisplayName: \"Proxy AIops\"\nsummary: \"Governed Traefik + Caddy + HAProxy ops: routes, upstreams, certs, 5xx RCA. 28 tools.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxy-AIops\ntags: [aiops, mcp, governance, proxy]\ndescription: >\n  Use this skill whenever the user needs to operate a Traefik, Caddy or HAProxy reverse proxy / load balancer — a one-shot overview, routes (routers / caddy routes / frontends) with host/path matching, services and server-level upstream health, middlewares, TLS certificate inventory with an expiry sweep, traffic and 5xx error counters, config snapshot/search, four flagship RCAs (backend health, cert expiry, error rate, route conflicts), and governed writes (caddy config set/delete/load with prior-config capture; haproxy server drain/maint/ready and weight).\n  Always use this skill for \"Traefik\", \"Caddy\", \"HAProxy\", \"reverse proxy\", \"load balancer\", \"upstream down\", \"502/503/504 errors\", \"bad gateway\", \"cert expiring\", \"TLS certificate\", \"route not matching\", \"which route serves this host\", \"drain a server\", \"server weight\", \"redirect loop\" when the context is a Traefik/Caddy/HAProxy edge.\n  Do NOT use when the target is something other than a Traefik/Caddy/HAProxy proxy (a hypervisor, storage appliance, backup product, container-orchestration cluster, multi-vendor router/switch config, or OT/industrial equipment) — route those to the appropriate other AIops-tools skill. Do NOT use for firewall rules — use firewall-aiops. Managed cloud load balancers are out of scope.\n  Governed proxy operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers). Behaviour is validated by a mock-based test suite; see docs/VERIFICATION.md for the live-verification checklist.\ninstaller:\n  kind: uv\n  package: proxy-aiops\nargument-hint: \"[a route/service/backend name, a hostname, or describe your proxy task]\"\nallowed-tools:\n  - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"proxy-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"PROXY_AIOPS_CONFIG\",\"PROXY_AIOPS_MASTER_PASSWORD\"]},\"homepage\":\"https://github.com/AIops-tools/Proxy-AIops\",\"emoji\":\"🔀\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n  Standalone, self-governed reverse-proxy operations across Traefik (API /api/..., metrics-text counters via /metrics), Caddy (admin API, default localhost:2019 — carries the write surface) and HAProxy (Data Plane API v2 /v2/..., HTTP Basic auth). Each target in the config names its own platform, and a name-keyed platform registry selects the API shape; an explicit support matrix raises teaching errors for ops a platform cannot do (traefik writes → its providers; caddy error counters → access logs; haproxy certs → the .pem pipeline), never a silent no-op. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency.\n  All write operations are audited to a local SQLite DB under ~/.proxy-aiops/ (relocatable via PROXY_AIOPS_HOME).\n  Credentials: the HAProxy Data Plane API password (required) or an optional Basic-auth credential for Traefik/Caddy is stored ENCRYPTED in ~/.proxy-aiops/secrets.enc (Fernet/AES-128 + scrypt-derived key) — never plaintext on disk. Traefik and Caddy usually run unauthenticated on localhost, so their secret is optional (no store entry = no auth header). Run 'proxy-aiops init' to onboard (it asks for the platform), or 'proxy-aiops secret set <target>'. The store is unlocked by a master password from PROXY_AIOPS_MASTER_PASSWORD (non-interactive/MCP/CI) or an interactive prompt (CLI on a TTY). A legacy plaintext env var PROXY_<TARGET_NAME_UPPER>_SECRET is still honoured as a fallback with a deprecation warning (migrate with 'proxy-aiops secret migrate'). Secrets are never logged or echoed.\n  State-changing operations pass through the @governed_tool decorator (budget guard + audit + risk-tier labelling). delete_config_path and load_config (full config replace) are risk=high with dry_run + double confirmation at the CLI. Reversible writes (set_config_value, delete_config_path, load_config, set_server_state, set_server_weight) capture the real fetched before-state and record an inverse undo descriptor whose params replay against the tool's own signature.\n  Webhooks: none — no outbound network calls beyond the configured proxy APIs, plus (only when the operator runs the cert sweep with probing) a bounded TLS handshake per inventoried domain.\n  SSL: verify_ssl defaults to true; disable only for self-signed lab certs.\n  Transitive dependencies: httpx (HTTP client), cryptography (secret store + cert parsing), and the MCP SDK. No post-install scripts or background services.\n---\n\n# Proxy AIops\n\n> **Disclaimer**: Community-maintained open-source project, **not affiliated with, endorsed by, or sponsored by Traefik Labs, the Caddy project, HAProxy Technologies, or the HAProxy project.** Traefik, Caddy and HAProxy are trademarks of their respective owners. Source at [github.com/AIops-tools/Proxy-AIops](https://github.com/AIops-tools/Proxy-AIops) under the MIT license.\n\nGoverned reverse-proxy operations — **28 MCP tools** across **Traefik** (API +\n`/metrics`), **Caddy** (admin API) and **HAProxy** (Data Plane API v2), every\none wrapped with the bundled `@governed_tool` harness: a local unified audit\nlog under `~/.proxy-aiops/`, policy engine, token/runaway budget guard,\nundo-token recording, and descriptive risk tiers. A per-target\n`platform` field selects the API shape, so the same tools work on all three\nproxies and one config can span a mixed edge. An explicit **support matrix**\nraises teaching errors for ops a platform cannot do — never a silent no-op.\nCredentials are stored **encrypted** (`~/.proxy-aiops/secrets.enc`, Fernet +\nscrypt) — never plaintext on disk; Traefik/Caddy secrets are optional\n(unauthenticated localhost is the common case).\n\n> **Standalone**: the governance harness is bundled in the package\n> (`proxy_aiops.governance`) — no external skill-family dependency. Behaviour is\n> covered by a mock-based test suite; `docs/VERIFICATION.md` is the checklist for a\n> live run (all three platforms are free/self-hostable, so a small lab is enough).\n\n## What This Skill Does\n\n| Group | Tools | Count | R/W |\n|-------|-------|:-----:|:---:|\n| **Status** | proxy_overview, version_info, list_entrypoints | 3 | read |\n| **Routes** | list_routes, route_detail, find_route | 3 | read |\n| **Services** | list_services, service_detail, list_upstreams, upstream_detail, list_middlewares | 5 | read |\n| **Certificates** | list_certificates | 1 | read |\n| **Traffic** | traffic_stats, error_counters | 2 | read |\n| **Config** | config_snapshot, search_config, get_config_value | 3 | read |\n| **Flagship analyses** | backend_health_rca, cert_expiry_sweep, error_rate_rca, route_conflict_analysis | 4 | read |\n| **Writes (caddy)** | set_config_value (med), delete_config_path (**high**), load_config (**high**) | 3 | write |\n| **Writes (haproxy)** | set_server_state, set_server_weight | 2 | write (med) |\n| **Undo** | undo_list, undo_apply | 2 | read / write |\n\nThe four flagship analyses are transparent heuristics that report their\nnumbers, never a black-box verdict: `backend_health_rca` groups down upstreams\nper service and maps the health-check failure class (connection refused / L4\ntimeout / TLS / L7 / DNS / maint) to a cause + action; `cert_expiry_sweep`\nbuckets certs by days-to-expiry with per-platform renewal hints;\n`error_rate_rca` ranks services by 5xx share vs the fleet baseline and maps\nthe dominant code (502/503/504/500) to a cause; `route_conflict_analysis`\nfinds shadowed routes, dead routes, and redirect loops.\n\n## Quick Install\n\n```bash\nuv tool install proxy-aiops\nproxy-aiops init       # wizard: pick platform (traefik/caddy/haproxy) + optional encrypted secret\nproxy-aiops doctor\n```\n\nOr as an OpenClaw plugin, which installs this skill and its MCP server together:\n\n```bash\nopenclaw plugins install clawhub:@zw008/proxy-aiops\nopenclaw skills info proxy-aiops          # expect: Visible to model: yes\n```\n\nNeeds `uvx` on `PATH`: the MCP server is fetched with uv, pinned to this release.\n\n## When to Use This Skill\n\n- Get a one-shot snapshot (`overview` / `version_info` / `list_entrypoints`)\n- Investigate 502/503/504 spikes (`error_rate_rca`) → dominant code → cause\n- Find why an upstream/backend is down (`list_upstreams`, `backend_health_rca`)\n- Sweep TLS cert expiry across the edge (`certs --sweep` / `cert_expiry_sweep`)\n- Audit routing hygiene (`route_conflict_analysis` — shadowed/dead routes,\n  redirect loops) and answer \"which route serves this host?\" (`find_route`)\n- Safely drain/return an haproxy server (`set_server_state`, reversible +\n  undo-recorded) or adjust its weight (`set_server_weight`)\n- Safely edit caddy config (`set_config_value` / `delete_config_path` /\n  `load_config` — prior config captured, undo replays the restore)\n\n**Do NOT use when** the target is not a Traefik/Caddy/HAProxy proxy — route\nhypervisor, storage, backup, cluster, network-device, or OT/industrial work to\nthe appropriate other AIops-tools skill. Do NOT use for firewall rules — use\nfirewall-aiops.\n\n## Related Skills — Skill Routing\n\n| If the user wants… | Use |\n|--------------------|-----|\n| Traefik / Caddy / HAProxy proxy ops | **proxy-aiops** (this skill) |\n| Firewall rules / NAT / gateway health | **firewall-aiops** |\n| A non-proxy platform (hypervisor, storage, backup, cluster, network devices, OT edge) | the appropriate **other AIops-tools** skill |\n| Managed cloud load balancers | out of scope for this tool |\n\n## Common Workflows\n\n### 1. A 5xx spike — is it the app or the backend?\n\n1. `proxy-aiops doctor` → confirm the proxy's API is reachable before you trust any\n   number that follows.\n2. `proxy-aiops overview` → the one-shot picture: platform/version, entrypoints, and\n   route/service counts, so you know the blast radius.\n3. `proxy-aiops analyze errors --rate 5 --min-requests 100` → services ranked by 5xx\n   share against the fleet baseline, with the **dominant status code mapped to a cause**\n   (503 no upstream available / 502 connection failed / 504 timeout / 500 app error).\n   The `--min-requests` floor keeps a single failed request on a quiet service from\n   outranking a real incident.\n4. `proxy-aiops analyze health --service <name>` → the same service from the backend\n   side: which servers are failing their health check and what class of failure it is.\n   If the servers are healthy, the 5xx is coming from **the application**, and no amount\n   of proxy work will fix it — hand it off.\n5. If one server is the problem, take it out of rotation gracefully:\n   `proxy-aiops services upstreams <backend>` to get the exact server name, then\n   `proxy-aiops server state <backend> <server> drain --dry-run` and re-run for real\n   (double-confirm; the prior state is captured as the undo descriptor). `drain` lets\n   in-flight connections finish — reach for `maint` only when you need it out *now*.\n6. Re-run `proxy-aiops analyze errors` to confirm the rate dropped.\n7. **Failure branch**: if draining one server just moves the load onto the next one to\n   fall over, you are shedding capacity you do not have — put it straight back with\n   `proxy-aiops undo list` → `undo apply <id>` (restores the **prior** state, not a\n   hardcoded `ready`) before you drain a second. Note `server state` / `server weight`\n   are **haproxy runtime** operations; on a traefik or caddy target the tool raises a\n   teaching error naming the right mechanism rather than silently doing nothing.\n\n### 2. Certificates about to expire\n\n1. `proxy-aiops certs --sweep --warn-days 30 --critical-days 7` → the TLS domain\n   inventory with each cert **live-probed** on port 443 and bucketed\n   expired / critical / warning, plus a renewal hint.\n2. `proxy-aiops certs --sweep --port 8443` for any entrypoint not on 443 —\n   the sweep probes one port at a time, so a non-standard listener needs its own pass.\n3. `proxy-aiops overview` and `proxy-aiops routes list` → map each expiring domain back\n   to the routes that actually serve it, so you renew what is in use and ignore what is\n   not.\n4. Renew through the platform's own mechanism (ACME for traefik/caddy), then re-run the\n   sweep to confirm the new expiry date.\n5. **Failure branch**: on a **haproxy** target the sweep returns a teaching note rather\n   than results — haproxy serves certs from `.pem` files on disk, outside this tool's\n   API surface, so check those with your file-level tooling. If a probe fails to connect,\n   distinguish \"cert is bad\" from \"port is closed\" with\n   `proxy-aiops routes find <host>` before assuming a certificate problem.\n\n### 3. \"Why is this hostname hitting the wrong backend?\"\n\n1. `proxy-aiops routes find <host> --path /api` → best-matching routes, most specific\n   first. This is the direct answer to \"who serves this request\".\n2. `proxy-aiops routes show <route-id>` → the full rule, priority, middlewares, and the\n   service it points at.\n3. `proxy-aiops analyze conflicts` → **shadowed** routes (fully covered by an earlier or\n   higher-priority route), **dead** routes (the service is missing, or has zero servers\n   up), and redirect loops — each finding names the covering route or the missing\n   service rather than just flagging a number.\n4. `proxy-aiops services show <service>` and `proxy-aiops services upstreams <service>`\n   → confirm the service the route resolves to actually has healthy servers behind it.\n5. Fix the ordering/priority at its source: on **caddy** via `proxy-aiops config set`\n   (recipe 4); on **traefik**, in the provider that generated the route (labels, file\n   provider, CRD) — traefik's API is read-only, and the tool says so explicitly instead\n   of pretending to write.\n6. **Failure branch**: if `routes find` returns nothing, the request is not matching any\n   route at all — check `proxy-aiops overview` for the entrypoints and confirm the\n   listener you think you are hitting exists. A \"dead route\" finding whose service is\n   missing usually means a config was applied referencing a service that was never\n   created; fixing the route without creating the service just moves the 404.\n\n### 4. Edit a caddy config subtree, reversibly\n\n1. `proxy-aiops config snapshot` → the whole current config; take this **before** you\n   change anything, so you have an out-of-band copy independent of the undo store.\n2. `proxy-aiops config search <needle>` → locate the config path holding the value you\n   want (searching beats guessing at caddy's nested JSON paths).\n3. `proxy-aiops config get <path>` → read the exact current subtree you are about to\n   replace.\n4. `proxy-aiops config set <path> '<json>' --dry-run` → preview the write.\n5. Re-run without `--dry-run` (double-confirm) — the prior subtree is fetched and\n   captured, and an inverse undo descriptor is recorded with an `_undo_id`.\n6. Validate: `proxy-aiops routes list`, `proxy-aiops analyze conflicts`, and\n   `proxy-aiops analyze errors` → confirm the edit did what you meant and did not\n   shadow an existing route.\n7. **Failure branch**: `proxy-aiops undo list` → `undo apply <id>` restores the captured\n   subtree exactly. If the config is too broken for a targeted undo, the\n   `config snapshot` from step 1 is your fallback via `load_config` — but note\n   `load_config` and `config delete` are **risk=high** with `--dry-run` + double\n   confirmation at the CLI. `load_config` replaces the *entire* config, so it is a\n   last resort, not a first instinct.\n\n## Governance & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide\nwhether a write is permitted. That is your agent's judgement, or the permission\nof the account you connect it with (a read-only HAProxy Data Plane API role, a\nscoped Traefik/Caddy admin API — writes then fail at the server). There is no\nread-only switch, policy file, or approval gate.\n\n- **Audit is the guarantee, and it is not bypassable.** Every operation — MCP and CLI alike — is logged to `~/.proxy-aiops/audit.db` (relocatable via `PROXY_AIOPS_HOME`): params (secrets redacted), result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- `PROXY_AUDIT_APPROVED_BY` / `PROXY_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Runaway guard** — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with `PROXY_RUNAWAY_MAX=0`.\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI; CLI writes execute through the same governed tools, so they are audited + undo-recorded.\n- Reversible writes capture the real fetched before-state and record an inverse descriptor that replays against the tool's own signature.\n- Traefik targets accept no writes at all — the support matrix teaches you to\n  edit the provider source instead.\n\n## References\n\n- `references/capabilities.md` — full tool + platform + API-path reference\n- `references/cli-reference.md` — CLI command reference\n- `references/setup-guide.md` — onboarding, credentials, and connectivity\n- `docs/VERIFICATION.md` — live-verification checklist (what the mock suite covers, and what a real-proxy run must prove)\n\nFile v0.9.2:_meta.json\n\n{\n  \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n  \"slug\": \"proxy-aiops\",\n  \"version\": \"0.9.2\",\n  \"publishedAt\": 1789224108908\n}\n\nFile v0.9.2:references/agent-guardrails.md\n\n# Agent guardrails — running proxy-aiops with a smaller / local model\n\nIf you drive these tools with a local model (Llama, Qwen, Mistral … via Goose,\nOllama, LM Studio, or any OpenAI-compatible runtime), you will get noticeably\nbetter results with a short system prompt. This page gives you one, and — more\nimportantly — tells you which guardrails you **no longer need to write**, because\nthe tool now enforces them itself.\n\nThe distinction matters. A guardrail in a prompt is a request. A guardrail in the\nharness is a guarantee. Anything below that we could move into the harness, we did.\n\n## Authorization is not this tool's job — decide it where it belongs\n\nWhether a write should happen is your decision, or the account's. The tool does\nnot gate it — there is no read-only switch and no approval prompt to configure.\nThe two right places to control read vs write:\n\n- **The account you connect with.** Give the HAProxy Data Plane API a read-only\n  role, or point the tool at a Traefik/Caddy admin API you have scoped down. A\n  write then fails at the server, which is the only place the permission actually\n  lives — a revoked permission cannot be argued around by a model, but a skill-side\n  flag can.\n- **Your agent's system prompt.** If you want an observe-only session, tell the\n  model not to call the write tools (they are clearly tagged `[WRITE]`).\n\nWhat the tool *does* guarantee is that you can always see what happened:\n\n## What the tool enforces — do not waste prompt budget on these\n\n| You might be tempted to prompt | Why you don't need to |\n|---|---|\n| \"Don't invent a value when a field is missing\" | Traefik, Caddy and HAProxy express the same concepts differently, so a field one platform has and another does not comes back as `null`, never as `\"\"`. A Caddy route's `raw` rule string is `null` — Caddy matches on a match list and has no such string — rather than a misleading empty rule. |\n| \"Tell me if the output was cut off\" | `search_config`, `traffic_stats` and `error_counters` return `{\"matches\"/\"services\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}` — one convention across the repo. Truncation is measured (the config walk deliberately overshoots by one) and not guessed from the count reaching the cap. |\n| \"Preserve the ordering / tell me what's most urgent\" | `backend_health_rca`, `error_rate_rca`, `route_conflict_analysis` and `cert_expiry_sweep` rank findings worst-first with the measured number attached. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | `delete_config_path` and `load_config` require a `--dry-run`-able preview plus double confirmation at the CLI. Config writes capture the prior value so the undo token can restore it. |\n| \"Log what you did\" | Every governed call is audited to `~/.proxy-aiops/audit.db` regardless of what the model says it did — and the CLI writes the same row the MCP path does, so there is no unaudited entry point. |\n| \"Don't get stuck retrying\" | The runaway guard trips a circuit breaker if the same call is hammered in a tight loop — a stuck agent is stopped rather than left to burn calls and time. |\n\n## What still needs a prompt\n\nThese are model-behaviour problems the harness cannot fix from the outside.\nCopy this into your agent's system prompt:\n\n```text\nYou operate a Traefik, Caddy or HAProxy reverse proxy through the proxy-aiops\nMCP tools.\n\nTOOL USE\n- Before answering any question about the current proxy, you MUST call a tool.\n  Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n  emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n  a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n  field that is true, say so and narrow the query instead of treating the\n  partial result as complete.\n- A null field means this platform does not express that concept, or did not\n  report it. Report it as \"not available\" — never infer it.\n- An \"unsupported\" field is a capability statement about the platform, not an\n  error and not a finding. Say the platform does not expose it; do not report\n  it as a problem with the proxy.\n- Report values exactly as returned. Traffic counters are cumulative since the\n  proxy started — compare rates, never quote a raw total as \"requests today\".\n\nSCOPE\n- Separate observation from interpretation. State what the tools returned, then\n  any interpretation, clearly marked as such.\n- Do not claim a backend is down unless a health/upstream result says so. A\n  route existing does not mean it resolves.\n- Do not confuse a route with a service, a service with an upstream server, or\n  an entrypoint with a route. One route names one service; one service has many\n  upstream servers.\n- The three platforms differ. The target's platform is in every result — do not\n  suggest a Traefik router rule on Caddy, or a Caddy config path on HAProxy.\n- On Traefik, /api/rawdata is the merged read-only view. Config changes belong\n  to the provider (the Docker labels, the file provider), not to this tool —\n  do not offer to edit what the tool cannot write.\n```\n\n## Recommended setup for a local model\n\nStart with a connection that *cannot* write, verify, and widen the account's\npermission only when you trust the setup — a proxy is the one component where a\nbad config change takes down everything behind it at once, and `load_config`\nreplaces the whole tree:\n\n```bash\n# e.g. give the HAProxy Data Plane API a read-only role, or point the tool at a\n# Traefik/Caddy admin API you have scoped down. Then:\nproxy-aiops doctor\n```\n\nOptionally annotate the audit trail with who is operating and why — recorded on\nevery row, never required:\n\n```bash\nexport PROXY_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport PROXY_AUDIT_RATIONALE=\"draining web-02 for maintenance\"\n```\n\n## If your model still struggles\n\nSome behaviours are model-capacity limits rather than prompt problems:\n\n- **Multi-tool workflows time out or drift.** Prefer the RCA tools —\n  `backend_health_rca` and `error_rate_rca` do the correlation inside one call,\n  so the model does not have to chain `list_services`, `list_upstreams` and\n  `error_counters` and keep service names straight.\n- **The model ignores later tool results in a long context.** The config\n  snapshot is the big payload here. Prefer `search_config` with a narrow query\n  over pulling the whole tree and asking the model to find things in it.\n- **The model describes calls instead of making them.** This is usually a\n  runtime/tool-calling-format mismatch, not a prompt problem — check that your\n  client advertises the tools in the format your model was trained on.\n\nFeedback on running this with a specific local model is genuinely useful —\nopen an issue at\n[github.com/AIops-tools/Proxy-AIops](https://github.com/AIops-tools/Proxy-AIops/issues)\nwith the model, runtime, and what went wrong.\n\nFile v0.9.2:references/capabilities.md\n\n# proxy-aiops — capabilities reference\n\n## Platforms\n\n| Platform | API | Auth | Default base_url |\n|----------|-----|------|------------------|\n| `traefik` | Traefik API (`/api/...`) + `/metrics` text | none, or optional HTTP Basic (username + stored secret) | `http://localhost:8080` |\n| `caddy` | Admin API (`/config/`, `/load`, `/reverse_proxy/upstreams`) | none, or optional HTTP Basic | `http://localhost:2019` |\n| `haproxy` | Data Plane API v2 (`/v2/...`) | HTTP Basic (username + stored secret, **required**) | `http://localhost:5555` |\n\nA per-target `platform` field selects the shape; the ops/CLI/MCP layers are\nplatform-neutral. Unsupported ops raise **teaching errors** (what to use\ninstead), never silent empties.\n\n## Support matrix\n\n| Capability | traefik | caddy | haproxy |\n|------------|:-------:|:-----:|:-------:|\n| version_info | ✅ `/api/version` | teaching note (no version endpoint) | ✅ `/v2/info` |\n| list_entrypoints | ✅ `/api/entrypoints` | ✅ server listen addresses | ✅ frontends |\n| list_routes / route_detail / find_route | ✅ routers (rule parsed) | ✅ routes (name = config path) | ✅ frontends (ACLs not parsed) |\n| list_services / service_detail | ✅ services + serverStatus | ✅ reverse_proxy routes + upstreams | ✅ backends + stats |\n| list_upstreams / upstream_detail | ✅ serverStatus map | ✅ `/reverse_proxy/upstreams` (fails→down) | ✅ stats server rows (status + check_status) |\n| list_middlewares | ✅ | teaching (inline handlers) | teaching (haproxy.cfg) |\n| list_certificates / cert_expiry_sweep | ✅ TLS routers + tls.domains | ✅ TLS listeners + automation subjects | teaching (.pem files) |\n| traffic_stats / error_counters | ✅ `/metrics` per-code | teaching (no per-route counters) | ✅ stats (`req_tot`, `hrsp_*`) |\n| config_snapshot / search_config | ✅ `/api/rawdata` (read-only) | ✅ `/config/` | teaching |\n| get/set_config_value, delete_config_path, load_config | teaching (edit the provider) | ✅ (the write surface) | teaching (use runtime writes) |\n| set_server_state / set_server_weight | teaching (provider) | teaching (config tree) | ✅ runtime servers |\n\n## MCP tools (28)\n\n### Reads (21)\n\n| Tool | Returns |\n|------|---------|\n| `proxy_overview` | platform/version + route/service counts + upstream up/down |\n| `version_info` | version/build info |\n| `list_entrypoints` | listeners: {name, address} |\n| `list_routes(host?)` | normalised routes: {name, hosts, paths, priority, service, tls, enabled, redirectTo} |\n| `route_detail(name)` | one route's full detail |\n| `find_route(host, path)` | routes that would serve a host/path, best first |\n| `list_services` | services/backends: {name, serversTotal, serversUp} |\n| `service_detail(name)` | one service's detail (+ haproxy servers) |\n| `list_upstreams(service?)` | server rows: {service, server, address, status up/down/maint/drain, checkInfo, weight} |\n| `upstream_detail(service, server)` | one server row |\n| `list_middlewares` | traefik middlewares (teaching elsewhere) |\n| `list_certificates(probe?, port?)` | TLS domain inventory (+ live expiry when probed) |\n| `traffic_stats` | per-service requests/latency/rate/sessions |\n| `error_counters` | per-service status-code counters |\n| `config_snapshot` | live config tree / merged dynamic state (sanitised) |\n| `search_config(query)` | matching config paths |\n| `get_config_value(path)` | one caddy config subtree |\n| `backend_health_rca(upstreams?)` | per-service outage/degraded findings + cause + action |\n| `cert_expiry_sweep(warn_days?, critical_days?, certs?)` | expiry buckets + renewal hints |\n| `error_rate_rca(error_rate_pct?, min_requests?, counters?)` | flagged services, dominant-code cause, vs-fleet baseline |\n| `route_conflict_analysis(routes?, services?)` | shadowed/dead routes, redirect loops |\n\nAll four analyses accept injected rows for pure offline analysis.\n\n### Writes (5) — all take `dry_run`, all capture prior state\n\n| Tool | Platform | Risk | Undo |\n|------|----------|:----:|------|\n| `set_config_value(path, value)` | caddy | medium | restore prior subtree (or delete a created path) |\n| `delete_config_path(path)` | caddy | **high** | re-create the captured subtree |\n| `load_config(config)` | caddy | **high** | re-load the snapshotted full config |\n| `set_server_state(backend, server, state)` | haproxy | medium | restore prior admin state (ready/drain/maint) |\n| `set_server_weight(backend, server, weight)` | haproxy | medium | restore prior weight (0-256) |\n\n### Undo (2)\n\n| Tool | Returns |\n|------|---------|\n| `undo_list(limit?)` | recorded undo descriptors, newest first, with their `_undo_id` |\n| `undo_apply(undo_id, dry_run?)` | replays the recorded inverse (governed like any other write) |\n\n`undo_apply` is governed like any other write (audited, capturing a before-state\nwhere the inverse is itself reversible). Undo descriptors are recorded to\n`~/.proxy-aiops/undo.db`; their params match each tool's own signature\n(replayable as-is).\n\n## Modelled API paths (mock-validated)\n\n- traefik: `/api/version`, `/api/overview`, `/api/entrypoints`,\n  `/api/http/routers[/{name}]`, `/api/http/services[/{name}]`,\n  `/api/http/middlewares`, `/api/rawdata`, `/metrics`\n- caddy: `/config/[{path}]`, `/load`, `/reverse_proxy/upstreams`\n- haproxy: `/v2/info`, `/v2/services/haproxy/configuration/{frontends|backends|servers|binds}`,\n  `/v2/services/haproxy/runtime/servers[/{name}]?backend=...`,\n  `/v2/services/haproxy/stats/native`\n\nEvery substituted path value is percent-encoded centrally; caddy config paths\nreject dot-segments.\n\nFile v0.9.2:references/cli-reference.md\n\n# proxy-aiops — CLI reference\n\nGlobal option on most commands: `--target/-t <name>` (default: first target in\nconfig).\n\n## Setup & health\n\n```bash\nproxy-aiops init                 # interactive wizard: platform, base_url, TLS verify, encrypted secret\nproxy-aiops doctor               # config + secrets + connectivity (probe per platform)\nproxy-aiops doctor --skip-auth   # skip the connectivity probe\nproxy-aiops overview             # one-shot: version + routes/services + upstream health\n```\n\n## Reads\n\n```bash\nproxy-aiops routes list [--host app.example.com]\nproxy-aiops routes show <name>              # traefik router name / caddy config path / haproxy frontend\nproxy-aiops routes find <host> [--path /]   # which routes would serve host/path\nproxy-aiops services list\nproxy-aiops services show <name>\nproxy-aiops services upstreams [--service <name>]\nproxy-aiops certs [--sweep] [--warn-days 30] [--critical-days 7] [--port 443]\nproxy-aiops config snapshot\nproxy-aiops config search <query>\nproxy-aiops config get <path>\n```\n\n## Flagship analyses\n\n```bash\nproxy-aiops analyze health [--service <name>]   # backend/upstream health RCA\nproxy-aiops analyze errors [--rate 5.0] [--min-requests 30]   # 5xx error-rate RCA\nproxy-aiops analyze conflicts                   # shadowed/dead routes, redirect loops\n```\n\n## Governed writes (dry-run + double-confirm; audited + undo-recorded)\n\n```bash\n# caddy config (teaching error on traefik/haproxy targets)\nproxy-aiops config set <path> '<json>' [--dry-run]\nproxy-aiops config delete <path> [--dry-run]        # risk=high, double-confirm\n\n# haproxy runtime servers (teaching error on traefik/caddy targets)\nproxy-aiops server state <backend> <server> ready|drain|maint [--dry-run]\nproxy-aiops server weight <backend> <server> <0-256> [--dry-run]\n```\n\nHigh-risk writes prompt for double confirmation at the CLI. Optionally export\n`PROXY_AUDIT_APPROVED_BY` (and `PROXY_AUDIT_RATIONALE`) to annotate the audit\nrow with who/why — never required.\n\n## Secrets\n\n```bash\nproxy-aiops secret set <target>      # store encrypted (hidden prompt)\nproxy-aiops secret list              # names only, never values\nproxy-aiops secret rm <target>\nproxy-aiops secret migrate           # import legacy plaintext .env\nproxy-aiops secret rotate-password   # re-encrypt under a new master password\n```\n\n## MCP server\n\n```bash\nproxy-aiops mcp        # stdio transport (or: proxy-aiops-mcp)\n```\n\n## Environment variables\n\n| Variable | Purpose |\n|----------|---------|\n| `PROXY_AIOPS_MASTER_PASSWORD` | unlock secrets.enc non-interactively (MCP/CI) |\n| `PROXY_AIOPS_CONFIG` | alternate config.yaml path (MCP server) |\n| `PROXY_AIOPS_HOME` | relocate config/audit/undo state dir |\n| `PROXY_AUDIT_APPROVED_BY` / `PROXY_AUDIT_RATIONALE` | optional approver/rationale annotations recorded on the audit row |\n| `PROXY_MAX_TOOL_CALLS` / `PROXY_MAX_TOOL_SECONDS` | per-process budget ceilings |\n| `PROXY_RUNAWAY_MAX` / `PROXY_RUNAWAY_WINDOW_SEC` | runaway circuit-breaker tuning |\n| `PROXY_<TARGET>_SECRET` | legacy plaintext fallback (deprecated) |\n\nFile v0.9.2:references/setup-guide.md\n\n# proxy-aiops — setup guide\n\n## 1. Enable each platform's API\n\n- **traefik** — expose the API: `--api=true` with a router on `api@internal`\n  (or `--api.insecure=true` in a lab, which serves it on `:8080`). For\n  error-rate analysis also enable the metrics endpoint\n  (Traefik's metrics provider serves `/metrics`).\n- **caddy** — the admin API is on `localhost:2019` by default (the `admin`\n  key in the config controls the listener). proxy-aiops needs plain HTTP\n  reachability to it; keep it bound to localhost or an internal network.\n- **haproxy** — run the **Data Plane API** sidecar (`dataplaneapi`) pointing at\n  haproxy.cfg, with a userlist user. Note the listen address (default `:5555`)\n  and the user/password.\n\n## 2. Onboard\n\n```bash\nuv tool install proxy-aiops\nproxy-aiops init\n```\n\nThe wizard asks for: target name → platform (`traefik` / `caddy` / `haproxy`)\n→ API base URL (per-platform default offered) → TLS verification (default ON;\nanswer No only for self-signed lab certs) → credentials:\n\n- **haproxy**: Data Plane API username + password (password stored encrypted —\n  required).\n- **traefik / caddy**: optional Basic-auth username/password — leave both\n  empty for the common unauthenticated-localhost case (no store entry means no\n  auth header is sent).\n\n## 3. Verify\n\n```bash\nproxy-aiops doctor\n```\n\nDoctor checks config, the encrypted store (and its permissions), per-target\nsecrets (respecting which platforms need one), then probes each target's cheap\nhealth/info endpoint: traefik `/api/version`, caddy `/config/`, haproxy\n`/v2/info`.\n\n## 4. Wire up an MCP client\n\n```json\n{\n  \"mcpServers\": {\n    \"proxy-aiops\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"proxy-aiops\", \"proxy-aiops-mcp\"],\n      \"env\": { \"PROXY_AIOPS_MASTER_PASSWORD\": \"your-master-password\" }\n    }\n  }\n}\n```\n\nMCP clients do not inherit your shell profile: set\n`PROXY_AIOPS_MASTER_PASSWORD` in the `env` block whenever any target has a\nstored secret, and `PROXY_AIOPS_CONFIG` / `PROXY_AIOPS_HOME` if you relocated\nstate.\n\n## Config file\n\n`~/.proxy-aiops/config.yaml`:\n\n```yaml\ntargets:\n  - name: edge1\n    platform: traefik\n    base_url: http://192.0.2.10:8080\n    verify_ssl: true\n  - name: caddy1\n    platform: caddy\n    base_url: http://127.0.0.1:2019\n  - name: lb1\n    platform: haproxy\n    base_url: http://192.0.2.20:5555\n    username: dpapi\n```\n\nSecrets never live here — only in `secrets.enc` (or the deprecated\n`PROXY_<TARGET>_SECRET` env fallback).\n\n## Troubleshooting\n\n- **401/403** — haproxy: wrong Data Plane API user/password; traefik/caddy: a\n  Basic-auth layer is in front (store a secret) or a stale secret is stored\n  (remove it with `proxy-aiops secret rm <target>`).\n- **404 on every call** — the API is not enabled (traefik `api@internal`\n  router missing; caddy admin listener disabled; dataplaneapi not running).\n- **Connection refused** — check `base_url` (scheme + port) and that the\n  endpoint is bound beyond localhost if proxy-aiops runs on another host.\n- **cert sweep returns unknowns** — the probe needs TCP reach to each domain\n  on the TLS port (default 443, max 25 domains, 5s each).\n\nFile v0.9.2:skill-card.md\n\n## Description:\n\nProxy AIops helps agents inspect and operate Traefik, Caddy, and HAProxy reverse proxies for routes, upstream health, TLS certificate checks, 5xx analysis, config lookup, and governed Caddy or HAProxy writes.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[zw008](https://clawhub.ai/user/zw008)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operations engineers use this skill to diagnose and operate self-hosted Traefik, Caddy, and HAProxy edges, including route matching, upstream health, TLS expiry, 5xx RCA, and controlled proxy changes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The release combines live reverse-proxy write authority, persistent credentials, and an unpinned runtime package, and the security verdict is suspicious.\n\nMitigation: Install only after pinning the executable package to a reviewed version or digest and reviewing the release before use.\n\nRisk: Caddy config replacement or deletion and HAProxy drain, readiness, maintenance, or weight changes can affect production traffic.\n\nMitigation: Run with least-privilege proxy accounts, prefer read-only credentials for routine diagnostics, use dry runs where available, and require external approval controls for production-impacting writes.\n\nRisk: Proxy credentials and the master password unlock operational access to live infrastructure.\n\nMitigation: Avoid placing production master passwords directly in MCP JSON configuration and protect the local proxy-aiops state directory with strict permissions.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/zw008/skills/proxy-aiops)\n- [Project homepage](https://github.com/AIops-tools/Proxy-AIops)\n- [Capabilities reference](references/capabilities.md)\n- [CLI reference](references/cli-reference.md)\n- [Setup guide](references/setup-guide.md)\n- [Agent guardrails](references/agent-guardrails.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown with inline shell commands, configuration snippets, and operational findings]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include proxy observations, RCA findings, dry-run guidance, and audit or undo follow-up steps.]\n\n## Skill Version(s):\n\n0.9.2 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.9.1: 7 files, 18476 bytes\n\nFiles: references/agent-guardrails.md (7072b), references/capabilities.md (5569b), references/cli-reference.md (3069b), references/setup-guide.md (3153b), skill-card.md (2738b), SKILL.md (17445b), _meta.json (130b)\n\nFile v0.9.1:SKILL.md\n\n---\nname: proxy-aiops\nslug: proxy-aiops\ndisplayName: \"Proxy AIops\"\nsummary: \"Governed Traefik + Caddy + HAProxy ops: routes, upstreams, certs, 5xx RCA. 28 tools.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxy-AIops\ntags: [aiops, mcp, governance, proxy]\ndescription: >\n  Use this skill whenever the user needs to operate a Traefik, Caddy or HAProxy reverse proxy / load balancer — a one-shot overview, routes (routers / caddy routes / frontends) with host/path matching, services and server-level upstream health, middlewares, TLS certificate inventory with an expiry sweep, traffic and 5xx error counters, config snapshot/search, four flagship RCAs (backend health, cert expiry, error rate, route conflicts), and governed writes (caddy config set/delete/load with prior-config capture; haproxy server drain/maint/ready and weight).\n  Always use this skill for \"Traefik\", \"Caddy\", \"HAProxy\", \"reverse proxy\", \"load balancer\", \"upstream down\", \"502/503/504 errors\", \"bad gateway\", \"cert expiring\", \"TLS certificate\", \"route not matching\", \"which route serves this host\", \"drain a server\", \"server weight\", \"redirect loop\" when the context is a Traefik/Caddy/HAProxy edge.\n  Do NOT use when the target is something other than a Traefik/Caddy/HAProxy proxy (a hypervisor, storage appliance, backup product, container-orchestration cluster, multi-vendor router/switch config, or OT/industrial equipment) — route those to the appropriate other AIops-tools skill. Do NOT use for firewall rules — use firewall-aiops. Managed cloud load balancers are out of scope.\n  Governed proxy operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers). Behaviour is validated by a mock-based test suite; see docs/VERIFICATION.md for the live-verification checklist.\ninstaller:\n  kind: uv\n  package: proxy-aiops\nargument-hint: \"[a route/service/backend name, a hostname, or describe your proxy task]\"\nallowed-tools:\n  - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"proxy-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"PROXY_AIOPS_CONFIG\",\"PROXY_AIOPS_MASTER_PASSWORD\"]},\"homepage\":\"https://github.com/AIops-tools/Proxy-AIops\",\"emoji\":\"🔀\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n  Standalone, self-governed reverse-proxy operations across Traefik (API /api/..., metrics-text counters via /metrics), Caddy (admin API, default localhost:2019 — carries the write surface) and HAProxy (Data Plane API v2 /v2/..., HTTP Basic auth). Each target in the config names its own platform, and a name-keyed platform registry selects the API shape; an explicit support matrix raises teaching errors for ops a platform cannot do (traefik writes → its providers; caddy error counters → access logs; haproxy certs → the .pem pipeline), never a silent no-op. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency.\n  All write operations are audited to a local SQLite DB under ~/.proxy-aiops/ (relocatable via PROXY_AIOPS_HOME).\n  Credentials: the HAProxy Data Plane API password (required) or an optional Basic-auth credential for Traefik/Caddy is stored ENCRYPTED in ~/.proxy-aiops/secrets.enc (Fernet/AES-128 + scrypt-derived key) — never plaintext on disk. Traefik and Caddy usually run unauthenticated on localhost, so their secret is optional (no store entry = no auth header). Run 'proxy-aiops init' to onboard (it asks for the platform), or 'proxy-aiops secret set <target>'. The store is unlocked by a master password from PROXY_AIOPS_MASTER_PASSWORD (non-interactive/MCP/CI) or an interactive prompt (CLI on a TTY). A legacy plaintext env var PROXY_<TARGET_NAME_UPPER>_SECRET is still honoured as a fallback with a deprecation warning (migrate with 'proxy-aiops secret migrate'). Secrets are never logged or echoed.\n  State-changing operations pass through the @governed_tool decorator (budget guard + audit + risk-tier labelling). delete_config_path and load_config (full config replace) are risk=high with dry_run + double confirmation at the CLI. Reversible writes (set_config_value, delete_config_path, load_config, set_server_state, set_server_weight) capture the real fetched before-state and record an inverse undo descriptor whose params replay against the tool's own signature.\n  Webhooks: none — no outbound network calls beyond the configured proxy APIs, plus (only when the operator runs the cert sweep with probing) a bounded TLS handshake per inventoried domain.\n  SSL: verify_ssl defaults to true; disable only for self-signed lab certs.\n  Transitive dependencies: httpx (HTTP client), cryptography (secret store + cert parsing), and the MCP SDK. No post-install scripts or background services.\n---\n\n# Proxy AIops\n\n> **Disclaimer**: Community-maintained open-source project, **not affiliated with, endorsed by, or sponsored by Traefik Labs, the Caddy project, HAProxy Technologies, or the HAProxy project.** Traefik, Caddy and HAProxy are trademarks of their respective owners. Source at [github.com/AIops-tools/Proxy-AIops](https://github.com/AIops-tools/Proxy-AIops) under the MIT license.\n\nGoverned reverse-proxy operations — **28 MCP tools** across **Traefik** (API +\n`/metrics`), **Caddy** (admin API) and **HAProxy** (Data Plane API v2), every\none wrapped with the bundled `@governed_tool` harness: a local unified audit\nlog under `~/.proxy-aiops/`, policy engine, token/runaway budget guard,\nundo-token recording, and descriptive risk tiers. A per-target\n`platform` field selects the API shape, so the same tools work on all three\nproxies and one config can span a mixed edge. An explicit **support matrix**\nraises teaching errors for ops a platform cannot do — never a silent no-op.\nCredentials are stored **encrypted** (`~/.proxy-aiops/secrets.enc`, Fernet +\nscrypt) — never plaintext on disk; Traefik/Caddy secrets are optional\n(unauthenticated localhost is the common case).\n\n> **Standalone**: the governance harness is bundled in the package\n> (`proxy_aiops.governance`) — no external skill-family dependency. Behaviour is\n> covered by a mock-based test suite; `docs/VERIFICATION.md` is the checklist for a\n> live run (all three platforms are free/self-hostable, so a small lab is enough).\n\n## What This Skill Does\n\n| Group | Tools | Count | R/W |\n|-------|-------|:-----:|:---:|\n| **Status** | proxy_overview, version_info, list_entrypoints | 3 | read |\n| **Routes** | list_routes, route_detail, find_route | 3 | read |\n| **Services** | list_services, service_detail, list_upstreams, upstream_detail, list_middlewares | 5 | read |\n| **Certificates** | list_certificates | 1 | read |\n| **Traffic** | traffic_stats, error_counters | 2 | read |\n| **Config** | config_snapshot, search_config, get_config_value | 3 | read |\n| **Flagship analyses** | backend_health_rca, cert_expiry_sweep, error_rate_rca, route_conflict_analysis | 4 | read |\n| **Writes (caddy)** | set_config_value (med), delete_config_path (**high**), load_config (**high**) | 3 | write |\n| **Writes (haproxy)** | set_server_state, set_server_weight | 2 | write (med) |\n| **Undo** | undo_list, undo_apply | 2 | read / write |\n\nThe four flagship analyses are transparent heuristics that report their\nnumbers, never a black-box verdict: `backend_health_rca` groups down upstreams\nper service and maps the health-check failure class (connection refused / L4\ntimeout / TLS / L7 / DNS / maint) to a cause + action; `cert_expiry_sweep`\nbuckets certs by days-to-expiry with per-platform renewal hints;\n`error_rate_rca` ranks services by 5xx share vs the fleet baseline and maps\nthe dominant code (502/503/504/500) to a cause; `route_conflict_analysis`\nfinds shadowed routes, dead routes, and redirect loops.\n\n## Quick Install\n\n```bash\nuv tool install proxy-aiops\nproxy-aiops init       # wizard: pick platform (traefik/caddy/haproxy) + optional encrypted secret\nproxy-aiops doctor\n```\n\nOr as an OpenClaw plugin, which installs this skill and its MCP server together:\n\n```bash\nopenclaw plugins install clawhub:@aiops-tools/proxy-aiops\nopenclaw skills info proxy-aiops          # expect: Visible to model: yes\n```\n\nNeeds `uvx` on `PATH`: the MCP server is fetched with uv, pinned to this release.\n\n## When to Use This Skill\n\n- Get a one-shot snapshot (`overview` / `version_info` / `list_entrypoints`)\n- Investigate 502/503/504 spikes (`error_rate_rca`) → dominant code → cause\n- Find why an upstream/backend is down (`list_upstreams`, `backend_health_rca`)\n- Sweep TLS cert expiry across the edge (`certs --sweep` / `cert_expiry_sweep`)\n- Audit routing hygiene (`route_conflict_analysis` — shadowed/dead routes,\n  redirect loops) and answer \"which route serves this host?\" (`find_route`)\n- Safely drain/return an haproxy server (`set_server_state`, reversible +\n  undo-recorded) or adjust its weight (`set_server_weight`)\n- Safely edit caddy config (`set_config_value` / `delete_config_path` /\n  `load_config` — prior config captured, undo replays the restore)\n\n**Do NOT use when** the target is not a Traefik/Caddy/HAProxy proxy — route\nhypervisor, storage, backup, cluster, network-device, or OT/industrial work to\nthe appropriate other AIops-tools skill. Do NOT use for firewall rules — use\nfirewall-aiops.\n\n## Related Skills — Skill Routing\n\n| If the user wants… | Use |\n|--------------------|-----|\n| Traefik / Caddy / HAProxy proxy ops | **proxy-aiops** (this skill) |\n| Firewall rules / NAT / gateway health | **firewall-aiops** |\n| A non-proxy platform (hypervisor, storage, backup, cluster, network devices, OT edge) | the appropriate **other AIops-tools** skill |\n| Managed cloud load balancers | out of scope for this tool |\n\n## Common Workflows\n\n### 1. A 5xx spike — is it the app or the backend?\n\n1. `proxy-aiops doctor` → confirm the proxy's API is reachable before you trust any\n   number that follows.\n2. `proxy-aiops overview` → the one-shot picture: platform/version, entrypoints, and\n   route/service counts, so you know the blast radius.\n3. `proxy-aiops analyze errors --rate 5 --min-requests 100` → services ranked by 5xx\n   share against the fleet baseline, with the **dominant status code mapped to a cause**\n   (503 no upstream available / 502 connection failed / 504 timeout / 500 app error).\n   The `--min-requests` floor keeps a single failed request on a quiet service from\n   outranking a real incident.\n4. `proxy-aiops analyze health --service <name>` → the same service from the backend\n   side: which servers are failing their health check and what class of failure it is.\n   If the servers are healthy, the 5xx is coming from **the application**, and no amount\n   of proxy work will fix it — hand it off.\n5. If one server is the problem, take it out of rotation gracefully:\n   `proxy-aiops services upstreams <backend>` to get the exact server name, then\n   `proxy-aiops server state <backend> <server> drain --dry-run` and re-run for real\n   (double-confirm; the prior state is captured as the undo descriptor). `drain` lets\n   in-flight connections finish — reach for `maint` only when you need it out *now*.\n6. Re-run `proxy-aiops analyze errors` to confirm the rate dropped.\n7. **Failure branch**: if draining one server just moves the load onto the next one to\n   fall over, you are shedding capacity you do not have — put it straight back with\n   `proxy-aiops undo list` → `undo apply <id>` (restores the **prior** state, not a\n   hardcoded `ready`) before you drain a second. Note `server state` / `server weight`\n   are **haproxy runtime** operations; on a traefik or caddy target the tool raises a\n   teaching error naming the right mechanism rather than silently doing nothing.\n\n### 2. Certificates about to expire\n\n1. `proxy-aiops certs --sweep --warn-days 30 --critical-days 7` → the TLS domain\n   inventory with each cert **live-probed** on port 443 and bucketed\n   expired / critical / warning, plus a renewal hint.\n2. `proxy-aiops certs --sweep --port 8443` for any entrypoint not on 443 —\n   the sweep probes one port at a time, so a non-standard listener needs its own pass.\n3. `proxy-aiops overview` and `proxy-aiops routes list` → map each expiring domain back\n   to the routes that actually serve it, so you renew what is in use and ignore what is\n   not.\n4. Renew through the platform's own mechanism (ACME for traefik/caddy), then re-run the\n   sweep to confirm the new expiry date.\n5. **Failure branch**: on a **haproxy** target the sweep returns a teaching note rather\n   than results — haproxy serves certs from `.pem` files on disk, outside this tool's\n   API surface, so check those with your file-level tooling. If a probe fails to connect,\n   distinguish \"cert is bad\" from \"port is closed\" with\n   `proxy-aiops routes find <host>` before assuming a certificate problem.\n\n### 3. \"Why is this hostname hitting the wrong backend?\"\n\n1. `proxy-aiops routes find <host> --path /api` → best-matching routes, most specific\n   first. This is the direct answer to \"who serves this request\".\n2. `proxy-aiops routes show <route-id>` → the full rule, priority, middlewares, and the\n   service it points at.\n3. `proxy-aiops analyze conflicts` → **shadowed** routes (fully covered by an earlier or\n   higher-priority route), **dead** routes (the service is missing, or has zero servers\n   up), and redirect loops — each finding names the covering route or the missing\n   service rather than just flagging a number.\n4. `proxy-aiops services show <service>` and `proxy-aiops services upstreams <service>`\n   → confirm the service the route resolves to actually has healthy servers behind it.\n5. Fix the ordering/priority at its source: on **caddy** via `proxy-aiops config set`\n   (recipe 4); on **traefik**, in the provider that generated the route (labels, file\n   provider, CRD) — traefik's API is read-only, and the tool says so explicitly instead\n   of pretending to write.\n6. **Failure branch**: if `routes find` returns nothing, the request is not matching any\n   route at all — check `proxy-aiops overview` for the entrypoints and confirm the\n   listener you think you are hitting exists. A \"dead route\" finding whose service is\n   missing usually means a config was applied referencing a service that was never\n   created; fixing the route without creating the service just moves the 404.\n\n### 4. Edit a caddy config subtree, reversibly\n\n1. `proxy-aiops config snapshot` → the whole current config; take this **before** you\n   change anything, so you have an out-of-band copy independent of the undo store.\n2. `proxy-aiops config search <needle>` → locate the config path holding the value you\n   want (searching beats guessing at caddy's nested JSON paths).\n3. `proxy-aiops config get <path>` → read the exact current subtree you are about to\n   replace.\n4. `proxy-aiops config set <path> '<json>' --dry-run` → preview the write.\n5. Re-run without `--dry-run` (double-confirm) — the prior subtree is fetched and\n   captured, and an inverse undo descriptor is recorded with an `_undo_id`.\n6. Validate: `proxy-aiops routes list`, `proxy-aiops analyze conflicts`, and\n   `proxy-aiops analyze errors` → confirm the edit did what you meant and did not\n   shadow an existing route.\n7. **Failure branch**: `proxy-aiops undo list` → `undo apply <id>` restores the captured\n   subtree exactly. If the config is too broken for a targeted undo, the\n   `config snapshot` from step 1 is your fallback via `load_config` — but note\n   `load_config` and `config delete` are **risk=high** with `--dry-run` + double\n   confirmation at the CLI. `load_config` replaces the *entire* config, so it is a\n   last resort, not a first instinct.\n\n## Governance & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide\nwhether a write is permitted. That is your agent's judgement, or the permission\nof the account you connect it with (a read-only HAProxy Data Plane API role, a\nscoped Traefik/Caddy admin API — writes then fail at the server). There is no\nread-only switch, policy file, or approval gate.\n\n- **Audit is the guarantee, and it is not bypassable.** Every operation — MCP and CLI alike — is logged to `~/.proxy-aiops/audit.db` (relocatable via `PROXY_AIOPS_HOME`): params (secrets redacted), result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- `PROXY_AUDIT_APPROVED_BY` / `PROXY_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Runaway guard** — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with `PROXY_RUNAWAY_MAX=0`.\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI; CLI writes execute through the same governed tools, so they are audited + undo-recorded.\n- Reversible writes capture the real fetched before-state and record an inverse descriptor that replays against the tool's own signature.\n- Traefik targets accept no writes at all — the support matrix teaches you to\n  edit the provider source instead.\n\n## References\n\n- `references/capabilities.md` — full tool + platform + API-path reference\n- `references/cli-reference.md` — CLI command reference\n- `references/setup-guide.md` — onboarding, credentials, and connectivity\n- `docs/VERIFICATION.md` — live-verification checklist (what the mock suite covers, and what a real-proxy run must prove)\n\nFile v0.9.1:_meta.json\n\n{\n  \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n  \"slug\": \"proxy-aiops\",\n  \"version\": \"0.9.1\",\n  \"publishedAt\": 1789208721396\n}\n\nFile v0.9.1:references/agent-guardrails.md\n\n# Agent guardrails — running proxy-aiops with a smaller / local model\n\nIf you drive these tools with a local model (Llama, Qwen, Mistral … via Goose,\nOllama, LM Studio, or any OpenAI-compatible runtime), you will get noticeably\nbetter results with a short system prompt. This page gives you one, and — more\nimportantly — tells you which guardrails you **no longer need to write**, because\nthe tool now enforces them itself.\n\nThe distinction matters. A guardrail in a prompt is a request. A guardrail in the\nharness is a guarantee. Anything below that we could move into the harness, we did.\n\n## Authorization is not this tool's job — decide it where it belongs\n\nWhether a write should happen is your decision, or the account's. The tool does\nnot gate it — there is no read-only switch and no approval prompt to configure.\nThe two right places to control read vs write:\n\n- **The account you connect with.** Give the HAProxy Data Plane API a read-only\n  role, or point the tool at a Traefik/Caddy admin API you have scoped down. A\n  write then fails at the server, which is the only place the permission actually\n  lives — a revoked permission cannot be argued around by a model, but a skill-side\n  flag can.\n- **Your agent's system prompt.** If you want an observe-only session, tell the\n  model not to call the write tools (they are clearly tagged `[WRITE]`).\n\nWhat the tool *does* guarantee is that you can always see what happened:\n\n## What the tool enforces — do not waste prompt budget on these\n\n| You might be tempted to prompt | Why you don't need to |\n|---|---|\n| \"Don't invent a value when a field is missing\" | Traefik, Caddy and HAProxy express the same concepts differently, so a field one platform has and another does not comes back as `null`, never as `\"\"`. A Caddy route's `raw` rule string is `null` — Caddy matches on a match list and has no such string — rather than a misleading empty rule. |\n| \"Tell me if the output was cut off\" | `search_config`, `traffic_stats` and `error_counters` return `{\"matches\"/\"services\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}` — one convention across the repo. Truncation is measured (the config walk deliberately overshoots by one) and not guessed from the count reaching the cap. |\n| \"Preserve the ordering / tell me what's most urgent\" | `backend_health_rca`, `error_rate_rca`, `route_conflict_analysis` and `cert_expiry_sweep` rank findings worst-first with the measured number attached. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | `delete_config_path` and `load_config` require a `--dry-run`-able preview plus double confirmation at the CLI. Config writes capture the prior value so the undo token can restore it. |\n| \"Log what you did\" | Every governed call is audited to `~/.proxy-aiops/audit.db` regardless of what the model says it did — and the CLI writes the same row the MCP path does, so there is no unaudited entry point. |\n| \"Don't get stuck retrying\" | The runaway guard trips a circuit breaker if the same call is hammered in a tight loop — a stuck agent is stopped rather than left to burn calls and time. |\n\n## What still needs a prompt\n\nThese are model-behaviour problems the harness cannot fix from the outside.\nCopy this into your agent's system prompt:\n\n```text\nYou operate a Traefik, Caddy or HAProxy reverse proxy through the proxy-aiops\nMCP tools.\n\nTOOL USE\n- Before answering any question about the current proxy, you MUST call a tool.\n  Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n  emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n  a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n  field that is true, say so and narrow the query instead of treating the\n  partial result as complete.\n- A null field means this platform does not express that concept, or did not\n  report it. Report it as \"not available\" — never infer it.\n- An \"unsupported\" field is a capability statement about the platform, not an\n  error and not a finding. Say the platform does not expose it; do not report\n  it as a problem with the proxy.\n- Report values exactly\n\nArchive v0.9.0: 7 files, 18532 bytes\n\nFiles: references/agent-guardrails.md (7072b), references/capabilities.md (5569b), references/cli-reference.md (3069b), references/setup-guide.md (3153b), skill-card.md (3141b), SKILL.md (17135b), _meta.json (130b)\n\nArchive v0.8.0: 7 files, 18200 bytes\n\nFiles: references/agent-guardrails.md (7072b), references/capabilities.md (5569b), references/cli-reference.md (3069b), references/setup-guide.md (3153b), skill-card.md (2314b), SKILL.md (17248b), _meta.json (130b)\n\nArchive v0.7.0: 7 files, 18416 bytes\n\nFiles: references/agent-guardrails.md (7072b), references/capabilities.md (5569b), references/cli-reference.md (3069b), references/setup-guide.md (3153b), skill-card.md (2834b), SKILL.md (17248b), _meta.json (130b)\n\nArchive v0.6.0: 7 files, 18498 bytes\n\nFiles: references/agent-guardrails.md (7072b), references/capabilities.md (5569b), references/cli-reference.md (3069b), references/setup-guide.md (3153b), skill-card.md (3281b), SKILL.md (17248b), _meta.json (130b)\n\nArchive v0.5.0: 7 files, 18236 bytes\n\nFiles: references/agent-guardrails.md (7072b), references/capabilities.md (5569b), references/cli-reference.md (3069b), references/setup-guide.md (3153b), skill-card.md (2427b), SKILL.md (17248b), _meta.json (130b)\n\nArchive v0.4.0: 7 files, 17973 bytes\n\nFiles: references/agent-guardrails.md (6362b), references/capabilities.md (5534b), references/cli-reference.md (2957b), references/setup-guide.md (3371b), skill-card.md (3058b), SKILL.md (16717b), _meta.json (130b)","readmeExcerpt":"Skill: proxy-aiops Owner: zw008 Summary: Use this skill whenever the user needs to operate a Traefik, Caddy or HAProxy reverse proxy / load balancer — a one-shot overview, routes (routers / caddy routes / frontends) with host/path matching, services and server-level upstream health, middlewares, TLS certificate inventory with an expiry sweep, traffic and 5xx error counters, config snapshot/search, four flagship RCAs ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"uv tool install proxy-aiops\nproxy-aiops init       # wizard: pick platform (traefik/caddy/haproxy) + optional encrypted secret\nproxy-aiops doctor"},{"language":"bash","snippet":"openclaw plugins install clawhub:@zw008/proxy-aiops\nopenclaw skills info proxy-aiops          # expect: Visible to model: yes"},{"language":"text","snippet":"You operate a Traefik, Caddy or HAProxy reverse proxy through the proxy-aiops\nMCP tools.\n\nTOOL USE\n- Before answering any question about the current proxy, you MUST call a tool.\n  Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n  emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n  a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n  field that is true, say so and narrow the query instead of treating the\n  partial result as complete.\n- `backend_health_rca` findings and `route_conflict_analysis` results are not ordered by\n  severity — the latter is in the proxy's match order. Weigh `backend_health_rca` findings on\n  their own `serversTotal`/`up`/`down`/`maint` counts. `route_conflict_analysis` results carry\n  no number at all — read `shadowedBy`, `reason` or `chain` and say which one you acted on.\n- A null field means this platform does not express that concept, or did not\n  report it. Report it as \"not available\" — never infer it.\n- An \"unsupported\" field is a capability statement about the platform, not an\n  error and not a finding. Say the platform does not expose it; do not report\n  it as a problem with the proxy.\n- Report values exactly as returned. Traffic counters are cumulative since the\n  proxy started — compare rates, never quote a raw total as \"requests today\".\n\nSCOPE\n- Separate observation from interpretation. State what the tools returned, then\n  any interpretation, clearly marked as such.\n- Do not claim a backend is down unless a health/upstream result says so. A\n  route existing does not mean it resolves.\n- Do not confuse a route with a service, a service with an upstream server, or\n  an entrypoint with a route. One route names one service; one service has many\n  upstream servers.\n- The three platforms differ. The target's platf"},{"language":"bash","snippet":"# e.g. give the HAProxy Data Plane API a read-only role, or point the tool at a\n# Traefik/Caddy admin API you have scoped down. Then:\nproxy-aiops doctor"},{"language":"bash","snippet":"export PROXY_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport PROXY_AUDIT_RATIONALE=\"draining web-02 for maintenance\""},{"language":"bash","snippet":"proxy-aiops init                 # interactive wizard: platform, base_url, TLS verify, encrypted secret\nproxy-aiops doctor               # config + secrets + connectivity (probe per platform)\nproxy-aiops doctor --skip-auth   # skip the connectivity probe\nproxy-aiops overview             # one-shot: version + routes/services + upstream health"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: proxy-aiops\nslug: proxy-aiops\ndisplayName: \"Proxy AIops\"\nsummary: \"Governed Traefik + Caddy + HAProxy ops: routes, upstreams, certs, 5xx RCA. 28 tools.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxy-AIops\ntags: [aiops, mcp, governance, proxy]\ndescription: >\n  Use this skill whenever the user needs to operate a Traefik, Caddy or HAProxy reverse proxy / load balancer — a one-shot overview, routes (routers / caddy routes / frontends) with host/path matching, services and server-level upstream health, middlewares, TLS certificate inventory with an expiry sweep, traffic and 5xx error counters, config snapshot/search, four flagship RCAs (backend health, cert expiry, error rate, route conflicts), and governed writes (caddy config set/delete/load with prior-config capture; haproxy server drain/maint/ready and weight).\n  Always use this skill for \"Traefik\", \"Caddy\", \"HAProxy\", \"reverse proxy\", \"load balancer\", \"upstream down\", \"502/503/504 errors\", \"bad gateway\", \"cert expiring\", \"TLS certificate\", \"route not matching\", \"which route serves this host\", \"drain a server\", \"server weight\", \"redirect loop\" when the context is a Traefik/Caddy/HAProxy edge.\n  Do NOT use when the target is something other than a Traefik/Caddy/HAProxy proxy (a hypervisor, storage appliance, backup product, container-orchestration cluster, multi-vendor router/switch config, or OT/industrial equipment) — route those to the appropriate other AIops-tools skill. Do NOT use for firewall rules — use firewall-aiops. Managed cloud load balancers are out of scope.\n  Governed proxy operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers). Behaviour is validated by a mock-based test suite; see docs/VERIFICATION.md for the live-verification checklist.\ninstaller:\n  kind: uv\n  package: proxy-aiops\nargument-hint: \"[a route/service/backend name, a hostname, or describe your proxy task]\"\nallowed-tools:\n  - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"proxy-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"PROXY_AIOPS_CONFIG\",\"PROXY_AIOPS_MASTER_PASSWORD\"]},\"homepage\":\"https://github.com/AIops-tools/Proxy-AIops\",\"emoji\":\"🔀\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n  Standalone, self-governed reverse-proxy operations across Traefik (API /api/..., metrics-text counters via /metrics), Caddy (admin API, default localhost:2019 — carries the write surface) and HAProxy (Data Plane API v2 /v2/..., HTTP Basic auth). Each target in the config names its own platform, and a name-keyed platform registry selects the API shape; an explicit support matrix raises teaching errors for ops a platform cannot do (traefik writes → its providers; caddy error counters → access logs; haproxy certs → the .pem pipeline), never a silent no-op. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency.\n  All write operations are audited to a local SQLite DB under ~/.proxy-aiops/ (relocatable"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n  \"slug\": \"proxy-aiops\",\n  \"version\": \"0.9.4\",\n  \"publishedAt\": 1789601191173\n}"},{"path":"references/agent-guardrails.md","content":"# Agent guardrails — running proxy-aiops with a smaller / local model\n\nIf you drive these tools with a local model (Llama, Qwen, Mistral … via Goose,\nOllama, LM Studio, or any OpenAI-compatible runtime), you will get noticeably\nbetter results with a short system prompt. This page gives you one, and — more\nimportantly — tells you which guardrails you **no longer need to write**, because\nthe tool now enforces them itself.\n\nThe distinction matters. A guardrail in a prompt is a request. A guardrail in the\nharness is a guarantee. Anything below that we could move into the harness, we did.\n\n## Authorization is not this tool's job — decide it where it belongs\n\nWhether a write should happen is your decision, or the account's. The tool does\nnot gate it — there is no read-only switch and no approval prompt to configure.\nThe two right places to control read vs write:\n\n- **The account you connect with.** Give the HAProxy Data Plane API a read-only\n  role, or point the tool at a Traefik/Caddy admin API you have scoped down. A\n  write then fails at the server, which is the only place the permission actually\n  lives — a revoked permission cannot be argued around by a model, but a skill-side\n  flag can.\n- **Your agent's system prompt.** If you want an observe-only session, tell the\n  model not to call the write tools (they are clearly tagged `[WRITE]`).\n\nWhat the tool *does* guarantee is that you can always see what happened:\n\n## What the tool enforces — do not waste prompt budget on these\n\n| You might be tempted to prompt | Why you don't need to |\n|---|---|\n| \"Don't invent a value when a field is missing\" | Traefik, Caddy and HAProxy express the same concepts differently, so a field one platform has and another does not comes back as `null`, never as `\"\"`. A Caddy route's `raw` rule string is `null` — Caddy matches on a match list and has no such string — rather than a misleading empty rule. |\n| \"Tell me if the output was cut off\" | `search_config`, `traffic_stats` and `error_counters` return `{\"matches\"/\"services\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}` — one convention across the repo. Truncation is measured (the config walk deliberately overshoots by one) and not guessed from the count reaching the cap. |\n| \"Make it show the number it judged on\" | `error_rate_rca` returns `errorRatePct`, `vsBaselineX` against the fleet baseline and a `severity` of `critical`/`warning` on every flagged service; `cert_expiry_sweep` returns `daysToExpiry` and a `bucket` per certificate, and orders by `daysToExpiry`. Both orderings are therefore checkable from the payload itself. |\n| \"Confirm before anything destructive\" | `delete_config_path` and `load_config` require a `--dry-run`-able preview plus double confirmation at the CLI. Config writes capture the prior value so the undo token can restore it. |\n| \"Log what you did\" | Every governed call is audited to `~/.proxy-aiops/audit.db` regardless of what the model says it did — and the CLI writes the same ro"},{"path":"references/capabilities.md","content":"# proxy-aiops — capabilities reference\n\n## Platforms\n\n| Platform | API | Auth | Default base_url |\n|----------|-----|------|------------------|\n| `traefik` | Traefik API (`/api/...`) + `/metrics` text | none, or optional HTTP Basic (username + stored secret) | `http://localhost:8080` |\n| `caddy` | Admin API (`/config/`, `/load`, `/reverse_proxy/upstreams`) | none, or optional HTTP Basic | `http://localhost:2019` |\n| `haproxy` | Data Plane API v2 (`/v2/...`) | HTTP Basic (username + stored secret, **required**) | `http://localhost:5555` |\n\nA per-target `platform` field selects the shape; the ops/CLI/MCP layers are\nplatform-neutral. Unsupported ops raise **teaching errors** (what to use\ninstead), never silent empties.\n\n## Support matrix\n\n| Capability | traefik | caddy | haproxy |\n|------------|:-------:|:-----:|:-------:|\n| version_info | ✅ `/api/version` | teaching note (no version endpoint) | ✅ `/v2/info` |\n| list_entrypoints | ✅ `/api/entrypoints` | ✅ server listen addresses | ✅ frontends |\n| list_routes / route_detail / find_route | ✅ routers (rule parsed) | ✅ routes (name = config path) | ✅ frontends (ACLs not parsed) |\n| list_services / service_detail | ✅ services + serverStatus | ✅ reverse_proxy routes + upstreams | ✅ backends + stats |\n| list_upstreams / upstream_detail | ✅ serverStatus map | ✅ `/reverse_proxy/upstreams` (fails→down) | ✅ stats server rows (status + check_status) |\n| list_middlewares | ✅ | teaching (inline handlers) | teaching (haproxy.cfg) |\n| list_certificates / cert_expiry_sweep | ✅ TLS routers + tls.domains | ✅ TLS listeners + automation subjects | teaching (.pem files) |\n| traffic_stats / error_counters | ✅ `/metrics` per-code | teaching (no per-route counters) | ✅ stats (`req_tot`, `hrsp_*`) |\n| config_snapshot / search_config | ✅ `/api/rawdata` (read-only) | ✅ `/config/` | teaching |\n| get/set_config_value, delete_config_path, load_config | teaching (edit the provider) | ✅ (the write surface) | teaching (use runtime writes) |\n| set_server_state / set_server_weight | teaching (provider) | teaching (config tree) | ✅ runtime servers |\n\n## MCP tools (28)\n\n### Reads (21)\n\n| Tool | Returns |\n|------|---------|\n| `proxy_overview` | platform/version + route/service counts + upstream up/down |\n| `version_info` | version/build info |\n| `list_entrypoints` | listeners: {name, address} |\n| `list_routes(host?)` | normalised routes: {name, hosts, paths, priority, service, tls, enabled, redirectTo} |\n| `route_detail(name)` | one route's full detail |\n| `find_route(host, path)` | routes that would serve a host/path, best first |\n| `list_services` | services/backends: {name, serversTotal, serversUp} |\n| `service_detail(name)` | one service's detail (+ haproxy servers) |\n| `list_upstreams(service?)` | server rows: {service, server, address, status up/down/maint/drain, checkInfo, weight} |\n| `upstream_detail(service, server)` | one server row |\n| `list_middlewares` | traefik middlewares (teaching elsewhere) |\n| `list_certificates(probe?,"},{"path":"references/cli-reference.md","content":"# proxy-aiops — CLI reference\n\nGlobal option on most commands: `--target/-t <name>` (default: first target in\nconfig).\n\n## Setup & health\n\n```bash\nproxy-aiops init                 # interactive wizard: platform, base_url, TLS verify, encrypted secret\nproxy-aiops doctor               # config + secrets + connectivity (probe per platform)\nproxy-aiops doctor --skip-auth   # skip the connectivity probe\nproxy-aiops overview             # one-shot: version + routes/services + upstream health\n```\n\n## Reads\n\n```bash\nproxy-aiops routes list [--host app.example.com]\nproxy-aiops routes show <name>              # traefik router name / caddy config path / haproxy frontend\nproxy-aiops routes find <host> [--path /]   # which routes would serve host/path\nproxy-aiops services list\nproxy-aiops services show <name>\nproxy-aiops services upstreams [--service <name>]\nproxy-aiops certs [--sweep] [--warn-days 30] [--critical-days 7] [--port 443]\nproxy-aiops config snapshot\nproxy-aiops config search <query>\nproxy-aiops config get <path>\n```\n\n## Flagship analyses\n\n```bash\nproxy-aiops analyze health [--service <name>]   # backend/upstream health RCA\nproxy-aiops analyze errors [--rate 5.0] [--min-requests 30]   # 5xx error-rate RCA\nproxy-aiops analyze conflicts                   # shadowed/dead routes, redirect loops\n```\n\n## Governed writes (dry-run + double-confirm; audited + undo-recorded)\n\n```bash\n# caddy config (teaching error on traefik/haproxy targets)\nproxy-aiops config set <path> '<json>' [--dry-run]\nproxy-aiops config delete <path> [--dry-run]        # risk=high, double-confirm\n\n# haproxy runtime servers (teaching error on traefik/caddy targets)\nproxy-aiops server state <backend> <server> ready|drain|maint [--dry-run]\nproxy-aiops server weight <backend> <server> <0-256> [--dry-run]\n```\n\nHigh-risk writes prompt for double confirmation at the CLI. Optionally export\n`PROXY_AUDIT_APPROVED_BY` (and `PROXY_AUDIT_RATIONALE`) to annotate the audit\nrow with who/why — never required.\n\n## Secrets\n\n```bash\nproxy-aiops secret set <target>      # store encrypted (hidden prompt)\nproxy-aiops secret list              # names only, never values\nproxy-aiops secret rm <target>\nproxy-aiops secret migrate           # import legacy plaintext .env\nproxy-aiops secret rotate-password   # re-encrypt under a new master password\n```\n\n## MCP server\n\n```bash\nproxy-aiops mcp        # stdio transport (or: proxy-aiops-mcp)\n```\n\n## Environment variables\n\n| Variable | Purpose |\n|----------|---------|\n| `PROXY_AIOPS_MASTER_PASSWORD` | unlock secrets.enc non-interactively (MCP/CI) |\n| `PROXY_AIOPS_CONFIG` | alternate config.yaml path (MCP server) |\n| `PROXY_AIOPS_HOME` | relocate config/audit/undo state dir |\n| `PROXY_AUDIT_APPROVED_BY` / `PROXY_AUDIT_RATIONALE` | optional approver/rationale annotations recorded on the audit row |\n| `PROXY_MAX_TOOL_CALLS` / `PROXY_MAX_TOOL_SECONDS` | per-process budget ceilings |\n| `PROXY_RUNAWAY_MAX` / `PROXY_RUNAWAY_WINDOW_SEC` | runaway circuit-breaker tuning |\n| `P"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2144,"uniquenessScore":40,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T17:07:11.725Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T17:07:11.725Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:43:28.536Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}