Commandclaw MCP

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": ""
  },
  "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

______________________________________________________________________

生成文件目标

______________________________________________________________________

API终点

健康与运营

会话管理

代理集成

代理只需要两个值：

COMMANDCLAW_MCP_GATEWAY=http://localhost:8420
COMMANDCLAW_MCP_KEY=

______________________________________________________________________

三个安全层

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

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

• 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来源研究白皮书.

仓库