当前状态#

当前状态

V0.1 — 9 个领域共 40 个 tool，外加 4 个 resource URI。覆盖 Agent 管理、成本追踪、配置安全、审计、连接器、智能分析、Runbook、运维操作，以及 Runtime Host 发现与 attach-mode session sync。认证方式仍是 Bearer Token（与 CLI 一致）。Hermes / Claude Code / Codex 的 Runtime Host 工具已经可用，但还不是与 OpenClaw connector 完全同权的 provider-native 集成。

工作原理#

MCP Server 是 AI 助手与 ClawButler API 之间的轻量协议桥梁。它将自然语言意图转换为结构化的 API 调用，让你可以通过任何 MCP 兼容客户端管理 Agent 舰队。

text

┌──────────────────┐     stdio / HTTP     ┌─────────────────┐     REST API     ┌──────────────────┐
│   AI 助手        │ ◄──────────────────► │  MCP Server     │ ◄─────────────► │  ClawButler API  │
│  (Claude 等)     │       MCP 协议       │  (clawbutler-   │   Bearer Token  │  (FastAPI)       │
│                  │                      │   mcp)          │                 │                  │
└──────────────────┘                      └─────────────────┘                 └──────────────────┘

安装与配置#

MCP Server 是一个独立的 Python 包，连接到你的 ClawButler API。安装后配置你的 AI 助手即可使用。

bash

# 从 PyPI 安装
pip install clawbutler-mcp

# 或使用 uvx 直接运行（零安装）
uvx clawbutler-mcp

# 设置环境变量
export CLAWBUTLER_API_URL=https://your-instance.clawbutler.cc
export CLAWBUTLER_TOKEN=your-bearer-token

IDE 配置#

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

json

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

添加到项目的 .mcp.json：

json

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目级）：

json

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

json

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Streamable HTTP（远程部署）

容器化或远程部署时，使用 HTTP 传输模式：

bash

clawbutler-mcp --transport http --port 8080

可用工具#

9 个领域共 40 个工具。点击任意工具查看参数详情。

Agent 管理（5 个工具）

list_agents, get_agent, enable_agent, disable_agent, get_agent_config

完整的 Agent 生命周期能力，可查看状态、启停和配置详情。

成本与预算（4 个工具）

get_cost_summary, get_cost_by_agent, get_cost_trend, list_budgets

支持日期范围成本追踪、按 Agent 拆分、趋势分析和预算监控。

配置安全（5 个工具）

list_config_snapshots, take_config_snapshot, diff_config_snapshots, preview_rollback, execute_rollback

配置安全能力，包含浏览快照、手动保存点、语义 diff、dry-run 回滚和正式回滚。

审计与活动（3 个工具）

search_audit_events, get_audit_event, get_recent_activity

提供多维筛选的审计搜索和最近活动流，适合调查取证。

连接器（4 个工具）

list_connectors, get_connector_detail, test_connector, diagnose_connector

网关连接器管理，支持列表、详情、连通性测试与诊断。

智能分析（4 个工具）

get_root_cause_analysis, get_reliability_scores, get_agent_reliability, get_value_comparison

智能分析面，覆盖根因分析、可靠性评分和价值对比。

运维操作（6 个工具）

get_killswitch_status, activate_killswitch, deactivate_killswitch, check_health, get_trust_status, get_dashboard

运维操作面，覆盖 Kill Switch、健康检查、信任状态与仪表盘摘要。

Runbook 自动化（4 个工具）

list_runbooks, get_runbook, execute_runbook, get_runbook_run

Runbook 自动化能力，支持浏览、带参数执行以及单次运行追踪。

运行时主机（5 个工具）

list_runtime_hosts, get_runtime_host_detail, discover_runtime_host, batch_add_runtime_host_instances, sync_runtime_host_sessions

对已配对机器做 Hermes / Claude Code / Codex / OpenClaw 发现、批量接入连接器，并同步 attach-mode 会话。

工具参数参考#

全部 40 个工具的完整参数参考。点击工具名展开参数。标记 * 的参数为必填。

Agent 管理

成本与预算

配置安全

审计与活动

连接器

智能分析

运维操作

Runbook 自动化

运行时主机

输出示例#

工具返回格式化的 Markdown 字符串。以下是 AI 助手实际收到的输出示例：

list_agents"列出我所有的 Agent"

markdown

- **coordinator** (id: aaa-bbb-…) [on] health=healthy platform=openclaw
- **researcher** (id: fff-ggg-…) [off] health=error platform=openclaw
- **writer** (id: ccc-ddd-…) [on] health=warning platform=codex

get_cost_summary"最近一周的成本是多少？"

markdown

**Cost Summary** (2026-03-10 → 2026-03-17)
- Total cost: $42.5678
- Input tokens: 1,234,567
- Output tokens: 654,321
- Records: 150

diff_config_snapshots"对比 agent coordinator 的配置版本 3 和 4"

markdown

**Config Diff** v3 → v4
Summary: Model changed
- [modified] `model.primary`: claude-sonnet-4-5 → claude-sonnet-4-6
- [added] `tools.web_search`: — → enabled
- [removed] `skills.deprecated_skill`: active → —

check_health"运行健康检查"

markdown

**Health Check**
- Status: ready
- Version: 0.1.0
- Dependencies:
  - postgres: ok
  - valkey: ok
- Worker: running (mode=embedded)

get_dashboard"显示仪表盘"

markdown

**Dashboard Summary**
- Agents: 12 online / 14 total
- Today's cost: $8.4321
- Events today: 67
- Pending approvals: 2
- Unread notifications: 5

MCP 资源#

资源提供只读快照，AI 助手可以在调用工具之前将其作为上下文使用。

