内容
# 开放远程控制
[](https://github.com/Pher217/OpenRemote-Control/actions/workflows/ci.yml) [](LICENSE) [](#为什么与众不同) [](CONTRIBUTING.md) [](https://github.com/Pher217/OpenRemote-Control/stargazers)
> 一个适用于所有编码代理的通用远程控制 - Claude Code、Codex、Gemini、Cursor、Copilot 以及任何 MCP 工具，集中到您选择的单个聊天应用中（Telegram、WhatsApp、Slack、Signal、Discord ...）。从手机启动、监控和驱动任何会话。
现在，AI 代理运行在各个地方：笔记本电脑、VPS、工作站、终端、编辑器、MCP 工具。难题不是启动它们，而是注意到何时需要它们。代理可以暂停在一个 tmux 窗格中，您几个小时前关闭了它，而您又不在那台键盘附近。更深层次的问题是，这些代理分散在各个机器、终端、编辑器和工具中，没有一个单独的地方可以查看或回答它们。开放远程控制就是这个单独的地方。
## 演示
<!-- 记录一个 20-40 秒的屏幕截图：输入 Claude Code -> 它出现在您的 Telegram 群组中 -> 从手机回复 -> 它驱动会话。保存为 docs/demo.gif，然后删除下面的占位行并取消注释下面的图像行。 -->
> 🎥 **演示即将到来** - 一个约 20 秒的剪辑：启动一个 Claude Code 会话，然后从手机驱动它。
<!--  -->
想象一下某些编码工具中内置的远程控制；然后使其通用。开放远程控制就是这样，但适用于每个编码代理，而不仅仅是一个：任何工具，任何机器，都集中到一个您已经使用的聊天中。代理**通知**您，**询问**您问题，并**请求批准** - 因此您可以**启动**，**流式传输**，**驱动**，在单个地方接收通知，回答问题并批准所有这些操作，无需找到正确的机器，终端或编辑器。
它在设计上是主权的：您自己托管它，您的会话和凭证从未离开您的基础设施，它通过官方 SDK 和开放的模型上下文协议（Model Context Protocol，MCP）访问您的工具 - 从不通过浏览器抓取或供应商黑客。
## 工作原理
```
编码代理和机器 开放远程控制 您选择的应用程序
───────────────────────────── ───────────────────── ─────────────────────
Claude Code / Codex / Cursor … Telegram
/openremote-control ──▶ WhatsApp / Slack /
主机代理（每台机器） ──▶ ──▶ 单个聊天会话每 ◀─▶ Discord / Signal /
驱动 + 镜像 ──▶ 代理 · 策略 · iMessage
通过 orc-mcp 调度 批准 · 审计
```
您生活在**一个您已经使用的应用程序**中 - Telegram，或者通过桥接器使用 WhatsApp / Slack / Signal。从您正在工作的编码代理（Claude Code，Codex，Cursor ...）内部，运行通用命令以**将该会话调度到您的手机**：
```
/openremote-control [名称]
```
它启动一个命名会话，并将其推送到您选择的应用程序；从那时起，代理的 `notify` / `ask` / `approve` 调用将到达那里，您可以从任何地方监督。 在幕后，该命令是 `openremote_control` 工具在 `orc-mcp` 桥上，因此它适用于*任何*支持 MCP 的工具 - 一个现成的 [`/openremote-control` Claude Code 命令](connectors/orc-mcp/claude/openremote-control.md) 与桥一起提供。
代理通过两种方式到达同一个聊天：
1. **聊天主题** - 会话被调度到一个聊天主题中，该主题同时流式传输回合并接受输入以驱动会话（[PR #90](https://github.com/Pher217/OpenRemote-Control/pull/90)）。
2. **通用 MCP 桥（`orc-mcp`）** - 一个小型 MCP 服务器，您可以将其安装到*任何*支持 MCP 的工具（Cursor，Copilot，Codex，Claude Code，Kiro ...）。它纯粹是一个**调度工具**：代理获得四个调用，通过*您的*后端路由到同一个聊天 -
- `openremote_control(名称)` - 启动一个会话并将其调度到您的聊天应用程序
- `notify(消息)` - 将进度推送到您的聊天
- `ask_human(问题，选项)` - 询问您某事并等待回复
- `request_approval(操作，预览)` - 请求某个操作的权限（**关闭失败**：超时时拒绝）
这是按需和代理发起的 - 代理调用您。不模拟供应商 API，不驱动封闭的 UI。
## 仓库布局
```
backend/ Django + DRF + Channels 控制平面（ASGI）
apps/
accounts 主机项目 机队库存：代理帐户，机器，项目
threads 提示批准 会话基元：对话，聊天中的答案， gated 操作
observe 会话持久性和聊天传递，用于驱动的会话（多运行时只读观察器已删除 - 请参阅 PR #90）
hostlink 主机守护进程注册 + PTY/命令 WebSocket 消费者
connectors 网关 通用 MCP 桥后端 + 消息网关后端
telegram 斜线监督 Telegram 界面，斜线命令，机队感知摘要
policies 审计二级技能 保障措施，追加审计日志，本地聊天模型，技能注册表
config/ 设置，ASGI/WSGI，Channels 路由，Celery
host-agent/ 每台机器的 Python 守护进程：注册，PTY 流式传输，输入安全策略
connectors/
orc-mcp/ 可安装的 MCP 桥客户端（openremote_control / notify / ask_human / request_approval）
messaging-gateway/ Node/TS 边车桥接 WhatsApp / Slack / Discord / Signal / iMessage
deploy/ Docker Compose，Caddy 和 headscale 部署配置
```
## 状态 - 编写+流媒体驱动已上线
后端和主机代理守护进程已实现并测试：**约 800 个测试通过**（542 后端，262 主机代理），实时 ASGI 烟雾测试绿色。
**已发货：**
- 会话调度到 **Telegram 论坛主题** 通过通用 **`/openremote-control`** 命令（`openremote_control` orc-mcp 工具 + 已发货的 Claude Code 命令）
- **绑定到调用会话** - 通过 `CLAUDE_CODE_SESSION_ID` 驱动*此* Claude Code 会话（[PR #91](https://github.com/Pher217/OpenRemote-Control/pull/91)）
- **作用域编辑器回合镜像**，带有驱动抑制，以便输入编辑器回合和聊天驱动的回合永远不会重复发布（[PR #93](https://github.com/Pher217/OpenRemote-Control/pull/93)，[PR #94](https://github.com/Pher217/OpenRemote-Control/pull/94)）
- **持久交互引擎** (`ORC_HEADLESS_ENGINE=interactive`) - 一个长寿命的 `claude -p` stream-json 进程，每个会话，温暖的多回合回复和重启生存（[PR #95](https://github.com/Pher217/OpenRemote-Control/pull/95)，[PR #96](https://github.com/Pher217/OpenRemote-Control/pull/96)）
- **机器人活跃度监视器**，以便捕获并重启卡住的 Telegram `getUpdates` 消费者（[PR #97](https://github.com/Pher217/OpenRemote-Control/pull/97)）
- **通用 MCP 桥** - `apps.connectors` 后端 + 可安装的 [`orc-mcp`](connectors/orc-mcp/README.md) 客户端
- **Telegram** 界面 + **消息网关** 连接器（→ WhatsApp / Slack / Discord / Signal / iMessage）
- **多主机** 后端 (`apps.hostlink`) + **主机守护进程客户端** (`host-agent`: `orc-host enroll | daemon`)
- **PTY 输入安全核心**，下一个里程碑在此基础上构建
**正在进行/下一步：**
- **部署运行手册**（docker-compose：后端 + 消息网关边车 + headscale；守护进程在第二台机器上）
- `orc run` - 批准门控远程终端（PTY）流式传输，在现有的输入安全核心基础上构建
- 每个连接器的密钥对身份强化（替换共享的承载令牌）在任何多用户使用之前
## 为什么与众不同
- **一站式服务** - 将所有代理、所有机器、所有工具集中到一个您已经使用的聊天收件箱中。无需新的应用程序，无需每个工具的仪表盘，无需上下文切换。
- **主权/自托管** - 无 SaaS，无托管中间人。会话、提示、批准和凭证保留在您拥有的硬件上。整个堆栈是开源的，可以自托管。
- **多主机** - 您的 MacBook、Windows 工作站和 Linux VPS 成为一个机队，一个收件箱。主机守护进程通过您的私有网络注册每台机器。
- **多运行时** - 今日 Claude Code（调度、镜像、驱动）；其他支持 MCP 的工具通过 `orc-mcp` 桥接；按提供商划分的驱动引擎正在路线图中。
- **双向，不只是查看器** - 代理询问，您回答；代理请求，您批准 - 直接在聊天中。
- **内置策略 + 批准 + 审计** - 敏感性感知项目配置文件，风险分级批准和追加 PostgreSQL 审计日志，适用于异构运行时。
- **您已经使用的界面** - 今日 Telegram；消息网关连接器扩展到 WhatsApp、Slack、Discord、Signal 和 iMessage。
## 它不是什么
- 一个新的 AI 代理
- Claude Code、Codex、Gemini、Cursor 或 Copilot 的替代品
- 一个托管的 SaaS、一个工作流构建器或一个 IDE
- 一个基于浏览器抓取的封闭供应商 UI 的包装器
如果一个工具无法通过 SDK 访问、导出会话文件或 MCP，则它不在范围内 - 没有脆弱的浏览器黑客。
## 试用桥梁
查看此功能的最快方法：连接一个工具，并让其代理通过您的聊天收件箱发送通知或询问问题。在运行后端的情况下，在任何支持 MCP 的工具中安装 [`orc-mcp`](connectors/orc-mcp/README.md）：
```bash
# Claude Code
claude mcp add orc -- orc-mcp
```
```toml
# OpenAI Codex CLI - ~/.codex/config.toml
[mcp_servers.orc]
command = "orc-mcp"
```
```json
// Cursor - ~/.cursor/mcp.json
{ "mcpServers": { "orc": { "command": "orc-mcp" } } }
```
设置 `ORC_BACKEND_URL` 和 `ORC_CONNECTOR_TOKEN`，代理可以访问您的聊天。完整的环境参考和其他工具在 [`orc-mcp` README](connectors/orc-mcp/README.md) 中。
## 快速入门（Docker）
最快的设置方法 - 一个命令将整个堆栈（后端、Postgres、Valkey、Telegram 机器人）启动并注册此机器的主机守护进程：
```bash
./quickstart.sh
```
您需要三样东西它无法为您做的事情：已安装的 Docker、来自 [@BotFather](https://t.me/BotFather) 的 Telegram 机器人令牌，以及一个启用了主题的 Telegram 群组（添加您的机器人为管理员）。脚本生成所有密钥，验证您的令牌，自动发现您的聊天，启动所有内容，并注册守护进程 - 然后您在 Claude Code 中运行 `/openremote-control`。有关手动/生产路径，请参见 [deploy/README.md](deploy/README.md)。
## 运行后端（开发）
```bash
# 用于测试/开发的 Postgres
docker run -d --name orc-pg \
-e POSTGRES_DB=openremote_control -e POSTGRES_USER=acc_user \
-e POSTGRES_PASSWORD=acc_password -p 5544:5432 postgres:16
cd backend
uv sync --extra dev
POSTGRES_PORT=5544 POSTGRES_HOST=localhost .venv/bin/python -m pytest -q
```
> **注意：** `acc_user` / `acc_password` 是临时本地开发凭证 - 它们**不是**生产密钥。通过环境设置真正的 `POSTGRES_PASSWORD`（和 `SECRET_KEY`）之前部署。
参见 [`docker-compose.yml`](docker-compose.yml) 和 [`Makefile`](Makefile) 以获取完整的开发循环。
## 堆栈
所有免费/开源友好：
- **后端** - Django 5.2，DRF，Channels，Celery 5
- **数据平面** - PostgreSQL 16，Valkey 8，追加审计日志
- **界面** - Telegram；消息网关连接器扩展到 WhatsApp、Slack、Discord、Signal 和 iMessage；用于编码代理的 MCP 桥
- **主机端** - Python 3.13 守护进程，Tailscale 连接性；headscale 是一个可选的部署路径（`deploy/headscale/`）；age-encrypted 凭证库，ntfy 推送和更快的-whisper 语音计划中
- **运维** - Docker Compose（开发），Caddy 2，OpenTelemetry → Loki + Tempo + Prometheus + Grafana
## 贡献
后端基础已经很稳固；目前最有用的贡献是关于**扩展到更多工具并将其投入使用**。最佳的第一份贡献：
- **添加每个提供商的驱动引擎或聊天界面。** 欢迎为每个提供商的驱动引擎和聊天界面做出贡献；打开一个讨论，描述工具的会话生命周期、身份验证模式和暴露的事件/钩子。
- **测试部署路径** 在您自己的自托管基础设施上，并报告文档不足的地方 - 运行手册现在正在编写中，实际世界的摩擦非常有价值。
- **改进 `orc-mcp` 安装文档**，适用于 Cursor、Codex、Claude Code、Copilot 和 Kiro。
- **加强安全边界** - 保险库、策略引擎、机密编辑器和批准流程在更改前进行设计审查；安全专家非常受欢迎。参见 [SECURITY.md](SECURITY.md) 和 [`docs/security/`](docs/security/)。
阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取工作流程、CI 和提交约定。一些早期的设计笔记仍然存在于维护者的私人知识库中；如果一个决定不明确，请打开一个问题，我们将把所需的上下文移到公共文档中。
## 许可证
[Apache-2.0](LICENSE) 用于代码。 [`docs/`](docs/) 中的文档双重许可为 CC-BY-SA 4.0 / Apache-2.0。
开放远程控制是一个独立的第三方项目，与Anthropic、OpenAI、Google或其他支持的工具供应商无关。根据Anthropic的Agent SDK指南，它不使用“Claude Code”名称或视觉样式；在UI中，Claude运行时被标记为“Claude Agent（SDK）”，“Claude（远程控制）”，“Claude（CLI）”或“Claude（观察到）”，具体取决于适配器。
