Claude Code CLI 与桌面端配置教程

Claude Code CLI 和 Claude Desktop 都可以接入 Xcompute，但当前版本使用两种不同的配置入口：CLI 修改 ~/.claude/settings.json，桌面端使用内置的 Configure Third-Party Inference 界面。

本教程只使用 Anthropic 官方 Claude Code、Claude Desktop 和系统自带文本编辑器。不需要安装 CC Switch 或其他切换、代理软件。

如果你不熟悉下载安装包、PowerShell、终端、命令或配置文件，请先阅读电脑基础使用扫盲。

先分清两套配置

使用方式	Xcompute 配置入口	适用范围
Claude Code CLI	`~/.claude/settings.json`	PowerShell、终端、IDE 中运行的 Claude Code
Claude Desktop	Developer > Configure Third-Party Inference	Claude Desktop 第三方推理模式
普通 Chat 标签	没有自定义 API 输入框	默认使用 Claude 官方服务

不要只修改 settings.json 后就认为桌面端已经接入。最新版 Claude Desktop 的 Gateway 路由使用独立的第三方推理配置，普通 Chat 登录模式也不会读取 ANTHROPIC_BASE_URL。

第一步：安装 Node.js

如果你已经按照 OpenCode 或 Codex 教程安装了 Node.js 24，执行 node -v 和 npm -v 能显示版本号，可以直接跳到下一步。

Windows
macOS
Linux

点击下载 Node.js 24 Windows 64 位 MSI，下载后双击安装，并使用默认选项完成安装。点击 开始菜单，输入 PowerShell 并打开，然后执行：

node -v
npm -v

点击下载 Node.js 24 macOS PKG，下载后双击安装，并按照界面提示完成安装。按 Command + 空格键，输入“终端”并打开，然后执行：

node -v
npm -v

Debian 或 Ubuntu 执行：

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

Fedora 或 RHEL 执行：

curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo dnf install -y nodejs

需要使用 NVM 或其他架构安装包时，请参考 OpenCode 安装教程中的 Node.js 章节。

第二步：安装 Claude Code CLI

Windows、macOS 和 Linux 都可以使用同一条 npm 命令：

npm install -g @anthropic-ai/claude-code

安装完成后验证：

claude --version

看到 Claude Code 版本号即表示安装成功。

备用：使用官方原生安装脚本

macOS、Linux 和 WSL 执行：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell 执行：

irm https://claude.ai/install.ps1 | iex

第三步：安装 Claude Desktop

桌面端是可选项。只使用 CLI 的用户可以直接跳到“创建 settings.json”。建议访问 Claude 官方下载页面获取最新版本，也可以使用下方官方入口：

系统	下载地址
macOS（Intel / Apple Silicon）	下载 Claude DMG
Windows（x64）	下载 Claude 安装程序
Windows（ARM64）	下载 Claude ARM64 安装程序
Linux（Beta）	查看官方 Linux 安装说明

macOS：打开 DMG，将 Claude 拖入 Applications 文件夹。
Windows：打开安装程序，按照界面提示完成安装。
Linux：按照官方页面选择 apt 或 DEB 安装方式。

Windows 的 Claude Desktop Code 标签需要 Git for Windows。如果尚未安装，请从 Git 官网下载并安装，然后完全退出并重新打开 Claude Desktop。

安装后打开 Claude Desktop。Code 标签首次运行时可能提示安装本地依赖：

公开教程中的 Claude Desktop Code 初始化界面，实际布局可能随版本更新。查看截图来源

第四步：在桌面端配置 Xcompute

Claude Desktop 的第三方 API 配置需要从登录页面进入开发者模式。不要先登录普通 Claude 账号。

1. 启用 Developer Mode

Windows
macOS

停留在 Claude Desktop 登录页面。
点击窗口左上角的菜单按钮 ☰。
选择 Help > Troubleshooting。
点击 Enable Developer Mode。

启用后，应用菜单中会出现 Developer。

2. 打开第三方推理配置

在应用菜单中依次点击：

Developer > Configure Third-Party Inference…

如果没有看到该菜单，请完全退出 Claude Desktop，重新打开后再次检查 Developer Mode 是否已经启用。

3. 填写 Gateway 信息

在配置窗口左侧选择 Connection，然后填写：

界面字段	填写内容
Inference provider	Gateway
Gateway base URL	`https://intl.dualseason.com`
Credential kind	Static API key
Gateway API key	你的 Xcompute API Key
Gateway auth scheme	Bearer

