> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Mode

`--remote` 模式让你的 Qoder CLI 任务直接在 Qoder 管理的云端虚拟机中执行，本地电脑无需保持开机或处于活跃状态。从下发指令到结果产出的全流程都托管在云端，本地终端仅作为入口。

> 与已有的 [Remote Control](https://docs.qoder.com/zh/cli/remote-control) 模式互补。

## 适用场景

* **长时任务**：训练、批量重构、大规模代码审查，本地电脑不便长时间占用。
* **离线发起**：飞机上、地铁上写一个 prompt，回来再看结果。
* **统一环境**：团队成员共享一致的依赖与工具集，避免「在我电脑上能跑」。
* **资源隔离**：云端 VM 提供独立的 CPU / 内存 / 网络配额，不与本机争抢。

## 快速开始

### 1. 在云端发起一次任务

在终端中直接传入 `--remote` 参数：

```bash theme={null}
qodercli --remote "review the auth middleware in src/middleware and suggest improvements"
```

<Note>
  如果执行时报 `Cannot find package` 错误，请改用 [HTTP API 快速开始](/zh/cloud-agents/quickstart) 通过 curl 直接调用 Cloud Agents API。
</Note>

执行后 CLI 会：

1. 在选定的远程环境中创建一个新的云端会话 (Cloud Session)。
2. 把任务描述发送到云端 Agent。
3. 实时把云端 Agent 的输出（思考、工具调用、最终结果）流式打印到本地终端。
4. 任务完成后，本地终端打印会话 URL，可在 Web 端继续追溯：

```plaintext theme={null}
Cloud remote session created.
Session ID: qs_01krxhzz******351vhya
Environment: Default (env_01kqs75n******6x6hmj53ds)
URL: https://qoder.com/agents/session/qs_01krxhzz******351vhya
```

任务发起后即使关闭本地终端，云端 Agent 仍然继续执行；下次重新打开 CLI 或访问 Web 控制台即可恢复进度。

### 2. 用 /remote-env 选择云端执行环境

在已有的 qodercli 交互式会话中输入：

```plaintext theme={null}
/remote-env
```

CLI 会弹出环境选择器：

```plaintext theme={null}
Remote Environment

Select the default cloud environment.

❯ 1. Default
  2. Sessions: test · Network: trusted
```

选定后会写入用户级配置 `~/.qoder/settings.json`：

```json theme={null}
{
  "remote": {
    "defaultCloudEnvironmentId": "env_01kq********hmj53ds"
  }
}
```

之后所有 `--remote` 调用都会复用这个默认环境，无需每次重新选择。

## 命令参考

### `qodercli --remote "<task>"`

| 项目           | 说明                                                      |
| ------------ | ------------------------------------------------------- |
| 作用           | 从 CLI 发起一次云端会话，在 Qoder 管理的 VM 中执行任务                     |
| 上下文          | 不依赖本地工作目录，所有读写发生在云端环境中                                  |
| 中断行为         | 本地按 `Ctrl+C` 仅断开终端订阅，云端任务继续执行                           |
| 需要登录         | 是（首次使用会触发 `qodercli login`）                             |
| 需要 Github 授权 | 需要授权 Qoder 对应 Github 仓库的权限（Qoder 官网 > 服务集成 > Github 集成） |

**示例**：

```bash theme={null}
# 基本用法
qodercli --remote "summarize the latest 50 PRs in this repo"
```

### `/remote-env`

| 项目   | 说明                                      |
| ---- | --------------------------------------- |
| 触发位置 | 仅在 qodercli 交互式会话中可用（输入 `/` 后选择）        |
| 作用   | 选择 / 切换 / 创建云端执行环境，作为 `--remote` 的默认值   |
| 影响范围 | 用户级（写入 `~/.qodercli/config.json`），多终端共享 |

## 常见问题

**Q：本地未保存的修改，可以在 `--remote` 模式中读取吗？**

不能。`--remote` 任务运行在云端独立 VM 中，访问的是当前环境对应的 Remote Github 的项目。

**Q：能在一台电脑上同时跑多个 `--remote` 任务吗？**

可以。每个 `--remote` 调用都会创建独立的云端 Session，互不影响。任务列表可在 [Cloud Agents 控制台](https://qoder.com/agents) 查看。

## 相关文档

* [Remote Control 使用指南](./remote-control)