快速开始

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

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

​

系统要求与安装前检查

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

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

​

安装

macOS

macOS 可选择安装包或命令行方式安装。

​

方式一：通过安装包安装

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

​

方式二：通过命令行安装

打开终端并执行：

curl -fsSL https://qoder-ide.oss-ap-southeast-1.aliyuncs.com/qoderwake/install.sh | bash

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

完成判断：

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

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

~/.qoderwake/bin/qoderwake login

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

1. 打开 QoderWake 官网，下载 Windows 安装程序（.exe）。
2. 双击安装程序，按向导完成安装和账号授权。
3. 等待服务启动并打开 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。

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

​

切换账号或退出

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

qoderwake logout

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

​

启动服务并打开控制台

​

启动并打开

服务未启动时执行：

qoderwake start --open

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

qoderwake portal

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

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

qoderwake portal --no-open

完成判断： 浏览器打开 Web Console，或 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

1. 打开 Waker 管理

   执行 qoderwake portal，进入「Waker 管理」→「新建 Waker」。

2. 选择角色

   选择最接近目标职责的预置角色；没有合适角色时选择「自定义角色」。

3. 填写信息

   填写名称和简介，按需上传头像、选择运行环境。

4. 保存并启用

   点击「保存并启用」。

完成判断：

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

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

​

发起第一次对话任务

1. 进入对话

   在新 Waker 卡片点击「创建对话任务」，确认 Chat 顶部显示正确的 Waker。

2. 选择工作目录

   涉及文件时选择正确的工作目录；需要时添加附件或 @ 引用上下文。

3. 发送试运行任务

   模型保持「Auto」，发送一个只读试运行任务，例如：

   只读取当前目录的 README，不修改文件。
   用 5 条以内的要点说明项目用途和启动方式；信息不足时明确指出。
   
4. 处理授权确认

   发送任务；出现授权或确认时，核对操作内容后再处理。

5. 验证结果

   等待最终回复，检查结果是否来自所选目录且没有超出要求。

完成判断：

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

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

​

快速开始常见问题

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