Claude Bridge

Claude Bridge

以本地优先、跨机器运行的独立编码 Agent 消息总线。

Claude Bridge 让不同机器上的编码 Agent 会话通过命名频道交换有序消息。中继由用户自托管，默认使用 SQLite，并提供 MCP、小型 JSON API、仪表板和终端 UI。

它不会调用模型 API，也不要求 Agent 共享文件系统或进程。本项目的起因是 Claude Code，但核心基于 MCP，不与 Anthropic 绑定。

前向构建提示： 此源代码树的版本标识为 1.2.0.dev1。这是一个超前于最新 PyPI 稳定版的开发构建。替换稳定版部署前，请查看变更日志和 0.9 到 1.2 迁移指南。

为什么使用它？

• 让 Windows、macOS、Linux 或远程主机上的 Agent 在各自的会话中运行。
• 发送任务、结果、审查请求和制品引用，无需远程 shell 访问权限。
• 使用持久化历史记录和消费者游标，在客户端重启后恢复。
• 使用幂等键安全地重试发送。
• 通过 MCP、浏览器仪表板、TUI 或 REST 观察同一个中继。
• 在本地运行，或通过明确的安全策略在专用 LAN/tailnet 上运行。

Claude Bridge 是一种传输机制，而不是自主编排器。收到消息并不意味着 Agent 获准执行该消息。

传输方式

