> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Qwen Code

> 了解如何配置 Qwen Code CLI、headless mode 和 IDE integrations，接入 siflow endpoint，并使用算秩模型完成编码任务。

[Qwen Code](https://github.com/QwenLM/qwen-code) 是阿里巴巴 Qwen 团队开源的 coding agent。它核心是交互式 CLI，同时支持 headless mode、VS Code、Zed、JetBrains 等 IDE integrations，以及基于其构建的 desktop app。它原生支持 OpenAI、Anthropic 和 Gemini protocols，因此可以直接连接到 siflow OpenAI-compatible endpoint。

以下配置适用于 Qwen Code 的所有形态。

通过 npm 安装 Qwen Code 需要 **Node.js 22 或更高版本**。如果安装后版本异常或 Qwen Code 无法启动，请先检查 `node --version`；使用低于 22 的 Node 安装可能会拉取 incomplete build。

## 配置

### 1. 安装 Qwen Code

先检查 Node 版本：

```bash theme={null}
node -v
```

如果版本低于 22，请升级 Node。[官方下载页面](https://nodejs.org/en/download) 覆盖各平台和安装方式。

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install node@24
  ```

  ```bash Windows (winget) theme={null}
  winget install OpenJS.NodeJS.LTS
  ```

  ```bash Linux/macOS (nvm) theme={null}
  nvm install 24 && nvm use 24
  nvm alias default 24
  ```
</CodeGroup>

<Warning>
  使用 nvm 时，请设置 default alias。否则新终端可能回退到旧 Node 版本，导致 npm 安装的命令从 `PATH` 中消失。
</Warning>

安装 Qwen Code：

```bash theme={null}
npm install -g @qwen-code/qwen-code@latest
# or
brew install qwen-code
qwen --version
```

### 2. 使用环境变量配置

在 [API 密钥](https://console.siflow.cn/model-inference/api_keys) 页面创建 API Key，然后将连接设置写入 Qwen Code 的 env file。该文件会在每次启动、每个终端中自动加载。

```bash theme={null}
mkdir -p ~/.qwen
cat >> ~/.qwen/.env <<'EOF'
OPENAI_API_KEY=<Your API Key>
OPENAI_BASE_URL=https://api.siflow.cn/model-api/v1
OPENAI_MODEL=glm-5.2
EOF
qwen
```

普通 `export` 命令也可使用，但只在当前 shell session 中有效。Qwen Code 会依次搜索 `.qwen/.env`、从当前目录向上查找的 `.env`、`~/.qwen/.env`、`~/.env`。项目级 `.qwen/.env` 可以让不同项目使用不同 key。

首次启动时，在 `/auth` dialog 中选择 provider。当前 UI 提供 **Alibaba ModelStudio**、**Third-party Providers** 和 **Custom Provider**。连接算秩请选择 **Custom Provider**。

### 3. 使用 `settings.json` 配置

如需持久配置，请先创建 config 目录，然后编辑 `~/.qwen/settings.json`：

```bash theme={null}
mkdir -p ~/.qwen
```

```json theme={null}
{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [
        {
          "id": "glm-5.2",
          "baseUrl": "https://api.siflow.cn/model-api/v1",
          "envKey": "SIFLOW_API_KEY"
        }
      ]
    }
  },
  "security": { "auth": { "selectedType": "openai" } },
  "model": { "name": "glm-5.2" }
}
```

将 key 存入 Qwen Code 的 env file：

```bash theme={null}
echo 'SIFLOW_API_KEY=<Your API Key>' >> ~/.qwen/.env
qwen
```

普通 `export SIFLOW_API_KEY="..."` 也可使用，但只在当前 shell session 中有效。新终端会丢失它，Qwen Code 会显示 "Missing credentials ... Set that environment variable"。

设置 `security.auth.selectedType` 后，Qwen Code 会直接进入已配置 provider，不再弹出 `/auth` dialog。

| 字段                                       | 说明                                                                      |
| ---------------------------------------- | ----------------------------------------------------------------------- |
| `modelProviders.openai.models[].id`      | 模型 ID，例如 `glm-5.2`。必须与 `model.name` 完全一致。                               |
| `modelProviders.openai.models[].baseUrl` | siflow OpenAI-compatible endpoint：`https://api.siflow.cn/model-api/v1`。 |
| `modelProviders.openai.models[].envKey`  | 保存 API Key 的环境变量。可选，默认是 `OPENAI_API_KEY`。                               |
| `security.auth.selectedType`             | 设置为 `openai`，默认使用该 provider。                                            |

<Warning>
  `model.name` 必须与 `modelProviders` 下的某个 `id` 完全一致。否则该模型不会出现在 `/model` 中。
</Warning>

`glm-5.2` 是推荐默认模型。如果需要更快响应，也可以选择支持原生 tool calling 的 `DeepSeek-V4-Flash`。

如果不想 export，也可以在 `settings.json` 中使用顶层 `"env": { "SIFLOW_API_KEY": "..." }` block。它优先级最低；shell exports 和 `.env` files 会覆盖它。项目级 `.qwen/settings.json` 会覆盖 home 目录中的配置。

## 验证

在交互模式中发送任务，例如 "list the current directory and summarize the project structure"，并确认 tool calls 和回复正常。

也可以 headless 验证：

```bash theme={null}
qwen -p "introduce yourself in one sentence, and name the model you're connected to"

# headless run that's allowed to edit files
# approval modes: plan / default / auto-edit / auto / yolo
qwen -p --approval-mode yolo "create a file named check.txt containing ok"
```

## VS Code Companion

Qwen Code 有官方 VS Code extension：**Qwen Code Companion**（`qwenlm.qwen-code-vscode-ide-companion`）。在 Qwen Code 中运行 `/ide install` 即可设置，也可以从 marketplace 安装后运行 `/ide enable`。

它会把 workspace context（例如 recent files、cursor position、selection）提供给 agent，并显示 native diff review。Zed 和 JetBrains integrations 也可用，参考 [官方 IDE integration docs](https://qwenlm.github.io/qwen-code-docs/en/users/ide-integration/ide-integration/)。