clawbutler://dashboard

仪表盘摘要 — Agent 数量、今日成本、事件、待审批。

clawbutler://agents

Agent 列表（ID、名称、状态、平台）。

clawbutler://cost/today

今日成本快照。

clawbutler://health

系统就绪状态和依赖健康。

使用示例#

晨间运维检查

让 AI 助手为你做一个 Agent 舰队的晨间简报。

bash

"检查一下我的 ClawButler 仪表盘 — 多少 Agent 在线，
今天的成本是多少，有没有待审批的？"

成本追查

不离开编辑器，直接深入分析成本异常。

bash

"显示最近 7 天按 Agent 的成本明细。
哪个 Agent 花费最高？"

应急响应

AI 辅助的事故响应 — Kill Switch 加审计追踪。

bash

"Agent coordinator 行为异常。
检查它的健康状态，然后激活 Kill Switch，
原因填'行为异常 — 调查中'。"

配置回滚

审查并回滚一个错误的配置变更。

bash

"列出 agent coordinator 最近 5 个配置快照。
对比版本 3 和 4 的 diff，然后预览回滚到版本 3。"

审计追查

搜索审计事件，追踪谁在什么时候做了什么变更。

bash

"搜索最近 3 天 risk_level=high 的审计事件。
显示最新一条的完整详情。"

连接器诊断

诊断网关连接问题。

bash

"列出我的连接器。OpenClaw 网关似乎变慢了 —
对它运行一次诊断，告诉我什么问题。"

Runtime Host 发现与会话同步

在已配对机器上发现 Hermes / Claude Code / Codex / OpenClaw 实例，只接入需要治理的实例，并把 attach-mode 会话投影到 ClawButler。

bash

"列出我的 Runtime Hosts。对已配对的 MacBook 执行发现，
把 Codex 和 Claude Code 实例添加成 connectors，
然后同步最近的 attach-mode 会话供调查使用。"

覆盖对比#

MCP 已支持

- Agent 增删改查和启停
- 成本汇总、按 Agent 明细、趋势、预算
- 配置快照、手动保存点、语义 diff、回滚
- 审计事件搜索和活动流
- 连接器列表、测试、诊断
- 智能分析（根因分析、可靠性、价值）
- Kill Switch（激活 / 解除）
- 健康检查和信任状态
- 仪表盘 KPI
- Runbook 执行和追踪
- Runtime Host 的 list/detail/discover/batch-add/sync，用于 Hermes / Claude Code / Codex / OpenClaw 的 attach-mode 接入

后续版本（V2）

- 用户注册 / 组织管理 / RBAC
- Federation 对等节点管理
- 模板画廊完整生命周期
- 报表生成和导出
- 计费和支付管理
- 通知管理
- Hermes / Claude Code / Codex Runtime Host 的 provider-native 审批、成本归因、时间线和托管控制

设计决策

- 破坏性操作（Kill Switch、回滚）在 tool description 中明确标注，AI 助手会在执行前确认。
- Token 认证 — 与 CLI 共用 Bearer Token。不要将包含 token 的 .mcp.json 提交到 git。
- 读多写少的设计 — 大部分工具是读操作；写操作需要显式参数。
- Runtime Host 同步当前是 attach-mode 投影能力，不等价于 Hermes / Claude Code / Codex 的 provider-native 治理闭环。

常见问题#

「Tool not found」或 IDE 中不显示工具

确认 clawbutler-mcp 已安装且命令路径正确。运行 `uvx clawbutler-mcp --help` 验证。检查 IDE 的 MCP 日志是否有连接错误。

401 Unauthorized / 认证错误

确认 CLAWBUTLER_TOKEN 设置正确。Token 与 CLI 通用 — 在 Web 仪表盘的设置 > API Token 中生成。

连接被拒绝 / 超时

检查 CLAWBUTLER_API_URL 指向正在运行的 ClawButler 实例。自部署环境需确保 MCP Server 运行的机器可以访问到 API。

工具可以调用但返回空数据

通常是因为 API 返回了空数组 — 你的实例可能还没有配置 Agent/成本/连接器。先试 get_dashboard 验证连通性。

如何在 Docker / 远程服务器中使用？

使用 HTTP 传输：`clawbutler-mcp --transport http --port 8080`。这会启动一个 Streamable HTTP 服务，任何 MCP 客户端都可以通过网络连接。

安全建议#

- 不要将 Token 提交到版本控制。如果 .mcp.json 包含凭据，请将其添加到 .gitignore。
- 使用环境变量或密钥管理器存储 Token — 避免在配置文件中硬编码。
- MCP Server 继承其使用的 Token 的权限。对自动化工作流使用最小权限的 scoped token。
- 共享环境中，优先使用 HTTP 传输 + 网络级访问控制（VPN、防火墙规则），而非公开暴露。

建议预留截图#

Screenshot Placeholder

Claude Desktop 集成

Claude Desktop 调用 list_agents 和 get_dashboard 工具

Screenshot Placeholder

Claude Code 集成

Claude Code 在编辑器中运行成本查询和健康检查

Screenshot Placeholder

Kill Switch 激活

AI 助手在激活 Kill Switch 前确认

Screenshot Placeholder

配置 diff

语义化的配置 diff 展示在 AI 助手对话中

Screenshot Placeholder

Runbook 执行

AI 助手执行 Runbook 并追踪进度

Screenshot Placeholder

Runtime Host 发现

AI 助手发现 Codex / Claude Code / Hermes 实例并同步 attach-mode 会话

Screenshot Placeholder

MCP 资源

AI 助手读取 clawbutler://dashboard 资源获取上下文