使用说明

CommandClaw MCP Gateway

Secure MCP proxy for AI agents. Phantom tokens. Rotating keys. Per-agent RBAC.
_{Agents never see real credentials. The gateway handles authentication. Keys rotate every hour.}

[！警告] 该项目正在积极开发中。 工作流和命令可能不完整或损坏。您的反馈有助于使情况变得更好！

有反馈或发现错误？联系方式： @Shikh4r 在X

为什么要设置单独的网关？

代理通过直接访问凭据的特定API调用与外部工具交互。如果代理通过提示注入、错误的工具调用或上下文转储泄漏密钥，则该密钥是有效的，直到有人手动旋转它。从凭据泄漏到首次恶意使用的中间时间为 5分钟.

CommandClaw MCP通过代理架构解决了这个问题：

Agent --> (phantom token) --> commandclaw-mcp --> (real credentials) --> External MCP Servers

代理从不持有真正的API密钥。即使幻影令牌泄漏，它也会在一小时内过期，并且只能通过网关工作。

快速入门（Docker Compose）

先决条件： Docker与Compose v2，Python 3.12+

# 1. Clone and enter the repo
gh repo clone FnSK4R17s/commandclaw-mcp && cd commandclaw-mcp

# 2. Generate config and .env with a random encryption seed
make setup

# 3. Add your MCP servers to the config
#    Edit ~/.commandclaw/mcp.json — see "Configuration" below

# 4. Start the stack (gateway + Redis + Cerbos)
make up

网关现在正在运行 http://localhost:8420.

make health      # Check health + readiness
make logs        # Follow container logs
make down        # Stop everything

本地开发

在Docker中仅使用Redis和Cerbos直接在您的计算机上运行网关：

# Install the package in editable mode
make install

# Start Redis + Cerbos containers
make dev-deps

# Run the gateway (connects to localhost Redis + Cerbos)
make dev

配置

网关读取 ~/.commandclaw/mcp.json （在仓库之外，从不在Git中）。环境变量与 COMMANDCLAW_ 前缀覆盖JSON值。

make setup 生成一个带有随机加密种子的启动器配置。添加您的上游MCP服务器和代理访问规则：

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 8420,
    "encryption_seed": "<auto-generated>"
  },
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": { "NOTION_API_KEY": "ntn_..." }
    }
  },
  "access": {
    "coding-agent": {
      "roles": ["developer"],
      "tools": ["github", "notion"],
      "rate_limit": { "requests_per_minute": 60 }
    },
    "research-agent": {
      "roles": ["reader"],
      "tools": ["notion"],
      "rate_limit": { "requests_per_minute": 30 }
    }
  },
  "redis": { "url": "redis://localhost:6379/0" },
  "cerbos": { "host": "localhost", "port": 3593 }
}

服务器可以是标准 (command + args)或 超文本传输协议 (url).网关自动将stdio服务器桥接到HTTP。

环境变量覆盖

环境变量使用 COMMANDCLAW_ 前缀为 __ 为了筑巢。他们 以（权力）否决 JSON配置值：

COMMANDCLAW_GATEWAY__PORT=9000              # Override gateway port
COMMANDCLAW_REDIS__URL=redis://myhost:6379  # Override Redis URL
COMMANDCLAW_CERBOS__HOST=cerbos-pdp         # Override Cerbos host

Docker Compose会自动为容器网络设置这些。看 .env.example 查看完整列表。

配置路径覆盖

集 COMMANDCLAW_CONFIG 从其他路径加载配置：

COMMANDCLAW_CONFIG=/etc/commandclaw/mcp.json commandclaw-mcp

生成文件目标

目标	描述
`make setup`	生成 `~/.commandclaw/mcp.json` 和 `.env` 带有随机加密种子
`make up`	启动所有服务（网关+Redis+Cerbos）
`make down`	停止所有服务
`make logs`	跟踪容器日志
`make ps`	显示正在运行的服务
`make build`	构建网关Docker镜像
`make restart`	重新启动所有服务
`make clean`	删除容器、卷和映像
`make install`	使用dev-deps以可编辑模式在本地安装软件包
`make dev-deps`	在Docker中仅启动Redis+Cerbos
`make dev`	在本地运行网关（首先启动Redis+Cerbos）
`make test`	运行测试套件
`make test-cov`	运行覆盖率测试
`make lint`	跑流氓+mypy
`make fmt`	带褶皱的格式代码
`make health`	检查网关运行状况和准备情况
`make session`	创建测试代理会话(`AGENT=coding-agent`)
`make metrics`	获取普罗米修斯指标

API终点

健康与运营

端点	方法	描述
`/health`	GET	活体检测
`/ready`	GET	就绪探测（Redis、Cerbos、轮换管理器）
`/metrics`	GET	普罗米修斯指标

会话管理

端点	方法	描述
`/sessions`	POST	创建幻影会话： `{"agent_id": "coding-agent"}`
`/token`	GET	轮询当前令牌（已验证）
`/sessions/{token}`	DELETE	立即撤销会话

代理集成

代理只需要两个值：

COMMANDCLAW_MCP_GATEWAY=http://localhost:8420
COMMANDCLAW_MCP_KEY=<phantom_token from /sessions>

三个安全层

1.幻影令牌模式（凭证隔离）

代理接收不透明、无意义的令牌。真正的API密钥只存在于网关的加密保险库中。

代理看到什么	网关持有什么
`dG9rZW5fYWJj...` （随机256位）	`ghp_realGitHubToken...` （静止时加密）

HMAC-SHA256使用幻影令牌作为签名密钥对请求进行签名
Fernet+Argon2d加密处于静止状态
每小时轮换一次，带5分钟的双键重叠窗口
通过会话DELETE立即撤销

2.每代理工具RBAC（双层强制）

对每个请求进行两次授权检查。两者都不够。

发现过滤 (tools/list)：Gateway只返回允许的工具。代理不知道存在未经授权的工具。

通话时间执行 (tools/call)：转发前进行完整的ABAC检查（资源属性、数量、时间）。

策略引擎： Cerbos （YAML+CEL，子ms决策）。默认情况下拒绝。

3.无状态会话管理

Redis支持的会话（第1阶段），具有可选的令牌编码会话，用于水平扩展。集 gateway.session_mode 到 "token_encoded" 以启用。

技术栈

Python 3.12+ 带有完整的async/await
FastAPI+Uvicorn --异步HTTP服务器
FastMCP --代理原语、多服务器聚合、命名空间隔离
Cerbos --RBAC工具的策略决策点（异步gRPC）
瑞迪斯 --会话存储、随机数缓存、速率限制
密码学+argon2 cffi --凭证加密
开放遥测 --OTLP跟踪，普罗米修斯指标
结构日志 --带凭证剥离的结构化JSON日志记录

文档

看 guiding_docs/VISION.md 了解完整的架构、设计决策和实现细节。

架构决策基于 124来源研究白皮书.

仓库

回购	目的
命令爪	代理运行时、电报I/O、跟踪
commandclaw保险库	Vault模板--按代理工作区克隆
commandclaw网关	LLM路由层——提供者凭据、虚拟密钥、预算、速率限制、多提供者回退
命令技能	技能库-- `npx skills add FnSK4R17s/commandclaw-skills`
命令爪存储器	召回服务——维基验证、LanceDB+BM25索引、蒸馏、混合检索
commandclaw维基	LLM Wiki——每个代理的持久复合知识库（Karpathy模式）
指挥官观察	自托管可观察性——Langfuse追踪+普罗米修斯+Grafana，一个组合