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

# 安装与升级

<div id="requirements">
  # 环境要求
</div>

安装 Qoder CLI 前，请确认你的环境满足以下要求：

* **操作系统**：macOS、Linux、Windows（推荐使用 Windows Terminal）。
* **CPU 架构**：arm64、amd64。
* **Node.js**：使用 npm 安装时需要 Node.js >= 20.0.0。

> Windows (arm64) 暂时不支持。

<div id="install">
  # 安装
</div>

Qoder CLI 提供多种安装方式，你可以根据环境和习惯任选其一。

## 使用安装脚本（推荐）

安装脚本会自动下载与当前系统匹配的版本，并配置好可执行文件。

**macOS / Linux**

```shell theme={null}
curl -fsSL https://qoder.com/install | bash
```

**Windows PowerShell**

```shell theme={null}
irm https://qoder.com/install.ps1 | iex
```

**Windows CMD**

```shell theme={null}
curl -fsSL https://qoder.com/install.cmd -o install.cmd && install.cmd
```

## 使用 npm 安装

如果你已经安装了 Node.js（>= 20.0.0），可以直接通过 npm 全局安装：

```shell theme={null}
npm install -g @qoder-ai/qodercli
```

指定发布渠道：

```shell theme={null}
# 稳定版
npm install -g @qoder-ai/qodercli@latest

# Node 原生兼容版（beta）
npm install -g @qoder-ai/qodercli@beta
```

> `beta` 是 Node 原生兼容版的预览渠道，版本号可能低于稳定版。如无特殊需要，建议安装稳定版。

<div id="verify">
  # 验证安装
</div>

安装完成后，运行下列命令。如果打印出 CLI 版本号，则表示安装成功：

```shell theme={null}
qodercli --version
```

如果提示找不到命令，请检查安装目录是否已加入系统 `PATH`。相关排查步骤见 安装与升级问题。

<div id="first-run">
  # 首次运行
</div>

在任意项目根目录运行以下命令，即可进入默认的交互式（TUI）模式：

```shell theme={null}
qodercli
```

首次运行时，Qoder CLI 会引导你完成登录。登录方式详见 [登录与认证](/zh/cli/01-开始使用/auth)。

<div id="upgrade">
  # 升级
</div>

Qoder CLI 默认启用自动升级。你也可以随时手动升级到最新版本。

## 使用安装脚本升级

**macOS / Linux**

```shell theme={null}
curl -fsSL https://qoder.com/install | bash -s -- --force
```

**Windows PowerShell**

```shell theme={null}
irm https://qoder.com/install.ps1 | iex
```

**Windows CMD**

```shell theme={null}
curl -fsSL https://qoder.com/install.cmd -o install.cmd && install.cmd
```

## 使用内置更新命令

```shell theme={null}
qodercli update
```

## 使用 npm 升级

```shell theme={null}
npm install -g @qoder-ai/qodercli@latest
```

<div id="auto-update">
  # 自动升级设置
</div>

自动升级默认开启。要禁用自动升级，在 `~/.qoder/settings.json` 中把 `general.enableAutoUpdate` 设置为 `false`：

```json theme={null}
{
  "general": {
    "enableAutoUpdate": false
  }
}
```

配置文件的作用范围和生效顺序，见 配置文件与生效顺序。

<div id="uninstall">
  # 卸载
</div>

卸载方式取决于你的安装方式：

* **通过 npm 安装**：执行 `npm uninstall -g @qoder-ai/qodercli`。
* **通过安装脚本安装**：删除安装脚本放置的可执行文件，并从 `PATH` 中移除对应目录。

如果你希望同时清理配置和本地数据，可以删除配置目录（默认 `~/.qoder`）。删除前请确认其中没有需要保留的会话、记忆或设置。

> 配置目录位置可以通过 `QODER_CONFIG_DIR` 环境变量自定义，默认是 `~/.qoder`。如果你设置过该变量，请删除对应目录。