Kontrol

你的机器。你的代理。你的审批门禁。

Kontrol 是一个自托管的控制平面，用于以特定且经过审核门禁的方式扩展 WebUI 和 CLI 编码代理。它通过 MCP 暴露你的本地项目文件，将受限的工作分派给已注册的 ACP 代理，将结果路由回人工审核，并对代理可以触及的工具和路径执行策略约束。

你在自己的机器上运行它，通过你控制的隧道暴露它，并决定哪些代理可以运行、它们能做什么、以及它们的工作何时被允许落地。

与众不同之处

大多数 MCP 文件服务器桥接只停留在"读/写/编辑"。Kontrol 在其上增加了三层：

Ralphie Muntz 循环 — 代理提交工作以供人工审核。审核界面（WebUI 或任何 MCP 客户端）显示差异。人工批准、要求修改或拒绝。代理从持久化的反馈状态继续 — 即使代理进程已死并重启。

续作发件箱 — 每个审核决定都会生成一个结构化的续作数据包，包含裁决、所需操作和恢复说明。该数据包从审核界面跨越到下一个代理回合，因此工作可以在不丢失上下文的情况下继续。

策略模式 — 按工具和按路径的审批规则。危险命令可以要求一次性审批，或者你可以为整个工作区会话批准它。只读检查保持快速；破坏性操作暂停等待人工判断。

底层是带追加式事件日志的事务性工作流状态：提交、反馈、审批、续作、运行和策略决策都持久化在 SQLite 中，事件流唤醒 WebUI 监视器和被阻塞的代理。

Related MCP server: safe-code-mcp

安装

Kontrol 需要 Node >=22.19 <27。

npm 包名已为 @b-a-m-n/kontrol 保留，但公共包尚未发布。目前从 GitHub 安装：

npm install -g git+ssh://git@github.com/B-A-M-N/Kontrol.git
kontrol init
kontrol serve

如果你没有使用 GitHub SSH 密钥，请使用 HTTPS URL：

npm install -g git+https://github.com/B-A-M-N/Kontrol.git

如需源码开发，请克隆仓库并在本地链接 CLI：

git clone git@github.com:B-A-M-N/Kontrol.git
cd Kontrol
npm install --include=dev
npm run build
npm link
kontrol init
kontrol serve

要从本检出启动完整的本地开发栈（MCP 服务器、已配置的 ACP 适配器和 Secure MCP 隧道），请使用：

kontrol up

kontrol up 使用检出的 .env，并执行与 start-all.sh 相同的预检和就绪检查。

该检出还提供 ./restart-kontrol.sh，它运行相同的事务性启动器。它在停止旧的受管进程之前构建并验证替换版本，如果就绪阶段失败则回滚。

仅限受限的 CI 或沙盒环境，设置 KONTROL_SKIP_PREFLIGHT_TESTS=true 以跳过完整测试套件；所有其他预检和就绪检查保持启用。

在设置过程中，Kontrol 会询问：

• 允许代理打开的本地项目文件夹

• 本地端口，通常为 7676

• 来自 Cloudflare Tunnel、ngrok、Pinggy、Tailscale Funnel 或其他反向代理的公共 HTTPS 基础 URL

使用不带 /mcp 的公共源：

https://your-tunnel-host.example.com

当客户端连接时，Kontrol 会打开一个 Owner 密码审批页面。输入 kontrol init 打印的密码。它也存储在：

~/.kontrol/auth.json

请保持该密码私密。

连接任何 MCP 客户端

默认本地端点：

http://127.0.0.1:7676/mcp

GET /healthz 报告进程存活状态和内置构建标识。GET /core-readyz 在适配器仍在启动时检查 KONTROL 自身的数据库、MCP 处理器、工作区/审核/ACP 初始化以及运行时构建标识。GET /readyz 是严格的操作就绪检查：它还要求已配置的工作代理处于活动状态。启动器在宣布堆栈就绪之前，还会执行实际的 MCP 初始化、代理发现、工作区打开、文件读取和 bash 往返测试。

大多数用户通过公共 HTTPS 隧道连接：

https://your-tunnel-host.example.com/mcp

Kontrol 通过 Streamable HTTP 使用标准 MCP 协议。任何兼容客户端都可以工作：ChatGPT、Claude、Codex、Cursor、Windsurf、自定义工具。

OpenAI Secure MCP 隧道

要将 Kontrol 连接到 ChatGPT 而无需暴露入站端口，请在本地运行它，并通过 OpenAI Secure MCP Tunnel 路由 ChatGPT。在该设置中使用 KONTROL_AUTH_MODE=tunnel：Kontrol 绑定回环地址并在 /mcp 上禁用自身的认证门禁，因此 ChatGPT 以无认证方式连接。访问控制委托给隧道和拥有它的 OpenAI 工作区。OAuth（公共部署的默认方式）在此有意关闭，因为其授权服务器无法通过隧道访问。

KONTROL_AUTH_MODE=tunnel
HOST=127.0.0.1
PORT=7676
kontrol serve

在隧道客户端中以无认证方式注册服务器，指向回环源。受管检出启动器（./start-all.sh）在启动后保持一个持久的监督进程，并使用阈值化重启修复失败的隧道/适配器组件：

