第 02 章

安装与登录

十分钟把 Qoder CLI 装到电脑上，并完成身份认证

装得起来，才用得上——这一步走顺，后面全是坦途

上一章我们理解了 CLI 是什么、它和 IDE 如何互补。现在把它装到你的电脑上。

卡在第一步

很多人对命令行工具有畏难情绪，其实就卡在"怎么装"

不知道选哪种

官网给了 curl、Homebrew、npm 三种安装方式，新手不知道该选哪个，怕选错。

登录流程陌生

第一次启动提示要登录，不知道用什么账号、Token 从哪来、要不要付费。

报错没人问

命令执行失败，红字一串，不知道是网络问题、权限问题还是命令写错了。

本章的目标：让你无论在 macOS、Linux 还是 Windows 上，都能选对方法、一次装好、顺利登录，并知道遇到报错怎么自救。

开始之前

确认你的系统在支持范围内

项目支持情况
操作系统macOS、Linux、Windows（推荐 Windows Terminal）
CPU 架构arm64、amd64 均可
暂不支持Windows arm64 架构
账号需要 Qoder 账号（可免费注册，含 Pro 试用）
还没账号？在 qoder.com 用 Google 或 GitHub 一键注册，新用户通常有免费 Pro 试用期，足够你跟完整门课。

三种安装方式

同一个工具，三条路径，按你的环境选

curl 脚本安装

官方推荐，几乎所有系统通用。一行命令下载并安装二进制，不需要预装 Node 或包管理器。不确定就选它。

Homebrew（macOS/Linux）

如果你已经用 brew 管理软件，用它能和系统其他工具统一升级。brew install 一条搞定。

npm 安装

需要预装 Node.js 环境。适合前端开发者，能和已有的 npm 工具链共存。

选择建议：三者装的是同一个 qodercli 程序，功能完全一样。区别只在"怎么管理升级"。新手优先 curl，已有 brew/npm 的用各自生态的方式。

curl 安装

一行命令，覆盖 macOS、Linux、Windows

macOS / Linux：

curl -fsSL https://qoder.com/install | bash

Windows PowerShell：

irm https://qoder.com/install.ps1 | iex

Windows CMD：

curl -fsSL https://qoder.com/install.cmd -o install.cmd && install.cmd

脚本会自动识别你的系统和架构，下载对应的二进制，放到合适的路径下，并配置好环境变量。

权限提醒：macOS / Linux 上如果提示 Permission denied，说明脚本没有执行权限，可以先下载再手动运行；Windows 上如果 PowerShell 拦截了脚本执行，用管理员身份打开 PowerShell 再试，或临时调整执行策略。

brew 与 npm

如果你已经在用这两个包管理器

Homebrew（macOS / Linux）

brew install qoderai/qoder/qodercli --cask

之后用 brew upgrade 统一升级，和系统其他软件一起管理。适合重度 brew 用户。

卸载也方便：brew uninstall qodercli。

npm（需要 Node.js）

npm install -g @qoder-ai/qodercli

-g 表示全局安装，装完后任何目录都能用 qodercli。适合前端/Node 开发者。

需要 Node.js 环境。如果提示 npm: command not found，先装 Node.js 再回来。

验证 Node 是否已装：运行 node --version，能打印出版本号（如 v20.x）就说明已就绪。没有的话，去 nodejs.org 下载安装。

验证安装

装完一定要验证——别假设它成功了

安装完成后，新开一个终端窗口（让环境变量生效），运行版本检查命令：

$ qodercli --version
0.1.21

如果打印出类似 0.1.21 的版本号，说明安装成功，可以进入下一步登录。

常见错误：command not found

症状：终端提示 qodercli: command not found。

原因：安装路径没有加进系统的 PATH 环境变量，或者没有新开终端窗口。

修复：① 关闭当前终端，重新打开一个再试；② 如果还是不行，确认安装时输出的路径，手动加到 .bashrc / .zshrc / 系统环境变量里；③ npm 全局安装的用户，运行 npm config get prefix 看全局目录是否在 PATH 中。

三种登录方式

认证的本质是告诉 CLI"你是谁、有没有权限"

Qoder CLI 在使用前必须完成身份验证。官方提供三种方式，适用场景不同：

方式适用场景是否交互
浏览器登录本地日常使用（推荐）是
Personal Access Token无法弹浏览器的环境是
环境变量CI/CD、自动化脚本否
新手请直接用浏览器登录。另两种方式等你在第 14 章接触 CI/CD 时再用，本章先讲清楚原理备用。

浏览器登录

最简单的认证方式，本地开发首选

进入任意项目目录（建议用全英文路径），启动 CLI：

$ cd ~/projects/my-app
$ qodercli

第一次启动会提示登录，在交互界面输入：

/login

选择 Login with browser，CLI 会在你的默认浏览器打开登录页面，完成授权后自动回到终端——这就登录好了。

常见错误：路径含中文导致启动失败

症状：启动时报错或直接退出。

