> ## 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.

# 快速开始

> 完成安装、打开控制台、创建 Waker 并发送第一条任务。包含系统要求、macOS / Linux / Windows 安装方式、登录、服务管理及常见问题。

本章目标：完成安装、打开控制台、创建 Waker 并发送第一条任务。已经能打开 Web Console 时，可直接跳到[创建第一个 Waker](#创建第一个-waker)。

## 系统要求与安装前检查

| 项目   | 建议                                       |
| ---- | ---------------------------------------- |
| 操作系统 | macOS 13.0+、主流 Linux 发行版、Windows 10+     |
| 内存   | 建议 4 GB+                                 |
| 磁盘空间 | 至少预留 500 MB                              |
| 网络   | 需要访问模型服务、代码仓库和所用连接器；企业网络需允许相关 HTTPS 出站连接 |

安装前确认当前用户可以安装程序、启动后台服务并访问目标工作目录。

## 安装

<Tabs>
  <Tab title="macOS">
    macOS 可选择安装包或命令行方式安装。

    ### 方式一：通过安装包安装

    1. 打开 [QoderWake 官网](https://qoder.com.cn/qoderwake)。
    2. 选择「MacOS」，再按本机芯片选择「ARM64（Apple Silicon）」或「X64（Intel）」安装包。
    3. 下载并打开 `.dmg`，将 QoderWake 拖入「应用程序」。
    4. 从「应用程序」打开 QoderWake，按提示完成账号授权，等待服务启动并打开 Web Console。

    ### 方式二：通过命令行安装

    打开终端并执行：

    ```bash theme={null}
    curl -fsSL https://qoder-ide.oss-ap-southeast-1.aliyuncs.com/qoderwake/install.sh | bash
    ```

    执行期间不要关闭终端；出现授权页面时，完成授权后返回终端等待结束。

    **完成判断：**

    * 浏览器打开 Web Console，或终端打印控制台地址。
    * 新终端执行 `qoderwake status` 能返回服务状态。

    若提示找不到 `qoderwake`，重新打开终端；仍不可用时执行完整路径：

    ```bash theme={null}
    ~/.qoderwake/bin/qoderwake login
    ```
  </Tab>

  <Tab title="Linux">
    打开终端并执行：

    ```bash theme={null}
    curl -fsSL https://qoder-ide.oss-ap-southeast-1.aliyuncs.com/qoderwake/install.sh | bash
    ```

    执行期间不要关闭终端；出现授权页面时，完成授权后返回终端等待结束。

    **完成判断：**

    * 浏览器打开 Web Console，或终端打印控制台地址。
    * 新终端执行 `qoderwake status` 能返回服务状态。

    若提示找不到 `qoderwake`，重新打开终端；仍不可用时执行完整路径：

    ```bash theme={null}
    ~/.qoderwake/bin/qoderwake login
    ```
  </Tab>

  <Tab title="Windows">
    1. 打开 [QoderWake 官网](https://qoder.com.cn/qoderwake)，下载 Windows 安装程序（`.exe`）。
    2. 双击安装程序，按向导完成安装和账号授权。
    3. 等待服务启动并打开 Web Console。

    **完成判断：** 浏览器可以进入 Web Console，并且 Waker 管理页能够正常加载。若浏览器未自动打开，可从安装后的命令入口运行 `qoderwake portal`。
  </Tab>
</Tabs>

<Note>
  安装包名称会随版本变化，请始终从官网下载安装。如果安装后已经完成登录、服务启动并打开 Web Console，无需重复执行后面的登录和启动命令，可直接创建 Waker。
</Note>

## 登录、检查账号与退出

### 浏览器授权登录

执行以下命令：

```bash theme={null}
qoderwake login
qoderwake whoami
```

在浏览器完成授权；浏览器未打开时，复制终端打印的地址。授权超时后重新执行 `login`。

**完成判断：** `qoderwake whoami` 显示当前账号，云端或远程功能不再提示登录。

### 使用令牌登录

无图形桌面或浏览器授权不可用时，可通过个人访问令牌（PAT）登录：

```bash theme={null}
QODER_PERSONAL_ACCESS_TOKEN="你的令牌" \
  ~/.qoderwake/bin/qoderwake login --method token
```

也可从文件读取令牌：

```bash theme={null}
qoderwake login --method file --token-file /path/to/token
```

登录后执行 `qoderwake whoami`。

<Warning>
  不要在截图、任务消息或仓库中保存真实令牌。
</Warning>

### 切换账号或退出

需要清除当前登录状态时执行：

```bash theme={null}
qoderwake logout
```

切换账号时依次执行 `logout`、`login` 和 `whoami`，再刷新 Web Console。未登录时仍可使用本地模式；云端和远程能力需要有效账号。

## 启动服务并打开控制台

### 启动并打开

服务未启动时执行：

```bash theme={null}
qoderwake start --open
```

服务已运行时，打开 Web Console：

```bash theme={null}
qoderwake portal
```

`portal` 会读取实际端口；默认地址为 `http://127.0.0.1:19820`，端口被占用时会自动顺延。

只打印实际地址、不自动打开浏览器：

```bash theme={null}
qoderwake portal --no-open
```

**完成判断：** 浏览器打开 Web Console，或 `portal --no-open` 打印的地址可以访问。

### 查看状态、重启和停止

```bash theme={null}
qoderwake status
qoderwake restart --open
qoderwake stop
qoderwake stop --force
```

| 命令                         | 使用时机              | 结果判断          |
| -------------------------- | ----------------- | ------------- |
| `qoderwake status`         | 不确定服务是否运行         | 返回当前服务状态和相关信息 |
| `qoderwake restart --open` | 页面异常、配置或版本更新后需要重启 | 服务重启并重新打开控制台  |
| `qoderwake stop`           | 正常停止后台服务          | 服务停止，但登录状态保留  |
| `qoderwake stop --force`   | 普通停止无效            | 强制停止，当前任务可能中断 |

<Warning>
  停止或重启前，先确认是否有进行中的对话任务、自动任务或 WakerFlow。强制停止可能中断当前执行。
</Warning>

## 创建第一个 Waker

<Steps>
  <Step title="打开 Waker 管理">
    执行 `qoderwake portal`，进入「Waker 管理」→「新建 Waker」。
  </Step>

  <Step title="选择角色">
    选择最接近目标职责的预置角色；没有合适角色时选择「自定义角色」。
  </Step>

  <Step title="填写信息">
    填写名称和简介，按需上传头像、选择运行环境。
  </Step>

  <Step title="保存并启用">
    点击「保存并启用」。
  </Step>
</Steps>

**完成判断：**

* 新 Waker 出现在「我的 Wakers」列表中。
* 卡片名称、简介、环境和状态正确。

如果「保存并启用」不可点击，依次检查是否已经选择角色、填写名称并完成页面标记为必填的项目。

## 发起第一次对话任务

<Steps>
  <Step title="进入对话">
    在新 Waker 卡片点击「创建对话任务」，确认 Chat 顶部显示正确的 Waker。
  </Step>

  <Step title="选择工作目录">
    涉及文件时选择正确的工作目录；需要时添加附件或 `@` 引用上下文。
  </Step>

  <Step title="发送试运行任务">
    模型保持「Auto」，发送一个只读试运行任务，例如：

    ```text theme={null}
    只读取当前目录的 README，不修改文件。
    用 5 条以内的要点说明项目用途和启动方式；信息不足时明确指出。
    ```
  </Step>

  <Step title="处理授权确认">
    发送任务；出现授权或确认时，核对操作内容后再处理。
  </Step>

  <Step title="验证结果">
    等待最终回复，检查结果是否来自所选目录且没有超出要求。
  </Step>
</Steps>

**完成判断：**

* Waker 进入处理状态并最终返回结果。
* 结果来自所选目录或附件，且没有超出任务范围。

完成以上步骤后，安装、服务、账号、Waker 和 Chat 主链路均已验证。

## 快速开始常见问题

| 现象                  | 优先检查            | 建议处理                                       |
| ------------------- | --------------- | ------------------------------------------ |
| 终端提示找不到 `qoderwake` | 新终端是否已加载命令路径    | 重新打开终端；必要时先使用 `~/.qoderwake/bin/qoderwake` |
| 浏览器没有自动打开           | 终端是否打印地址        | 复制地址到浏览器，或执行 `qoderwake portal --no-open`  |
| 默认地址无法访问            | 服务是否运行、实际端口是否变化 | 执行 `qoderwake status` 和 `qoderwake portal` |
| 云端或远程能力不可用          | 当前账号是否有效        | 执行 `qoderwake whoami`，必要时重新登录              |
| Waker 无法处理本地文件      | 是否选中了正确工作目录     | 回到输入区选择目录，再重新发起任务                          |