默认推荐 https://intl.dualseason.com。具备稳定科学上网能力时可以使用 https://xcompute.us。两个地址都不要添加 /v1，Claude Desktop 会自动请求 /v1/messages。

Xcompute 使用 Bearer 认证时，Gateway auth scheme 必须选择 Bearer。不要选择 x-api-key，除非你的 Xcompute 接口明确要求该方式。

4. 配置模型

如果桌面端能从 Xcompute 的 /v1/models 自动读取模型，模型列表会自动出现。如果没有出现，请在配置窗口的 Models 区域手动添加当前可用的 Claude 模型 ID，例如：

claude-sonnet-5
claude-opus-4-8
claude-fable-5

模型 ID 以 Xcompute 模型定价页面的当前列表为准。

5. 应用到本机

检查配置无误后，点击 Apply locally。Claude Desktop 会把第三方推理配置写入本机并重新启动。

Apply locally 用于当前电脑直接测试。Export 用于企业通过 MDM 批量部署，个人用户不需要导出 .mobileconfig 或 .reg 文件。

配置成功后进入 Code 标签，可以创建 Local 会话：

Claude Desktop Code 标签中的 Local 和 Cloud 会话入口

公开教程中的 Claude Desktop Code 会话界面。接入 Xcompute 后请选择本地项目和 Local 会话。查看截图来源

Gateway API Key 会保存在 Claude Desktop 的本机第三方推理配置中。不要截图展示配置窗口，也不要导出并分享包含密钥的配置文件。

第五步：为 CLI 创建 `settings.json`

Windows
macOS / Linux

点击 开始菜单，输入 PowerShell 并打开。复制下面两行，粘贴后按 Enter：

New-Item -ItemType Directory -Force "$HOME\.claude"
notepad "$HOME\.claude\settings.json"

记事本询问是否创建文件时选择是。保存时按 Ctrl+S。如果出现“另存为”，将 保存类型 改为 所有文件，确保文件名是 settings.json，而不是 settings.json.txt。

打开终端，执行：

mkdir -p ~/.claude
nano ~/.claude/settings.json

使用 nano 时，按 Ctrl+O 保存，按 Enter 确认，再按 Ctrl+X 退出。

不要把文件放进某个项目的 .claude 文件夹。本教程使用用户级 ~/.claude/settings.json 配置 CLI。Claude Desktop 的 Gateway 请使用上面的图形界面，不要依赖此文件。

第六步：写入 CLI 的 Xcompute 配置

将下面内容完整粘贴到 settings.json，把 在这里填写你的APIKey 替换为你的 Xcompute API Key：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://intl.dualseason.com",
    "ANTHROPIC_AUTH_TOKEN": "在这里填写你的APIKey",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5"
  }
}

默认推荐使用 https://intl.dualseason.com。如果你具备稳定的科学上网能力，可以改为 https://xcompute.us。Claude Code 使用 Anthropic 协议，Base URL 不要添加 /v1。

settings.json 包含明文 API Key。不要上传到 GitHub、发送给他人或在截图中展示。JSON 最后一项后面不能有逗号。

每个配置项有什么作用

配置项	作用
`ANTHROPIC_BASE_URL`	Xcompute 的 Anthropic 协议入口，不包含 `/v1`
`ANTHROPIC_AUTH_TOKEN`	你的 Xcompute API Key，以 Bearer Token 方式发送
`ANTHROPIC_MODEL`	启动时默认使用的模型
`ANTHROPIC_DEFAULT_SONNET_MODEL`	将 Sonnet 选项映射到 Xcompute 的 Sonnet 模型
`ANTHROPIC_DEFAULT_OPUS_MODEL`	将 Opus 选项映射到 Xcompute 的 Opus 模型
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	为后台轻量任务指定可用模型
`ANTHROPIC_DEFAULT_FABLE_MODEL`	将 Fable 选项映射到 Xcompute 的 Fable 模型

模型 ID 必须与 Xcompute 模型定价页面中显示的 ID 完全一致。可用模型变化时，请同步修改对应值。

第七步：启动并验证 CLI

保存 settings.json 后，完全退出之前打开的 Claude Code，再重新打开 PowerShell 或终端。进入你的项目目录并启动：

cd /path/to/your-project
claude

如果出现“使用检测到的 API Key”之类的提示，请确认使用该 Key。进入 Claude Code 后输入：

请告诉我当前使用的模型，并分析这个项目的目录结构，不要修改任何文件。

也可以输入 /status，检查当前 API provider、Base URL 和模型信息。

第八步：启动并验证桌面端