tunnel-client run \
  --mcp.server-url "http://127.0.0.1:7676/mcp"

启动器使用 KONTROL_TUNNEL_PROFILE（默认 sample_mcp_with_dcr）。如果该配置文件指向已退役或过时的隧道，请在 OpenAI Tunnels 中创建或选择当前注册后，在 .env 中设置 KONTROL_TUNNEL_ID=tunnel_...，然后重启堆栈并将 ChatGPT 连接器重新连接到该隧道 ID。

审核 WebUI 作为自包含的 MCP App 资源提供（其 CSS 和 JS 内联到单个 workspace-app.html 中），因此 ChatGPT iframe 不需要 localhost 获取。完整安全规则请参阅 配置参考。

每个 MCP mcp-session-id 都是一个隔离的传输上下文。Kontrol 不会仅仅因为客户端共享逻辑名称就合并会话，因此多个对话可以并发使用服务器。工作区和审核连续性由显式的持久化 ID 承载，而不是假设单独的传输属于同一对话。

代理可以做什么

连接后，代理可以打开一个已批准的项目文件夹作为工作区，并：

• 读取、写入和编辑文件

• 搜索代码和检查目录

• 运行 shell 命令以执行测试、构建、git 和包脚本

• 使用隔离的 Git worktree 进行并行会话

• 遵循 AGENTS.md 和 CLAUDE.md 中的项目说明

• 从你的技能文件夹中发现本地代理技能

• 在 ChatGPT Apps 兼容主机中显示工具卡片和可选的变更摘要

• 提交工作以供人工审核并从反馈中继续

Ralphie Muntz 循环

审核循环是事件驱动的且与提供商无关：

Agent submits work → Kontrol captures diff, emits ReviewRequested
     ↓
Human reviews diff in WebUI / any MCP client
     ↓
Human approves, requests changes, or rejects
     ↓
Kontrol persists feedback event + generates continuation packet
     ↓
If agent is live: it unblocks and continues
If agent stopped: it reads feedback when it resumes

该循环存在于 Kontrol 的事件日志中，而不是任何特定主机中。你可以从用于聊天的同一界面、从终端或从未来的工具中审核提交。

技能名称

该项目附带几个刻意好记的 Agent Skills。这些名称不是产品表面；它们是循环的协议句柄：

• ralphie-muntz-loop 是工作方契约。CLI 代理执行受限工作，提交差异，等待反馈，并且仅从持久的审核状态恢复。

• nelson-wiggum-loop 是审核方契约。WebUI 或 MCP 审核者开始工作，检查提交，并且是唯一有权宣布工作完成的方。

• kontrol-supervised-mission 是任务控制契约。它在传输循环之上添加目标、标准、发现、证据、工作订单和审批阻止项。

这些玩笑名称使会合点易于记忆。权威模型是严肃的：工作者不能自我批准，审核绑定到确切的提交和工作区快照，完成由审核者或任务谓词门控。

策略模式

控制哪些操作需要人工审批：

# Require approval for bash, allow file edits freely
KONTROL_POLICY_TOOL_BASH=ask KONTROL_POLICY_TOOL_WRITE=allow

# Deny access to sensitive paths (structured JSON — the per-rule env format
# `KONTROL_POLICY_PATH_<glob>` is no longer supported; it is not valid
# shell assignment syntax)
KONTROL_POLICY_PATH_RULES='[{"pattern":"/etc/ssh/**","mode":"deny"}]'

# Default: ask for anything not explicitly allowed
KONTROL_POLICY_MODE=ask

模式：

当调用需要审批时，代理的工具调用会阻塞（长轮询），直到人工决定。"为工作会话批准"缓存该决定直到工作会话结束，因此重复操作不会重新提示；"为工作区批准"缓存直到工作区关闭；"批准一次"不缓存。

心智模型

Kontrol 是一个持久的审核邮箱和策略权威，而不仅仅是一个文件服务器。

你决定允许哪些根目录。你决定哪些工具需要审批。代理完成工作，提交审核，并从结构化反馈中继续。持久的工作流状态和追加式事件日志是每个界面读取的权威：CLI、WebUI、MCP 工具和 ACP 适配器。

对于正常会话：

1. 启动你的隧道。

2. 运行 kontrol serve。

3. 将你的 MCP 代理连接到公共 /mcp URL。

4. 使用 Owner 密码批准连接。

5. 要求代理在你允许的根目录之一内打开项目。

6. 审核传入的提交。

文档

• 设置指南

• 编码工作流

• 配置参考

• 安全模型

• 故障排除

平台支持

kontrol doctor

致谢

Kontrol 源于我酝酿已久的一个想法，后来因为本地 MCP/工作区层难以做对而被搁置。当我看到 Waishnav 构建了 DevSpace 时，我以该 MCP 实现为基础，并朝着我一直试图达到的方向进行了扩展。

原始 DevSpace 项目以 MIT 许可证分发。Kontrol 保留该归属，同时添加了 ACP 工作分派、持久审核循环、受监督任务、策略审批和适配器集成。我可以看到这种本地、审核门控的代理控制平面风格可能在我的个人设置之外也有用，因此该分支现在有了自己的名称和产品方向。

本地开发

npm install --include=dev
npm run dev
npm run typecheck
npm test
npm run build
npm run start