# Remote Cli

**Repository Path**: sunshinewithmoonlight/remote-cli

## Basic Information

- **Project Name**: Remote Cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-28
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# remote-cli

`remote-cli` 是一个把飞书机器人接到本机 AI 运行时的常驻服务。它可以把飞书消息送入 Codex 或 Claude Code，把回复实时回写到飞书；也可以通过远端 Agent 控制另一台可信设备，执行命令和传输文件。

如果你只想快速跑起来，看这份 README 就够了。更完整的系统设计、配置字段和排障细节见 [README.Architecture.md](README.Architecture.md)。

## 文档边界

- 当前入口：本文件，覆盖构建、最小配置、远端 Agent 基本用法和日常运维。
- 当前权威架构：[README.Architecture.md](README.Architecture.md)，覆盖组件边界、远端 Agent 身份模型、安全边界和排障口径。
- 历史/长文资料：`docs/` 下文档只作补充背景；若与本文件或架构文档冲突，以本文件和 `README.Architecture.md` 为准。

## 能做什么

- 飞书消息进入 Codex RPC 或 Claude Code 后端。
- 多个飞书 bot 可分别绑定不同后端和 `codex_home`。
- 回复默认以飞书交互式卡片回写，并持续 patch 当前回复。
- 支持 `/new` 开新会话、空闲自动续会话、可选历史恢复。
- 飞书附件可下载到本地运行时目录，并按配置决定是否立即处理。
- 支持系统任务：解析自然语言任务、安装为 macOS LaunchAgent、按时执行并回写飞书。
- 支持远端 Agent：可信设备主动连到 relay，控制端可 `list`、`exec`、`send-file`、`fetch-file`；Agent WebSocket 断线后会自动退避重连。

## 依赖

- macOS 或类 Unix 环境。
- Go 1.23+。
- `codex` CLI；如果使用 Claude 后端，还需要 `claude` CLI。
- 可用的飞书应用凭证。
- 可选：Cloudflare Workers relay，用于远端 Agent。

## 构建

```bash
make test
make build-all
make build-agent-release
```

输出：

```text
bin/remote-cli
bin/remote-agent
```

普通构建和 release 构建都输出到 `bin/`；项目不再使用 `dist/` 作为构建目录。

常用命令：

```bash
./bin/remote-cli --help
./bin/remote-cli agent --help
./bin/remote-agent --help
```

## 快速开始

1. 生成配置：

```bash
./bin/remote-cli config
```

`setup` 是等价别名：

```bash
./bin/remote-cli setup
```

2. 校验配置：

```bash
./bin/remote-cli --dry-run
```

3. 前台启动：

```bash
./bin/remote-cli
```

4. 检查健康：

```bash
./bin/remote-cli health
curl -fsS http://127.0.0.1:6230/readyz
```

5. 安装为 macOS 自启动服务：

```bash
./bin/remote-cli autorun
./bin/remote-cli status
./bin/remote-cli logs
```

默认配置路径是：

```text
~/.runtime/remote-cli.yaml
```

也可以显式指定：

```bash
./bin/remote-cli --config /path/to/remote-cli.yaml --dry-run
./bin/remote-cli autorun --config /path/to/remote-cli.yaml
```

## 最小配置示例

```yaml
port: 6230
codex_full_access: true
claude_full_access: true
main_chat_history_auto_resume: true
main_chat_auto_renew_idle_timeout_h: 24
main_chat_auto_compact_idle_timeout_h: 0

feishu-api:
  timeout_s: 8
  upload_timeout_s: 120

immediately-process:
  image: true
  file: false
  audio: true
  media: false

bots:
  - bot-type: feishu
    backend: codex
    codex_home: ""
    id: cli_xxx
    secret: "[REDACTED_FEISHU_SECRET]"

schedule:
  system_tasks_root: /absolute/path/for/system-tasks
```

切到 Claude Code 后端：

```yaml
claude-code:
  command: claude
  permission_mode: default
  include_partial_messages: true

bots:
  - bot-type: feishu
    backend: claude
    id: cli_xxx
    secret: "[REDACTED_FEISHU_SECRET]"
```

## 远端 Agent

远端 Agent 适合控制自己的可信设备。Agent 不开放公网入站端口，而是主动连出到 relay；`remote-cli` 控制端也主动连到 relay。公网链路按不可信处理，需要 relay key、relay 生成的在线身份、飞书 sender 白名单、审计日志和危险命令开关共同约束。

Remote Agent 不暴露飞书 `/ra` 聊天命令。飞书用户只发送自然语言请求，例如：

- "列出在线远程设备"
- "让 Mac mini 执行 pwd"
- "把这个文件发到远程 Mac 的 Downloads"

是否调用远程控制能力由后端 Agent/LLM 决定。后端和本地运维都通过 `remote-cli agent` CLI 调用控制能力。

