本章目标： 完成安装、打开控制台、创建 Waker 并发送第一条任务。已经能打开 Web Console 时，可直接创建 Waker。
系统要求与安装前检查
| 项目 | 建议 |
|---|
| 操作系统 | macOS 13.0+、主流 Linux 发行版、Windows 10+ |
| 内存 | 建议 4 GB+ |
| 磁盘空间 | 至少预留 500 MB |
| 网络 | 需要访问模型服务、代码仓库和所用连接器；企业网络需允许相关 HTTPS 出站连接 |
macOS / Linux 安装
macOS 可选择安装包或命令行；Linux 使用命令行。
方式一：通过安装包安装（macOS）
- 打开 QoderWake 官网。
- 选择「MacOS」，再按本机芯片选择「ARM64（Apple Silicon）」或「X64（Intel）」安装包。
- 下载并打开
.dmg，将 QoderWake 拖入「应用程序」。
- 从「应用程序」打开 QoderWake，按提示完成账号授权，等待服务启动并打开 Web Console。
方式二：通过命令行安装（macOS / Linux）
打开终端并执行：
curl -fsSL https://qoder-ide.oss-ap-southeast-1.aliyuncs.com/qoderwake/install.sh | bash
- 浏览器打开 Web Console，或终端打印控制台地址。
- 新终端执行
qoderwake status 能返回服务状态。
若提示找不到 qoderwake，重新打开终端；仍不可用时执行完整路径：
~/.qoderwake/bin/qoderwake login
Windows 安装
- 打开 QoderWake 官网，下载 Windows 安装程序（
.exe）。
- 双击安装程序，按向导完成安装和账号授权。
- 等待服务启动并打开 Web Console。
完成判断： 浏览器可以进入 Web Console，并且 Waker 管理页能够正常加载。若浏览器未自动打开，可从安装后的命令入口运行 qoderwake portal。
安装包名称会随版本变化，请始终从官网下载安装。如果安装后已经完成登录、服务启动并打开 Web Console，无需重复执行后面的登录和启动命令，可直接创建 Waker。
登录、检查账号与退出
浏览器授权登录
执行以下命令：
qoderwake login
qoderwake whoami
login。
完成判断：qoderwake whoami 显示当前账号，云端或远程功能不再提示登录。
使用令牌登录
无图形桌面或浏览器授权不可用时，可通过个人访问令牌（PAT）登录：
QODER_PERSONAL_ACCESS_TOKEN="你的令牌" \
~/.qoderwake/bin/qoderwake login --method token
qoderwake login --method file --token-file /path/to/token
qoderwake whoami。不要在截图、任务消息或仓库中保存真实令牌。
切换账号或退出
需要清除当前登录状态时执行：
切换账号时依次执行 logout、login 和 whoami，再刷新 Web Console。未登录时仍可使用本地模式；云端和远程能力需要有效账号。
启动服务并打开控制台
启动并打开
服务未启动时执行：
服务已运行时，打开 Web Console：
portal 会读取实际端口；默认地址为 http://127.0.0.1:19820，端口被占用时会自动顺延。
只打印实际地址、不自动打开浏览器：
qoderwake portal --no-open
portal --no-open 打印的地址可以访问。
查看状态、重启和停止
qoderwake status
qoderwake restart --open
qoderwake stop
qoderwake stop --force
| 命令 | 使用时机 | 结果判断 |
|---|
qoderwake status | 不确定服务是否运行 | 返回当前服务状态和相关信息 |
qoderwake restart --open | 页面异常、配置或版本更新后需要重启 | 服务重启并重新打开控制台 |
qoderwake stop | 正常停止后台服务 | 服务停止，但登录状态保留 |
qoderwake stop --force | 普通停止无效 | 强制停止，当前任务可能中断 |
停止或重启前，先确认是否有进行中的对话任务、自主工作或 WakerFlow。强制停止可能中断当前执行。
创建第一个 Waker
- 执行
qoderwake portal，进入「Waker 管理」，点击「新建 Waker」。
- 在角色市场选择最接近目标职责的预置角色；没有合适角色时选择「自定义 Waker」。
- 打开角色卡片，检查核心能力、工作风格、工作模式和预装 Skills，然后点击「就他了！」。
- 在「完善信息」页填写名称，核对“我负责什么”和运行环境；只保留首个任务确实需要的 Skills、知识库和连接器。
- 点击「创建 Waker」。
完成判断：
- 新 Waker 出现在 Waker 列表中。
- 卡片名称、简介、环境和状态正确。
如果「创建 Waker」不可点击，依次检查是否已经选择角色、填写名称并完成页面标记为必填的项目。
发起第一次对话任务
- 在新 Waker 卡片点击「创建对话任务」，确认对话页显示正确的 Waker。
- 涉及文件时选择正确的工作目录；需要时添加附件或
@ 引用上下文。
- 模型保持「Auto」，发送一个只读试运行任务，例如：
只读取当前目录的 README，不修改文件。
用 5 条以内的要点说明项目用途和启动方式；信息不足时明确指出。
- 发送任务；出现授权或确认时，核对操作内容后再处理。
- 等待最终回复，检查结果是否来自所选目录且没有超出要求。
完成判断：
- Waker 进入处理状态并最终返回结果。
- 结果来自所选目录或附件，且没有超出任务范围。
完成以上步骤后，安装、服务、账号、Waker 和对话任务主链路均已验证。
快速开始常见问题
| 现象 | 优先检查 | 建议处理 |
|---|
终端提示找不到 qoderwake | 新终端是否已加载命令路径 | 重新打开终端；必要时先使用 ~/.qoderwake/bin/qoderwake |
| 浏览器没有自动打开 | 终端是否打印地址 | 复制地址到浏览器，或执行 qoderwake portal --no-open |
| 默认地址无法访问 | 服务是否运行、实际端口是否变化 | 执行 qoderwake status 和 qoderwake portal |
| 云端或远程能力不可用 | 当前账号是否有效 | 执行 qoderwake whoami，必要时重新登录 |
| Waker 无法处理本地文件 | 是否选中了正确工作目录 | 回到输入区选择目录，再重新发起任务 |
