Claude Code 接入

这篇指南基于 Claude Code 官方文档整理，适合想在终端中直接使用 Xcompute 的开发者。内容分为三块：安装、接入、日常使用。

先理解 Claude Code 是什么

Claude Code 是 Anthropic 的编码 Agent。它能直接在终端里：

核心功能

功能	说明
代码生成	根据自然语言描述生成完整的代码实现
文件编辑	直接读取、修改、创建项目中的文件
终端操作	执行 shell 命令、运行测试、管理依赖
项目理解	自动索引项目结构，理解代码关系和上下文
Git 操作	提交代码、创建分支、解决合并冲突
调试排错	分析错误日志，定位并修复 bug
重构优化	大规模代码重构、性能优化建议

与传统的代码补全工具不同，Claude Code 拥有对整个项目的全局理解能力，能够跨文件分析和修改代码，就像一位经验丰富的工程师坐在你旁边。

系统要求

项目	最低版本	推荐版本
Node.js	v22.0.0	v22.x LTS
npm	v10+	最新稳定版
操作系统	macOS 12+ / Ubuntu 20.04+ / WSL2	最新稳定版
内存	4 GB	8 GB+
磁盘空间	500 MB	1 GB+

Claude Code 不支持原生 Windows（cmd / PowerShell），必须通过 WSL2 使用。

这篇文章会带你完成什么

你做完这篇后，应该能完成这几件事：

在本地安装 Claude Code
用 Xcompute 的 Base URL 和 API Key 接入
在你的项目目录里启动 Claude Code
执行第一次问答和第一次代码修改任务

安装方式

如果你还没有准备 Node 环境，先看 Node.js 开发环境准备。官方更推荐原生安装脚本，但如果你想和 Codex、OpenCode 统一走 Node 环境，也可以直接用 npm。

npm 安装（推荐本教程用这个）
官方原生安装

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

macOS / Linux / WSL:

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

Windows PowerShell:

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

安装后验证：

claude --version

如果能看到版本号，说明工具本身已经安装成功。如果安装遇到权限错误（EACCES）：

# 方法一：使用 sudo（macOS/Linux）
sudo npm install -g @anthropic-ai/claude-code

# 方法二：修改 npm 全局目录权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

各平台安装说明

macOS

# 如果使用 Homebrew 管理的 Node.js
brew install node@22
npm install -g @anthropic-ai/claude-code

Ubuntu / Debian

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

Windows (WSL2)

# 1. 先在 PowerShell 中安装 WSL2
wsl --install

# 2. 重启电脑后进入 WSL Ubuntu
wsl

# 3. 在 WSL 中安装 Node.js 和 Claude Code
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

接入 Xcompute

Claude Code 支持第三方 provider，这是接入 Xcompute 的关键。Xcompute 的 API 客户端会与 Anthropic Messages 协议进行转换，所以你只需要配置 Base URL 和 Key 即可。

了解渠道信息

配置项	值
Base URL	`https://xcompute.us`
加速入口	`https://intl.dualseason.com`
API Key 格式	`sk-xxxxxxxxxxxxxxxx`
协议	Anthropic Messages

渠道分组与折扣：

渠道名称	折扣	说明
GPT 福利渠道	0.9 折	超低价格，适合日常开发
Kiro 渠道	1.8 折	平衡价格与性能
官 Key 渠道	4.9 折	接近官方价格，稳定性最佳

三种配置方式

Mintlify 不支持嵌套 Tabs，这里列出三种方式，选择一种即可。 方式一：环境变量（推荐） — 优先级最高，最简单直接

# 永久写入配置（bash）
echo 'export ANTHROPIC_BASE_URL=https://xcompute.us' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的API密钥' >> ~/.bashrc
source ~/.bashrc

# 或如果你用 zsh（macOS 默认）
echo 'export ANTHROPIC_BASE_URL=https://xcompute.us' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的API密钥' >> ~/.zshrc
source ~/.zshrc

临时测试（当前终端有效）：

export ANTHROPIC_BASE_URL=https://xcompute.us
export ANTHROPIC_AUTH_TOKEN=sk-你的API密钥
claude

方式二：claude config 命令

claude config set anthropicBaseUrl https://xcompute.us
claude config set apiKey sk-你的API密钥
claude config list   # 查看当前配置

配置写入 ~/.claude/settings.json，可手动编辑。 配置文件目录结构：

~/.claude/
├── settings.json          # 全局设置（API Key、Base URL 等）
├── credentials.json       # 认证凭证
├── statsig.json           # 功能标记
└── projects/              # 项目级配置
    └── <project-hash>/
        └── settings.json  # 项目特定设置

方式三：手动编辑 settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://xcompute.us",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_XCOMPUTE_API_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-5"
  }
}

文件位置：