推荐使用 `--url-key-env REMOTE_AGENT_RELAY_KEY` 从环境变量读取受控端 key，避免真实 key 出现在进程参数中。`--url-key` 参数名保留用于兼容，但它表示部署级 agent relay key，不是由飞书聊天创建的一次性 URL key。真实 key 必须通过 Worker secret、系统服务环境变量或受限权限环境文件注入，不写入 YAML、日志或文档。

控制端配置示例：

```yaml
remote-agent:
  enabled: true
  server-relay:
    cloudflare-workers-url: "wss://relay.example.com/"
    key: "control-relay-key-here"
    heartbeat_interval_s: 20
    request_timeout_s: 30
    command_timeout_s: 60
  access:
    allowed_sender_ids:
      - ou_xxx
    allow_any_sender: false
    allow_dangerous_commands: false
    max_output_bytes: 65536
```

`remote-agent.server-relay.key` 是 control relay key 明文。它只应写入本机受限权限的运行时 YAML，例如 `~/.runtime/remote-cli.yaml`；不要把真实 key 写入仓库示例、日志或 release 资产。

`remote-agent.server-relay.cloudflare-workers-url` 推荐填写 relay 根 URL，例如 `wss://relay.example.com/`。程序会自动补齐为控制端 WebSocket 路径 `/control/ws`；被控端 `remote-agent --url` 仍自动补齐到 `/agent/ws`。

被控设备启动 Agent：

```bash
./bin/remote-agent \
  --url relay.example.com \
  --url-key-env REMOTE_AGENT_RELAY_KEY \
  --hint "Mac mini at home"
```

`remote-agent --url` 可以只填写 relay host，例如 `relay.example.com`。程序会自动补齐为 `wss://relay.example.com/agent/ws`。仍兼容显式填写 `wss://relay.example.com/agent/ws`；不要把被控端指向 `/control/ws`。

Android/Termux note: `remote-agent` always uses `/system/bin/sh -c` as the direct child process on `GOOS=android`. This avoids Android/HarmonyOS cases where Go reports `os.Executable()` and `/proc/self/exe` as `/apex/com.android.runtime/bin/linker64`, and direct `fork/exec` of Termux private shells such as `/data/data/com.termux/files/usr/bin/fish` or `sh` can fail with `permission denied`. The existing `PATH` is preserved, so commands can still resolve Termux tools.

受控端认证和身份分离：

- `REMOTE_AGENT_RELAY_KEY` 只证明受控端允许接入 `/agent/ws`。
- `remote-agent` 不生成、不保存、不发送 `instance_id`。
- Worker relay 在 agent WebSocket 接入时生成 `instance_id`，派生当前在线连接的 `agent_id`。
- `remote-cli agent --json` 从 `agent_list` 中读取 `agent_id` / `instance_id`；后续控制命令仍使用 `agent_id`。
- 如果未传 `--hint`，`remote-agent` 会默认使用本机 hostname 作为展示名称；`--hint` 仍可显式覆盖该默认值。
- `hint` 只用于展示和调试，不参与认证、`agent_id` 或 `instance_id` 生成，也不作为稳定身份。

控制端 CLI：

```bash
./bin/remote-cli agent --json
./bin/remote-cli agent --uid agt_xxx --exec "pwd && uname -m" --json
./bin/remote-cli agent --uid agt_xxx --send-file ./local.txt --remote-path ~/Downloads/local.txt --json
./bin/remote-cli agent --uid agt_xxx --fetch-file ~/Downloads/local.txt --output /tmp/local.txt --json
```

## 系统任务

标准链路：

```bash
./bin/remote-cli task resolve --request '明天上午 9:30 给当前会话发送提醒' --json
./bin/remote-cli task create --task-dir /path/to/task_dir --json
```

`task resolve` 负责自然语言解析和草稿目录生成；`task create` 负责安装为系统任务。任务的真实状态以 bundle 文件和对应 LaunchAgent 为准。

## 日常运维

```bash
./bin/remote-cli start
./bin/remote-cli restart
./bin/remote-cli stop
./bin/remote-cli status
./bin/remote-cli logs
./bin/remote-cli service paths
```

健康检查优先看：

```bash
./bin/remote-cli health
curl -fsS http://127.0.0.1:6230/livez
curl -fsS http://127.0.0.1:6230/readyz
```

不要只用 pid、旧 tmux session 或历史 helper script 判断服务是否可用。

## 本地调试

注入一条模拟飞书入站消息：

```bash
./bin/remote-cli inject-feishu-text --text "请回复 pong"
```

发送飞书消息：

```bash
./bin/remote-cli send-feishu-text --text "hello"
./bin/remote-cli send-feishu-message --msg-type file --local-file /absolute/path/report.pdf --file-type stream
```

常用日志：

```text
/tmp/remote-cli/remote-cli.log
/tmp/remote-cli/remote-cli.error.log
/tmp/remote-cli/remote-cli.debug.log
```

## 更多文档

- [README.Architecture.md](README.Architecture.md)：架构、配置、远端 Agent、安全边界和排障。
- [docs/quick-deploy.md](docs/quick-deploy.md)：长版部署手册。
- [docs/technical-details/README.md](docs/technical-details/README.md)：历史设计和发布收束记录。