# Claude / Claude Code 配置

Claude Code 是 Anthropic 官方的终端命令行 AI 编程助手。通过 4AICode API 接入后，可以在控制台管理密钥、团队额度和用量，按实际 token 用量计费。

> 💡 **新手建议**：推荐优先使用 **【方式一：快捷脚本安装与配置】**，一条命令自动完成安装与配置，省时省力。

**关于线路选择**：
4AICode 提供两条通用线路，账号与 Token 两条线路均通用：
- **中国大陆直连线路**：默认使用 `https://relay.4aicode.net`（国内直连访问更稳定）。
- **国际线路**：海外网络推荐使用 `https://relay.4aicode.com`。

---

## 准备工作：获取你的 Token

无论使用哪种方式，都需要先拿到属于你的 4AICode 访问令牌（Token）：

1. 登录 4AICode，进入 [仪表盘 → 管理 Tokens](https://4aicode.net/tokens)（国际网络可访问 [4aicode.com/tokens](https://4aicode.com/tokens)）。
2. 点击 **「新建 Token」**。
3. 复制生成的字符串（格式为 `sk-4ai-<your-token>`）。

> ⚠️ **重要安全提示**：
> - Token 只会完整显示一次，请妥善保存到记事本或密码管理器中。
> - 本文示例中的 `sk-4ai-<your-token>` 是占位符，请务必替换为您自己的真实 Token。
> - Token 等同于密码，请勿泄露给他人或上传到 GitHub；命令行中直接传入 Token 会保存在终端历史记录中，用完可清理对应历史（如运行 `history -c` 或清空对应 shell 历史文件）。

---

## 方式一：快捷脚本安装与配置（推荐小白）

根据你的电脑操作系统，选择对应的选项卡：


**macOS / Linux**


### 1. 打开终端
按快捷键 `⌘ + 空格`，输入「终端」或「Terminal」并按回车。

### 2. 安装 Claude Code CLI
Claude Code 依赖 Node.js 18+ 环境。在终端中运行以下官方安装命令：

```bash
# 官方一键安装命令
curl -fsSL https://claude.ai/install.sh | bash
```

安装完成后，输入 `claude --version`，若能正常输出版本号说明安装成功。

### 3. 配置 4AICode 环境变量
将环境变量写入当前 Shell 配置文件，这样每次打开终端都能自动生效。把 `sk-4ai-<your-token>` 替换为你准备好的真实 Token：

```bash
# 默认使用中国大陆直连线路（推荐国内用户）
cat <<'EOF' >> ~/.zshrc
export ANTHROPIC_BASE_URL=https://relay.4aicode.net
export ANTHROPIC_AUTH_TOKEN=sk-4ai-<your-token>
export ANTHROPIC_API_KEY=sk-4ai-<your-token>
EOF
source ~/.zshrc

# 提示：如果你使用的是 bash 而非 zsh（例如部分 Linux 系统），请将 ~/.zshrc 换成 ~/.bashrc
```

*若身处海外/使用国际线路，只需将上述 `https://relay.4aicode.net` 替换为 `https://relay.4aicode.com`。*

### 4. 验证运行
**新开一个终端窗口**（加载最新配置），进入你的任意项目代码目录，运行：

```bash
claude
```
进入对话界面后，输入一句 `你好，解释一下当前项目结构`。若正常收到回复，即代表已成功接通 4AICode！


**Windows**


### 1. 打开 PowerShell
按键盘 `Win 键`，搜索并打开 **PowerShell**（或 Windows Terminal）。

### 2. 执行一键安装与配置脚本（全自动）
4AICode 针对 Windows 用户提供了自动化脚本，会自动检测并安装 Node.js、npm、Git 以及 Claude Code，并一键完成 4AICode 接入配置。

**交互式安装（推荐）**：运行后会提示粘贴你的 Token：

```powershell
irm https://4aicode.net/claude-install.ps1 | iex
```

**静默安装**：直接传入真实 Token 执行：

```powershell
& ([scriptblock]::Create((irm https://4aicode.net/claude-install.ps1))) -ApiKey 'sk-4ai-<your-token>'
```

*若身处海外/使用国际线路，可下载或指定 BaseUrl 为 `https://relay.4aicode.com`。*

### 3. 验证运行
**新开一个 PowerShell 窗口**，进入代码目录后输入：

```powershell
claude
```
输入测试消息，确认能正常交互即可开始日常编程开发！


---

## 方式二：配置文件持久化（更优雅的方式）

除了配置环境变量，Claude Code 还支持直接通过全局配置文件 `settings.json` 设置代理网关和 Token。这种方式配置全局持久生效，不会污染命令行环境。

配置文件路径：
- **macOS / Linux**：`~/.claude/settings.json`
- **Windows**：`%USERPROFILE%\.claude\settings.json`

打开或创建该文件，在 `env` 节点中填入配置（如果已有其他设置，请保留原有项并合并 `env` 节点）：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://relay.4aicode.net",
    "ANTHROPIC_AUTH_TOKEN": "sk-4ai-<your-token>",
    "ANTHROPIC_API_KEY": "sk-4ai-<your-token>"
  }
}
```

保存后彻底重启终端或 Claude Code 即可生效。

---

## 进阶玩法：在 Claude Code 中使用其他顶级模型

4AICode 后端网关支持强大的模型智能路由能力。你可以在 Claude Code 优雅精致的终端交互界面中，直接调用 ChatGPT（GPT-5.6 / GPT-6）或者 Kimi K3 模型！

### 0. 在 Claude Code 中使用 Claude Opus 5.5 Kiro（超值推荐）

**Claude Opus 5.5 Kiro** 是 4AICode 专属的 Claude Code 优化版本，享受超值优惠定价。


**macOS / Linux**


```bash
# 使用 Claude Opus 5.5 Kiro（推荐）
export ANTHROPIC_BASE_URL=https://relay.4aicode.net
export ANTHROPIC_AUTH_TOKEN=sk-4ai-<your-token>
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5-kiro
export ANTHROPIC_MODEL=opus
claude
```


**Windows**


```powershell
# 使用 Claude Opus 5.5 Kiro（推荐）
[Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://relay.4aicode.net', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', 'sk-4ai-<your-token>', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL', 'claude-opus-5-5-kiro', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'opus', 'User')
```


**适用场景**：
- 复杂代码生成与架构设计
- 多步骤推理与问题解决
- 大规模上下文处理（200K tokens）
- 技术文档编写与代码审查

### 1. 在 Claude Code 中使用 ChatGPT 系列模型

只需设置模型环境变量，网关在接收到 `/v1/messages` 请求时会按 `gpt-*` 模型名称选择对应的上游服务：


**macOS / Linux**


```bash
# 日常推荐：使用 GPT-5.6 Terra
export ANTHROPIC_BASE_URL=https://relay.4aicode.net
export ANTHROPIC_AUTH_TOKEN=sk-4ai-<your-token>
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.6-terra
export ANTHROPIC_MODEL=opus
claude

# 追求极致：使用新一代旗舰 GPT-6 Astra
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-6-astra
export ANTHROPIC_MODEL=opus
claude

# 攻坚复杂架构难题：固定 GPT-5.6 Sol 超高推理
export ANTHROPIC_BASE_URL=https://relay.4aicode.net
export ANTHROPIC_AUTH_TOKEN=sk-4ai-<your-token>
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.6-sol
export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME="4AICode GPT 5.6 Sol"
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES=effort,xhigh_effort,thinking,adaptive_thinking,interleaved_thinking
export ANTHROPIC_MODEL=opus
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5.4-mini
export CLAUDE_CODE_EFFORT_LEVEL=xhigh
claude
```


**Windows**


```powershell
# 日常推荐：使用 GPT-5.6 Terra
[Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://relay.4aicode.net', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', 'sk-4ai-<your-token>', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL', 'gpt-5.6-terra', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'opus', 'User')

# 追求极致：使用新一代旗舰 GPT-6 Astra
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL', 'gpt-6-astra', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'opus', 'User')
```


### 2. 在 Claude Code 中使用 Kimi K3（超长 1M 上下文）
如果你需要处理超大型代码仓库或阅读海量文档，推荐接入 Kimi K3，完整配置步骤请参考专用指南：
👉 [Claude Code 使用 Kimi K3 详细指南](/docs/guides/claude-kimi)

---

## 其他工具与 SDK 接入

4AICode 完全兼容 Anthropic 官方 API 协议规范，你可以把 4AICode 接入任何支持 Anthropic 接口的应用或代码中：

### 1. 统一接口参数
- **Base URL**：`https://relay.4aicode.net`（国际网络用 `https://relay.4aicode.com`）
- **API Key / Token**：你的 4AICode Token（`sk-4ai-<your-token>`）

### 2. Node.js / TypeScript SDK

```ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://relay.4aicode.net",
  apiKey: "sk-4ai-<your-token>",
});

const msg = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(msg.content);
```

### 3. Python SDK

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://relay.4aicode.net",
    api_key="sk-4ai-<your-token>",
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "你好，请写一段快速排序算法"}
    ]
)

