# 远程 Shell (Conch)

Agora 可以通过 [Conch](https://github.com/newo-ether/conch) 协议在远程机器上执行命令——一个专为 AI 代理设计的端到端加密安全 Shell。

## 工作原理

```text
Agora (Android)  ──ECDH + AES-256-GCM──▶  Conch Server (Linux/macOS/Windows)
                                           │
                                           ├── 执行命令
                                           ├── 读/写/编辑文件
                                           ├── Glob 和 grep 搜索
                                           └── 返回结果
```

模型自行决定何时使用 Shell——它可以检查服务器状态、管理文件、运行脚本或自主排查问题。

## 安全

Conch 使用强加密和反滥用保护：

- **ECDH 密钥交换** — 每会话临时密钥
- **AES-256-GCM 加密** — 所有流量加密
- **HMAC-SHA256 签名** — 消息完整性验证
- **令牌桶速率限制** — 防止滥用
- **基于 Nonce 的防重放** — 每个请求唯一

!!! note
    命令以运行 Conch 服务器的用户权限执行。对敏感环境使用受限用户账户。

---

## 设置

### 第一步：部署 Conch 服务器

在目标机器上部署 Conch 服务器。详见 [Conch 仓库](https://github.com/newo-ether/conch) 的安装说明。

### 第二步：在 Agora 中添加设备

1. 前往 **设置 → Shell**
2. 启用 **Shell 工具**
3. 点按 **添加设备**
4. 选择设备类型：**Conch** 或 **SSH**
5. 填写设备详情：

=== "Conch"

    | 字段 | 描述 | 示例 |
    |-------|-------------|---------|
    | **名称** | 此设备的显示名称 | `构建服务器` |
    | **描述** | 关于此机器的可选备注 | `办公室 Ubuntu 机` |
    | **服务器 URL** | Conch 服务器端点（主机:端口） | `http://192.168.1.100:14216` |
    | **API 密钥** | 认证令牌 | 来自 Conch 服务器配置 |
    | **超时** | 命令超时（秒） | `30` |

=== "SSH"

    | 字段 | 描述 | 示例 |
    |-------|-------------|---------|
    | **名称** | 此设备的显示名称 | `VPS 服务器` |
    | **描述** | 关于此机器的可选备注 | `生产 Web 服务器` |
    | **主机** | SSH 主机名或 IP 地址 | `192.168.1.200` |
    | **端口** | SSH 端口 | `22` |
    | **用户** | SSH 用户名 | `root` |
    | **密码** | SSH 密码 | 你的 SSH 密码 |

点按 **添加** 保存。

### 第三步：使用

配置完成后，模型即可访问设备。无需手动触发——模型自动发现可用的 Shell 设备并在适当时调用。

---

## 多设备支持

添加多个 Shell 设备让模型跨机器工作：

- **构建服务器** — 编译和测试代码
- **家庭实验室** — 管理自托管服务
- **开发虚拟机** — 编辑代码和运行脚本

每个设备独立配置自己的名称、URL 和凭证。模型可以区分它们并为每个任务选择合适的设备。

---

## 可用操作

### 命令执行 (`shell_execute`)

运行任意 Shell 命令并接收 stdout、stderr 和退出码。

### 文件操作

| 工具 | 功能 |
|------|----------|
| `file_read` | 读取远程文件系统中的文件 |
| `file_write` | 写入或覆盖文件 |
| `file_edit` | 在文件中执行精确字符串替换 |
| `file_glob` | 按 glob 模式查找文件 |
| `file_grep` | 用正则表达式搜索文件内容 |

所有文件操作通过加密的 Conch 通道进行。

---

## MCP 集成

Conch 也可以作为 **Claude Desktop MCP 服务器**。如果你使用 Claude Code 或其他 MCP 客户端，可以将 Conch 配置为工具提供者，用于远程文件和 Shell 访问。

详见 [Conch 文档](https://github.com/newo-ether/conch) 的 MCP 设置说明。

---

## 故障排除

### 设备显示为不可用
- 检查 Conch 服务器是否在运行
- 验证 URL 是否可从 Android 设备访问
- 检查服务器上的防火墙规则

### 命令超时
- 在设备设置中增加超时值
- 检查命令是否挂起（需要用户输入等）

### 认证失败
- 验证 API 密钥与服务器配置匹配
- 必要时重新生成密钥