完全退出 Claude Desktop。
重新打开 Claude Desktop，确认第三方推理配置仍处于已应用状态。
点击 Code 标签。
新建会话时将 Environment 选择为 Local。
选择一个测试项目文件夹。
输入“分析这个项目，不要修改文件”。

能正常返回内容，说明 Claude Desktop 已通过 Xcompute Gateway 工作。

不要选择 Remote 或云端环境来测试 Xcompute。远程会话不会使用当前电脑上应用的第三方 Gateway 配置。

如何切换模型

Claude Code CLI

修改 settings.json 中的默认模型：

"ANTHROPIC_MODEL": "其他模型ID"

保存后重新打开 CLI。也可以在 CLI 中输入 /model，选择已映射的 Sonnet、Opus、Fable 等模型。

Claude Desktop

重新打开 Developer > Configure Third-Party Inference…，在 Models 区域调整模型列表，然后点击 Apply locally。应用重启后，在模型选择器中选择需要使用的模型。

更新 Claude Code

通过 npm 安装时，三个平台都执行：

npm update -g @anthropic-ai/claude-code
claude --version

原生安装版本会在后台自动更新。桌面端可以使用应用内更新，或重新访问官方下载页面。

常见问题

`claude` 命令不存在

关闭并重新打开 PowerShell 或终端，再执行：

node -v
npm -v
npm install -g @anthropic-ai/claude-code
claude --version

桌面端找不到 Third-Party Inference 菜单

退出当前登录，返回 Claude Desktop 登录页面。
打开 Help > Troubleshooting。
点击 Enable Developer Mode。
完全退出并重新打开应用。
在应用菜单中查找 Developer > Configure Third-Party Inference…。

Claude Desktop 无法连接 Xcompute

确认：

Inference provider 是 Gateway。
Gateway base URL 没有 /v1。
Credential kind 是 Static API key。
Gateway auth scheme 是 Bearer。
API Key 没有前后空格，并且账户有可用额度。
修改后点击了 Apply locally，并等待应用重新启动。

Claude Code CLI 提示未授权

ANTHROPIC_AUTH_TOKEN 没有前后空格。
API Key 仍然有效且账户有可用额度。
ANTHROPIC_BASE_URL 没有 /v1。
JSON 使用英文双引号，最后一项后面没有逗号。

以前使用过切换工具或本地代理

本教程不需要任何本地代理。CLI 的 ANTHROPIC_BASE_URL 和桌面端的 Gateway base URL 都不要使用 127.0.0.1 或 localhost。默认配置应直接指向：

"ANTHROPIC_BASE_URL": "https://intl.dualseason.com"

模型不存在或无法使用

前往模型定价页面检查模型 ID。模型名称必须完全一致，不能有多余空格。

​先分清两套配置

​第一步：安装 Node.js

​第二步：安装 Claude Code CLI

​第三步：安装 Claude Desktop

​第四步：在桌面端配置 Xcompute

​1. 启用 Developer Mode

​2. 打开第三方推理配置

​3. 填写 Gateway 信息

​4. 配置模型

​5. 应用到本机

​第五步：为 CLI 创建 settings.json

​第六步：写入 CLI 的 Xcompute 配置

​每个配置项有什么作用

​第七步：启动并验证 CLI

​第八步：启动并验证桌面端

​如何切换模型

​Claude Code CLI

​Claude Desktop

​更新 Claude Code

​常见问题

​claude 命令不存在

​桌面端找不到 Third-Party Inference 菜单

​Claude Desktop 无法连接 Xcompute

​Claude Code CLI 提示未授权

​以前使用过切换工具或本地代理

​模型不存在或无法使用

​官方资源

先分清两套配置

第一步：安装 Node.js

第二步：安装 Claude Code CLI

第三步：安装 Claude Desktop

第四步：在桌面端配置 Xcompute

1. 启用 Developer Mode

2. 打开第三方推理配置

3. 填写 Gateway 信息

4. 配置模型

5. 应用到本机

第五步：为 CLI 创建 `settings.json`

第六步：写入 CLI 的 Xcompute 配置

每个配置项有什么作用

第七步：启动并验证 CLI

第八步：启动并验证桌面端

如何切换模型

Claude Code CLI

Claude Desktop

更新 Claude Code

常见问题

`claude` 命令不存在

桌面端找不到 Third-Party Inference 菜单

Claude Desktop 无法连接 Xcompute

Claude Code CLI 提示未授权

以前使用过切换工具或本地代理

模型不存在或无法使用

官方资源