原因：项目路径里含有中文字符，部分系统对中文路径支持不好。

修复：把项目目录改成全英文路径（如 D:\workspace\my-app），再重新启动。

Token 与环境变量

给服务器和自动化场景准备的认证方式

Personal Access Token

在 /login 时选择 Login with qoder personal access token，把 Token 粘贴进终端即可。

Token 在这里获取：

https://qoder.com/account/integrations

适合无法弹出浏览器的远程服务器、SSH 会话。

环境变量（自动化）

设置环境变量，CLI 启动时自动读取，无需交互：

# Linux / macOS
export QODER_PERSONAL_ACCESS_TOKEN="你的token"

# Windows CMD
set QODER_PERSONAL_ACCESS_TOKEN="你的token"

适合 CI/CD 流水线，把 Token 存进流水线密钥。

优先级规则：如果同时设置了 /login 登录和环境变量，以 /login 提供的 Token 为准。登出环境变量登录前，必须先清除环境变量。

升级机制

默认自动升级，也可以手动控制

Qoder CLI 默认开启自动升级，新版本发布后会自动更新，你通常不用管。

需要手动升级时，用对应安装方式的命令：

# curl 方式强制重装最新版
curl -fsSL https://qoder.com/install | bash -s -- --force

# 内置更新命令（任意安装方式都可用）
qodercli update

关闭自动升级

在某些受控环境（如企业内网）你不想自动升级，可以在 ~/.qoder/settings.json 中关闭：

{
  "general": {
    "enableAutoUpdate": false
  }
}

改完后 CLI 不再自动更新，需要你手动 qodercli update。

登出与退出

两个容易混淆的命令，分清楚

命令作用使用场景
/logout 退出当前登录的 Qoder 账号 换账号、在公共机器上清理凭证
/quit 退出 TUI 交互界面 结束本次会话，下次还要继续用
环境变量登录的登出特别注意：如果你是通过 QODER_PERSONAL_ACCESS_TOKEN 环境变量登录的，必须先清除该环境变量，再运行 /logout，否则下次启动还是会自动登录。

排错指南

安装登录阶段的高频问题

curl 下载卡住或超时

原因：网络访问 qoder.com 不稳定，或企业网络拦截了脚本下载。

修复：配置代理（HTTPS_PROXY 环境变量），或改用 npm 安装绕过脚本下载环节。

浏览器登录后没反应

原因：浏览器和终端不在同一台机器（如 SSH 远程），回调无法到达终端。

修复：改用 Personal Access Token 方式登录。

Pro 试用到期无法切换模型

原因：新用户两周免费 Pro 试用到期后，账号回到免费版，不再支持某些模型。

修复：在 qoder.com 升级到 Pro / Pro+ / Ultra，或继续使用免费版支持的模型。

npm 全局安装后 command not found

原因：npm 全局 bin 目录不在 PATH 中。

修复：运行 npm bin -g 找到目录，加进 PATH；或改用 curl 安装。

排错指南

安装和登录中的高频问题

命令找不到：qodercli 不是内部或外部命令

原因：安装目录不在 PATH 中。修复：重启终端；手动将安装目录加入 PATH；或用绝对路径运行。

登录页面打不开

原因：无图形界面环境（SSH、CI 服务器）。修复：用 Token 方式登录（从 qoder.com/account/integrations 获取 PAT）；或设置环境变量 QODER_TOKEN。

Token 过期了怎么办

原因：Personal Access Token 有有效期。修复：重新生成 Token；运行 qodercli login 刷新；或在 CI 中用环境变量注入新 Token。

安装脚本被安全软件拦截

原因：curl | bash 触发安全策略。修复：手动下载二进制包；用 npm 安装；或临时关闭安全软件后重试。

动手练习

装好之后，做这三件事确认一切就绪

练习 1：验证版本

  • 运行 qodercli --version，记下版本号
  • 如果版本低于 0.1.x，用 qodercli update 升级

练习 2：完成登录

  • 在一个全英文路径的项目目录下启动 qodercli
  • 用浏览器方式完成登录
  • 运行 /status，确认显示账号信息和连通状态

练习 3：查看帮助

  • 在 TUI 里输入 /help，浏览所有可用命令
  • 不用记，先有个印象——后面章节会逐个讲
完成这三步，你就拥有了可用的 Qoder CLI。下一章我们正式学习怎么和它对话。

本章回顾

带走的三个核心认知

安装选型

curl 通用、brew/npm 适合已有生态。装的是同一个程序，按环境选即可。

登录方式

本地用浏览器登录，服务器用 Token，CI 用环境变量。新手先用浏览器。

自动升级

默认开启，可在 settings.json 关闭。手动升级用 qodercli update。

核心结论：安装登录是门槛最低、却最容易让人放弃的一步。走通它，你已经赢过一半人。接下来真正有趣的——和 AI 对话——才刚开始。

下一章，学习 Qoder CLI 的五种输入模式，掌握和它高效沟通的全部姿势。

延伸阅读

继续本课程

官方资源