macOS / Linux：~/.claude/settings.json
Windows：C:\Users\你的用户名\.claude\settings.json

加速入口

如果 https://xcompute.us 延迟较高，可切换加速入口：

export ANTHROPIC_BASE_URL=https://intl.dualseason.com

两个入口使用相同 API Key，协议完全一致，均可正常使用。

对比项	标准入口	加速入口
URL	`https://xcompute.us`	`https://intl.dualseason.com`
协议	Anthropic Messages	Anthropic Messages
适用场景	默认使用	网络较慢时切换
API Key	通用	通用

模型选择

模型	特点	适用场景
`claude-sonnet-5`	速度与质量平衡	日常开发推荐
`claude-opus-4-8`	最强推理能力	复杂架构、疑难 bug
`claude-fable-5`	推理增强	复杂推理任务

验证连接

启动 Claude Code

claude

首次启动会显示欢迎界面，在 > 提示符后输入：

你好，请告诉我你是什么模型，以及你的 API 地址是什么？

如果配置正确，Claude 会回复当前模型信息和 API Base URL。

检查模型

/model

显示当前使用的模型信息。

连接检查清单

claude --version 正常输出版本号
echo $ANTHROPIC_BASE_URL 输出 https://xcompute.us
echo $ANTHROPIC_AUTH_TOKEN 输出你的 API Key
claude 可以正常启动并对话
/model 显示的模型名称正确

完整配置流程示例

从零开始，以 macOS 为例：

# 1. 确认 Node.js 版本
node --version          # 应 v22.x.x

# 2. 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 3. 验证安装
claude --version        # 应 Claude Code v1.x.x

# 4. 配置环境变量
echo 'export ANTHROPIC_BASE_URL=https://xcompute.us' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-你的API密钥' >> ~/.zshrc
source ~/.zshrc

# 5. 验证配置
echo $ANTHROPIC_BASE_URL   # 应 https://xcompute.us

# 6. 启动 Claude Code
claude

高级配置

多模型切换

# 启动时指定模型
claude --model claude-opus-4-8

# 运行时切换（在 Claude Code 界面中）
/model claude-sonnet-5

推荐创建别名（写入 ~/.zshrc 或 ~/.bashrc）：

alias cc-sonnet='claude --model claude-sonnet-5'
alias cc-opus='claude --model claude-opus-4-8'
alias cc-quick='claude --model claude-fable-5'

代理设置

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1

Xcompute 中转站通常不需要代理。代理主要在使用官方 API 时使用。

超时配置

export CLAUDE_CODE_TIMEOUT=180000   # 请求超时（毫秒）
export CLAUDE_CODE_CONNECT_TIMEOUT=30  # 连接超时（秒）

自定义 System Prompt

在项目根目录创建 CLAUDE.md，Claude Code 会自动读取作为上下文参考：

# 项目说明

这是一个 React + TypeScript 项目。

## 编码规范
- 使用函数式组件和 React Hooks
- 所有函数必须有 TypeScript 类型注解
- 组件文件使用 PascalCase 命名
- 工具函数使用 camelCase 命名

## 测试要求
- 修改代码后运行 npm test 验证
- 新功能必须添加单元测试

你也可以在子目录中创建项目级 CLAUDE.md，Claude Code 在访问该目录时会自动加载：

my-project/
├── CLAUDE.md              # 全局项目说明
├── src/
│   └── CLAUDE.md          # src 目录特定说明
└── tests/
    └── CLAUDE.md          # 测试目录特定说明

权限精细管理

claude config set permissions.allow "Read"
claude config set permissions.allow "Write:src/**"
claude config set permissions.deny "Bash:rm -rf *"
claude config set permissions.deny "Bash:sudo *"

对应 settings.json 配置：

{
  "permissions": {
    "allow": ["Read", "Write:src/**", "Bash:npm *", "Bash:git *"],
    "deny": ["Bash:rm -rf *", "Bash:sudo *"]
  }
}

管道输入用法

claude -p 支持非交互模式，适合脚本集成：

# 分析代码
cat src/app.ts | claude -p "分析这段代码的潜在问题"

# 审查 Git diff
git diff HEAD~3 | claude -p "审查这些变更，指出潜在问题"

# 日志分析
cat error.log | claude -p "分析错误日志，找出根因"

权限管理最佳实践

按项目设置权限：

cd my-project
claude config set --project permissions.allow "Read,Write:src/**,Bash:npm *,Bash:git *"

安全建议：

允许 Read 权限（只读是安全的）
允许 Bash:npm * 和 Bash:git *（常用且安全）
谨慎允许 Bash:*
始终禁止 Bash:rm -rf / 和 Bash:sudo *

实用工作流示例

新功能开发：