接口	路径或命令	用途
MCP Streamable HTTP	/mcp	推荐的远程 MCP 传输方式
MCP stdio	claude-bridge --stdio	本地子进程传输方式
旧版 MCP HTTP+SSE	/sse 和 /messages/	迁移期间用于现有配置
频道事件 SSE	/events/channel/<channel>	仪表板、TUI 和自定义监听器；不是 MCP
JSON API	/api/*	浏览器、脚本和集成

自动化测试会针对 /mcp 完成真实的 MCP SDK 握手。CI 中不会启动厂商客户端。请参阅基于证据的兼容性矩阵。

架构

flowchart TB
    A["Claude Code / Codex / MCP client"] -->|"Streamable HTTP /mcp"| B["Claude Bridge"]
    C["Local MCP client"] -->|"stdio"| B
    D["Dashboard / TUI / script"] -->|"REST + event SSE"| B
    B --> E[("SQLite")]

消息和实时通知记录会在同一事务中写入 SQLite。HTTP 进程会轮询该持久化发件箱（默认间隔为 500 ms），因此，来自独立 stdio 进程的写入也会传播到已连接的仪表板/TUI 事件流。持久化的频道历史记录在重启后仍是权威数据。

安装

python -m pip install claude-code-bridge

也可以安装终端 UI：

python -m pip install "claude-code-bridge[tui]"

由于 claude-bridge 已被另一个无关项目占用，PyPI 发行包命名为 claude-code-bridge。命令和 Python 包仍为 claude-bridge 和 claude_bridge。

从源代码检出目录安装：

git clone https://github.com/constripacity/Claude-Bridge.git
cd Claude-Bridge
python -m pip install -e ".[dev]"

安全启动

默认使用仅限本地访问的 HTTP 模式：

claude-bridge

此模式会监听 127.0.0.1:8765。打开 http://127.0.0.1:8765/ 访问仪表板，或将 MCP 客户端连接到 http://127.0.0.1:8765/mcp。

本地 stdio 模式不会打开网络监听端口：

claude-bridge --stdio

跨机器服务

网络绑定采用故障关闭策略。将客户端 URL 中使用的地址作为可信主机提供，并要求使用令牌：

export CLAUDE_BRIDGE_AUTH_TOKEN="$(openssl rand -hex 32)"
claude-bridge \
  --host 0.0.0.0 \
  --trusted-host 100.64.0.10

这里的 100.64.0.10 可能是服务器的 tailnet 地址。DNS 部署可以使用 bridge.example.internal 这样的值。--trusted-host 的值应为主机名或 IP 地址，不带 URL 方案或路径；该选项可以重复使用。

需要通过两项独立检查：

1. --trusted-host 控制接受哪些 HTTP Host 名称；以及
2. Bearer 令牌控制谁可以使用受保护的端点。

若要在私有测试网络中有意禁用身份验证，请将令牌替换为 --allow-unauthenticated-network。这是对风险的明确接受，并非推荐的生产环境配置。

在不可信网络上传输敏感内容前，请使用 --tls-cert 和 --tls-key、HTTPS 反向代理或加密覆盖网络。 完整的信任模型请参阅安全策略。

容器

官方镜像同样采用故障关闭策略。网络部署必须提供可信主机和身份验证策略：

export CLAUDE_BRIDGE_AUTH_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 8765:8765 \
  -v claude-bridge-data:/data \
  -e CLAUDE_BRIDGE_AUTH_TOKEN \
  -e CLAUDE_BRIDGE_TRUSTED_HOSTS="100.64.0.10" \
  ghcr.io/constripacity/claude-bridge:latest

SQLite 数据库存储在 /data 中。发布镜像使用精确版本标签和主版本/次版本标签；edge 跟踪 main。

连接客户端

Claude Code

远程 Streamable HTTP：

claude mcp add --transport http -s user claude-bridge \
  http://127.0.0.1:8765/mcp

本地 stdio：

claude mcp add -s user claude-bridge -- claude-bridge --stdio

对于受保护的远程端点，请使用已安装的 Claude Code 版本所支持的选项，附加匹配的 Authorization 标头。迁移期间，旧版配置可以继续使用 --transport sse 指向 /sse。

Codex

在 ~/.codex/config.toml 中配置本地 stdio：

[mcp_servers.claude_bridge]
command = "claude-bridge"
args = ["--stdio"]

远程 Streamable HTTP：

[mcp_servers.claude_bridge]
url = "http://127.0.0.1:8765/mcp"
bearer_token_env_var = "CLAUDE_BRIDGE_AUTH_TOKEN"

这些示例遵循各客户端文档所述的传输方式。仓库的 CI 会验证 MCP 协议行为，而不会启动完整的厂商客户端。作出支持声明前，请参阅兼容性矩阵。

MCP 工具

工具	用途
bridge_send	发送旧版文本或协议 v1 消息；支持幂等重试
bridge_receive	使用消息游标或持久化消费者游标读取有界页面
bridge_wait	等待新消息，最长 55 秒，无需频繁轮询
bridge_ack	单调递增地推进限定于通道的消费者游标
bridge_channels	列出活跃通道及其计数
bridge_ping	检查桥接服务的健康状态和能力
bridge_status	汇总各通道的近期活动
bridge_clear	删除一个通道中的所有消息（和任务）
bridge_enqueue	将任务加入通道的工作队列（独占；仅领取一次）
bridge_claim	以租约原子领取下一个任务；使用 wait_seconds 长轮询
bridge_complete	将已领取的任务标记为完成，并由其 lease_token 进行隔离
bridge_fail	将已领取的任务标记为失败——使用退避策略重新入队，或移入死信队列
bridge_tasks	检查通道队列：按状态统计数量并列出任务

对于支持 MCP 结构化内容的客户端，工具结果会包含结构化数据；此外还会提供可读文本表示，以确保兼容性。

可靠任务/结果示例

协调器使用稳定的重试键发送结构化任务：

bridge_send(
  channel="payments:worker",
  sender="windows-orchestrator",
  idempotency_key="job-802-task",
  message={
    "schema_version": 1,
    "type": "task",
    "content": {"action": "run_tests", "target": "payments"},
    "thread_id": "payments-42",
    "correlation_id": "job-802"
  }
)

工作器使用其持久化的消费者身份等待：

bridge_wait(
  channel="payments:worker",
  consumer_id="mac-worker",
  timeout_seconds=20
)

成功处理任务后，它会推进游标：

bridge_ack(
  channel="payments:worker",
  consumer_id="mac-worker",
  message_id="<processed-message-id>"
)

之后，它可以使用相同的 thread_id 和 correlation_id 将结果发送到返回通道。确认机制提供至少一次处理语义，但不能保证任意外部副作用恰好发生一次。

完整的信封、重试、游标和保留策略约定见协议参考。

任务队列（工作分配）

消息会扇出——每个消费者游标都能看到每条消息。任务队列则恰恰相反：每个任务只由一名工作者认领。让一组工作者 Agent 监听一个通道，即可共享工作，且不会重复处理任务。

编排器将任务入队（使用幂等键确保去重安全）：

bridge_enqueue(
  channel="builds",
  payload={"repo": "payments", "action": "run_tests"},
  max_attempts=3,
  idempotency_key="build-802"
)

每名工作者认领下一个任务，并持有一项租约（可见性超时）。两名工作者不会获得同一个任务；wait_seconds 会在队列为空时进行长轮询：

bridge_claim(channel="builds", consumer="worker-3", lease_seconds=300, wait_seconds=20)
# -> { task_id, payload, attempts, lease_token, lease_expires_at }

任务会在租约到期前完成——成功时调用 complete，需要重试时调用 fail——两者都由 lease_token 进行隔离，确保重新认领的任务不会被覆盖：

bridge_complete(channel="builds", task_id="tsk_…", lease_token="…", result={"passed": 105})
bridge_fail(channel="builds", task_id="tsk_…", lease_token="…", requeue=true, retry_delay_seconds=30)

如果工作者崩溃且始终未处理完任务，租约到期后任务会自动重新入队；或者在 max_attempts 耗尽后进入死信队列。这是至少一次投递，因此任务处理程序应具备幂等性。 bridge_tasks(channel="builds") 会显示队列各状态的计数。

通道

通道会在首次写入时创建。一个易读的命名惯例是 <project>:<purpose>：

payments:orchestrator
payments:worker
payments:events
payments:review
general:status

通道名称用于路由，而非授权。在当前的共享令牌模型中，任何经过授权的客户端都可以读取、写入或清空任何通道。

控制面板、TUI 和 JSON API

除非使用 --no-dashboard，否则控制面板将在 / 提供服务。它使用 JSON API 和各通道的事件流。其 React 应用、字体及其他运行时资源都与软件包一同打包，因此加载控制面板时不会连接第三方 CDN。静态应用采用限制性内容安全策略。

运行 TUI：

python -m claude_bridge.tui
python -m claude_bridge.tui \
  --url http://100.64.0.10:8765 \
  --sender mac

TUI 会从环境变量中读取 CLAUDE_BRIDGE_AUTH_TOKEN，避免机密出现在进程命令行中。

核心 HTTP 端点：

端点	用途
GET /status	无需身份验证的精简健康检查
GET /api/state	通道计数、发送方、版本和运行时长
GET /api/messages?channel=X&since_id=Y&limit=N	有界通道历史记录
GET /api/messages/{id}	单条消息详情
GET /api/wait?channel=X&consumer_id=Y	使用消费者或消息游标进行有界长轮询
POST /api/send	发送传统文本或 protocol-v1 消息，可选启用幂等性
POST /api/ack	前移一个持久化消费者游标
POST /api/clear	清空一个通道
GET、POST、DELETE /api/session	查看、创建或撤销不透明的控制面板会话
GET /api/audit?limit=N	启用时返回近期审计事件
GET /events/channel/<channel>	带有界重放的实时事件流

事件流缓冲区填满后，可能会断开速度较慢的订阅者；持久化历史记录仍是权威数据源。使用最后一条消息 ID 重新连接；若收到 cursor_stale 或 replay_truncated，请显式获取历史记录。

身份验证和浏览器边界

设置 CLAUDE_BRIDGE_AUTH_TOKEN、--auth-token-file 或 --auth-token。字面形式的 CLI 参数可能出现在进程列表中；建议使用环境变量或权限受限的文件。

启用后，受保护的 REST、MCP 和事件端点需要提供：

Authorization: Bearer <token>

/status 仍可公开访问，并且有意仅包含最少信息。静态控制面板外壳可能可以访问，但受保护的数据 API 仍需要令牌。

不安全的浏览器变更操作会受到 Origin 限制；JSON 端点要求使用 JSON 媒体类型；Host 标头采用允许列表。可使用可重复指定的 --cors-origin 标志，单独配置额外的浏览器来源。

控制面板会将 Bearer 令牌提交一次到 POST /api/session，并接收一个短期有效的不透明 HttpOnly、SameSite=Strict Cookie。主令牌不会写入本地存储或 URL。事件流使用该 Cookie 进行身份验证；不接受通过 ?token= 进行的查询参数身份验证。退出登录会撤销会话；服务器重启后，所有内存中的控制面板会话都会失效。

配置

CLI/环境	默认值	用途
--host	127.0.0.1	HTTP 绑定接口
--port	8765	HTTP 端口
--db / CLAUDE_BRIDGE_DB	./claude-bridge.db	SQLite 路径
--trusted-host / CLAUDE_BRIDGE_TRUSTED_HOSTS	loopback 主机	接受的 Host 名称/IP
--auth-token-file / CLAUDE_BRIDGE_AUTH_TOKEN	未设置	共享 Bearer 身份验证
--allow-unauthenticated-network	关闭	明确绕过非 loopback 网络身份验证
--cors-origin / CLAUDE_BRIDGE_CORS_ORIGIN	仅同源	其他浏览器来源，包括另一个 localhost 端口
--tls-cert + --tls-key	未设置	直接启用 HTTPS 监听器
--retention-days / CLAUDE_BRIDGE_RETENTION_DAYS	0	删除早于 N 天的消息；0 表示保留
--audit-log / CLAUDE_BRIDGE_AUDIT_LOG	关闭	记录与安全相关的事件
CLAUDE_BRIDGE_AUDIT_RETENTION_DAYS	90	限制审计历史记录
CLAUDE_BRIDGE_SESSION_TTL_SECONDS	28800	不透明仪表板会话的有效期
CLAUDE_BRIDGE_EVENT_POLL_MS	500	跨进程 outbox 轮询间隔
CLAUDE_BRIDGE_EVENT_RETENTION_DAYS	7	保留已投递的 outbox 记录
--no-dashboard	关闭	不挂载浏览器资源
CLAUDE_BRIDGE_MAX_REQUEST_BYTES	262144	HTTP 请求正文的最大大小
CLAUDE_BRIDGE_MAX_MESSAGE_BYTES	131072	编码后消息的最大大小
CLAUDE_BRIDGE_MAX_SSE	100	通道事件订阅者总数
CLAUDE_BRIDGE_MAX_SSE_PER_CHANNEL	25	单个通道的订阅者数量
CLAUDE_BRIDGE_SSE_REPLAY_LIMIT	500	重连积压上限
CLAUDE_BRIDGE_STATELESS_HTTP	关闭	使用无状态 Streamable HTTP 会话

存在对应标志时，CLI 值优先。无效的数值或布尔型环境变量会在启动时导致配置错误。

持久化与运行限制

• SQLite 以 WAL 模式运行，适用于个人或小型团队的消息中继。
• 该服务目前不是多节点或高可用消息代理。
• 一个 HTTP 工作进程可与协作的 stdio 进程共享 WAL 数据库；持久化 outbox 会传播它们的实时事件。这仍是小规模 SQLite 设计，并非多节点或企业级消息代理。
• 保留策略可能导致旧游标失效。重要的工作成果应存放在代码库或制品存储中，而不应只保留在中继历史记录里。
• 共享 Bearer 令牌不提供身份信息或按通道划分的权限。
• 没有可复现的基准测试和环境信息时，不会声称性能基准。

未来的运维与授权里程碑见路线图。

开发

python -m pip install -e ".[dev]"
ruff check claude_bridge tests
pytest -v
python -m build

CI 会在 Python 3.10–3.13 上测试 Linux，并在 Windows 和 macOS 上运行当前版本的冒烟测试。真实套接字 MCP 测试通过官方 SDK 覆盖初始化、工具列表、发送、接收、等待和确认。另一个任务会构建 sdist 和 wheel、验证其元数据、将每个制品安装到干净环境中，并检查 CLI。

提出新功能前，请阅读贡献指南。如需报告漏洞，请使用安全政策中的私密流程，而非公开议题。

路线图

当前计划顺序如下：

1. 1.2 — 安全的 Streamable HTTP、结构化消息、幂等性和持久化 消费者；
2. 1.3 — 原生客户端诊断和实验性的 Claude Channels 配套工具；
3. 1.4 — 独立身份、作用域、ACL、配额和令牌轮换；
4. 1.5 — 可观测性、运维工具和可选的可扩展 后端；以及
5. 2.0 — 联邦和可选的 A2A 适配器（如果实际使用需求确有需要）。

每个里程碑及其不在目标范围内的事项均已在 路线图中定义。

许可证

MIT — 详见许可证。

由 Constripacity 创立并维护。