print(message.content[0].text)
```

### 4. cURL 请求示例

4AICode 同时支持官方 Anthropic 的 `x-api-key` 请求头与标准的 `Authorization: Bearer` 请求头：

```bash
# 方式 A：使用 x-api-key（Anthropic 官方标准格式）
curl https://relay.4aicode.net/v1/messages \
  -H "x-api-key: sk-4ai-<your-token>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "ping"}]
  }'

# 方式 B：使用 Authorization: Bearer
curl https://relay.4aicode.net/v1/messages \
  -H "Authorization: Bearer sk-4ai-<your-token>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

---

## 常见问题与排错（FAQ）

### Q1：提示 `claude: command not found` 或不是内部命令？
- **原因**：Claude Code 尚未安装成功，或安装后没有刷新终端环境变量。
- **解决**：彻底关闭当前终端并新开一个窗口重试。若依然找不到命令：
  - macOS/Linux：重新运行官方安装命令 `curl -fsSL https://claude.ai/install.sh | bash`，并检查 `~/.local/bin` 是否在 `PATH` 中。
  - Windows：使用 PowerShell 运行官方一键脚本 `irm https://4aicode.net/claude-install.ps1 | iex`，脚本会自动修正 PATH。

### Q2：运行时出现 `401 Unauthorized` 或 Token 无效？
- **原因**：填写的 Token 不正确，或复制时漏掉了字符，或未将文档中的占位符替换。
- **解决**：前往 [仪表盘 → 管理 Tokens](https://4aicode.net/tokens) 检查 Token 状态或新建一个 Token，确保填入的是 `sk-4ai-` 开头的完整密钥。

### Q3：修改了环境变量或 settings.json 后，为什么不生效？
- **原因**：当前终端进程已经加载了旧配置，或者 `settings.json` 的优先级覆盖了环境变量。
- **解决**：完全退出正在运行的 Claude 进程，关闭终端并重新打开。优先级规则为：`settings.json` > 终端环境变量。

### Q4：常见 HTTP 错误状态码处理

| 状态码 | 产生原因 | 应对措施 |
|---|---|---|
| **401** | Token 无效、过期或已被手动撤销 | 在仪表盘重新创建 Token 并更新配置 |
| **403** | 团队或组织已被暂停访问 | 联系管理员核对账户状态 |
| **429** | 触发频率限流或额度已用尽 | 观察响应中的 `X-RateLimit-*` 标头；详见 [限流说明](/docs/guides/rate-limit) 或充值额度 |
| **503** | 上游服务暂时不可用或繁忙 | 稍等几秒后重新发送即可 |