我需要为用户模块添加一个"忘记密码"功能。请先阅读现有的用户认证代码，
然后设计实现方案，包括 API 接口、前端页面和邮件发送逻辑。

Bug 修复：

用户反馈在提交表单时偶发 500 错误，错误日志如下：
[粘贴日志]
请帮我定位问题并修复。

代码重构：

请将 src/services/ 下所有使用 callback 的代码重构为 async/await 风格，
保持功能不变，添加适当的错误处理。

编写测试：

为 src/components/UserProfile.tsx 编写完整的单元测试，
覆盖正常流程和边界情况，使用 Jest + React Testing Library。

第一次正式使用：一步一步来

1. 进入你的项目目录

cd your-project

2. 启动 Claude Code

claude

3. 先做一个简单问题

请先告诉我这个仓库是做什么的

4. 再做一个低风险任务

请帮我找出这个项目的首页文件在哪里

5. 最后再让它改代码

请帮我在首页加一句欢迎文案

这样最不容易一下子把操作做复杂。

日常怎么用

1. 在项目目录中启动

cd your-project
claude

2. 让它解释代码

帮我解释一下这个仓库的认证流程

3. 让它修改代码

请在这个项目里增加一个登录失败重试提示

4. 常用命令

命令	说明
`/help`	显示帮助信息和所有可用命令
`/clear`	清除当前对话上下文
`/model`	查看或切换当前模型
`/config`	查看或修改配置
`/cost`	显示当前会话的 token 使用量和费用
`/compact`	压缩对话上下文（长对话时有用）
`/doctor`	诊断连接和配置问题
`/status`	显示当前状态信息
`/quit` 或 `/exit`	退出 Claude Code

常见问题

API 连接失败

Error: Failed to connect to API endpoint / ECONNREFUSED / ETIMEDOUT

排查步骤：

# 1. 检查环境变量
echo $ANTHROPIC_BASE_URL   # 应输出 https://xcompute.us

# 2. 测试网络连通性
curl -v https://xcompute.us
# 返回 401 说明连接正常，问题在 API Key

# 3. 检查 DNS 解析
nslookup xcompute.us

# 4. 尝试切换加速入口
export ANTHROPIC_BASE_URL=https://intl.dualseason.com

认证错误

Error: Authentication failed (401) / Invalid API key

排查步骤：

# 1. 确认 API Key 格式
echo $ANTHROPIC_AUTH_TOKEN   # 应以 sk- 开头

# 2. 检查是否有多余空格
echo -n "$ANTHROPIC_AUTH_TOKEN" | wc -c

# 3. 用 curl 直接测试
curl https://xcompute.us/v1/messages \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 10, "messages": [{"role": "user", "content": "Hi"}]}'

API Key 是从 Xcompute 平台获取的，不是 Anthropic 官方 Key，两者不通用。

模型不可用

Error: Model not found / Model not available

# 1. 确认模型名称完整
echo $ANTHROPIC_MODEL   # 应输出 claude-sonnet-5 等

# 2. 清除模型配置，使用默认
unset ANTHROPIC_MODEL
claude config remove model

# 3. 访问 Xcompute 控制台查看可用模型

常见错误：

错误写法	正确写法
`claude-sonnet-4`	`claude-sonnet-5`
`claude-4-opus`	`claude-opus-4-8`
`claude-4`	`claude-sonnet-5`

网络超时

Error: Request timed out / ETIMEDOUT after 30000ms

# 1. 切换到加速入口
export ANTHROPIC_BASE_URL=https://intl.dualseason.com

# 2. 增加超时
export CLAUDE_CODE_TIMEOUT=180000

# 3. 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 4. 清除代理（如果导致问题）
unset HTTP_PROXY
unset HTTPS_PROXY

与官方 API 的区别

对比项	官方 API	Xcompute
Base URL	`https://api.anthropic.com`	`https://xcompute.us`
认证方式	`x-api-key` header	`ANTHROPIC_AUTH_TOKEN`
价格	官方定价	折扣价（最低 0.9 折）
计费方式	按 token 直接计费	通过 Xcompute 平台
稳定性	最高	取决于中转站负载
延迟	直连最低	可能略高（加速入口可缓解）
模型可用性	第一时间可用	可能有短暂延迟

为什么建议先从简单问题开始？

因为非技术用户最容易在第一步就直接让 Agent 做复杂改动。先确认它能理解仓库、能正常响应，再开始真正修改更稳。

其他常见问题

可以在公司内网使用吗？ 取决于公司网络策略。如果外网访问受限，可以配置 HTTP 代理：

export HTTP_PROXY=http://your-company-proxy:port
export HTTPS_PROXY=http://your-company-proxy:port

API Key 被泄露了怎么办？ 立即在 Xcompute 控制台重新生成 API Key，并更新本地配置。 费用如何计算？ Xcompute 按照中转站的渠道定价计费，具体费率请查看 Xcompute 控制台的费用页面。 支持并发请求吗？ 取决于你的 Xcompute 账户等级和渠道限制，请咨询 Xcompute 客服了解详情。

配置速查

配置项	环境变量	命令	示例值
API 地址	`ANTHROPIC_BASE_URL`	`claude config set anthropicBaseUrl`	`https://xcompute.us`
API 密钥	`ANTHROPIC_AUTH_TOKEN`	`claude config set apiKey`	`sk-xxx`
模型	`ANTHROPIC_MODEL`	`claude config set model`	`claude-sonnet-5`
HTTP 代理	`HTTP_PROXY`	—	`http://127.0.0.1:7890`
HTTPS 代理	`HTTPS_PROXY`	—	`http://127.0.0.1:7890`
超时	`CLAUDE_CODE_TIMEOUT`	—	`180000`（毫秒）

配图示例

建议不要把 Claude Code 和生产应用共用同一个密钥。按工具拆分 API Key，更方便限额管理和排查问题。

官方参考

一键配置脚本

保存为 setup-claude-code.sh，在 macOS / Linux 上运行：

#!/bin/bash
set -e

echo "配置 Claude Code + Xcompute..."

if ! command -v node &> /dev/null; then
    echo "Node.js 未安装，请先安装 Node.js 22+"
    exit 1
fi

NODE_VERSION=$(node --version | cut -d'v' -f2 | cut -d'.' -f1)
if [ "$NODE_VERSION" -lt 22 ]; then
    echo "Node.js 版本过低 ($(node --version))，需要 v22+"
    exit 1
fi

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

read -p "请输入你的 Xcompute API Key: " API_KEY
echo "请选择 API 入口："
echo "  1) 标准入口 (https://xcompute.us)"
echo "  2) 加速入口 (https://intl.dualseason.com)"
read -p "请输入选项 (1/2): " ENTRY

if [ "$ENTRY" = "2" ]; then
    BASE_URL="https://intl.dualseason.com"
else
    BASE_URL="https://xcompute.us"
fi

SHELL_RC="$HOME/.zshrc"
[ -n "$BASH_VERSION" ] && SHELL_RC="$HOME/.bashrc"

echo "" >> "$SHELL_RC"
echo "# Xcompute Claude Code" >> "$SHELL_RC"
echo "export ANTHROPIC_BASE_URL=$BASE_URL" >> "$SHELL_RC"
echo "export ANTHROPIC_AUTH_TOKEN=$API_KEY" >> "$SHELL_RC"

echo "配置已写入 $SHELL_RC"
echo "运行 source $SHELL_RC 生效，然后执行 claude 开始使用"

​先理解 Claude Code 是什么

​核心功能

​系统要求

​这篇文章会带你完成什么

​安装方式

​各平台安装说明

​接入 Xcompute

​了解渠道信息

​三种配置方式

​加速入口

​模型选择

​验证连接

​启动 Claude Code

​检查模型

​连接检查清单

​完整配置流程示例

​高级配置

​多模型切换

​代理设置

​超时配置

​自定义 System Prompt

​权限精细管理

​管道输入用法

​权限管理最佳实践

​实用工作流示例

​第一次正式使用：一步一步来

​1. 进入你的项目目录

​2. 启动 Claude Code

​3. 先做一个简单问题

​4. 再做一个低风险任务

​5. 最后再让它改代码

​日常怎么用

​1. 在项目目录中启动

​2. 让它解释代码

​3. 让它修改代码

​4. 常用命令

​常见问题

​API 连接失败

​认证错误

​模型不可用

​网络超时

​与官方 API 的区别

​为什么建议先从简单问题开始？

​其他常见问题

​配置速查

​配图示例

​官方参考

​一键配置脚本

先理解 Claude Code 是什么

核心功能

系统要求

这篇文章会带你完成什么

安装方式

各平台安装说明

接入 Xcompute

了解渠道信息

三种配置方式

加速入口

模型选择

验证连接

启动 Claude Code

检查模型

连接检查清单

完整配置流程示例

高级配置

多模型切换

代理设置

超时配置

自定义 System Prompt

权限精细管理

管道输入用法

权限管理最佳实践

实用工作流示例

第一次正式使用：一步一步来

1. 进入你的项目目录

2. 启动 Claude Code

3. 先做一个简单问题

4. 再做一个低风险任务

5. 最后再让它改代码

日常怎么用

1. 在项目目录中启动

2. 让它解释代码

3. 让它修改代码

4. 常用命令

常见问题

API 连接失败

认证错误

模型不可用

网络超时

与官方 API 的区别

为什么建议先从简单问题开始？

其他常见问题

配置速查

配图示例

官方参考

一键配置脚本