# Claude Code CLI
> Claude Code CLI 接入灵眸 API 完整指南：settings.json 配置、指定模型、国产大模型调用、1M 上下文启用与常见报错排查。
URL: https://docs.lmuai.ai/cn/docs/tools/claude-code
Claude Code 是 Anthropic 官方推出的 AI 编程智能体，可在终端中直接使用自然语言完成代码编写、调试、重构等任务。
如果你不想手动编辑 `settings.json`，可使用 [**CC Switch 一键导入**](./cc-switch)：在灵眸后台密钥列表点击「导入到 CCS」按钮，即可自动完成 Base URL 与密钥配置。
***
## 第一步：安装 Node.js [#第一步安装-nodejs]
> 如果已安装可跳过，检查命令：`node -v`
需要 **Node.js 18+** 版本，下载地址：[https://nodejs.org/en/download](https://nodejs.org/en/download)
```bash
# 安装完成后验证
node -v
# 显示版本号（如 v24.4.1）表示安装成功
```
```powershell
# 安装时注意勾选 "Automatically install the necessary tools"
# 安装完成后重新打开 PowerShell 验证
node -v
```
如果之前安装过但版本过低或环境变量有问题，重新下载安装后重新打开终端即可。
***
## 第二步：安装 Claude Code [#第二步安装-claude-code]
```bash
npm install -g @anthropic-ai/claude-code
```
```powershell
npm install -g @anthropic-ai/claude-code
```
验证安装：
```bash
claude --version
```
```bash
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code
```
***
## 第三步：配置灵眸 API [#第三步配置灵眸-api]
Claude Code 通过 `settings.json` 配置自定义 API 端点。
### 配置文件位置 [#配置文件位置]
```bash
~/.claude/settings.json
```
```powershell
C:\Users\你的用户名\.claude\settings.json
```
### 创建配置文件 [#创建配置文件]
```bash
mkdir -p ~/.claude && touch ~/.claude/settings.json
```
```powershell
mkdir "$env:USERPROFILE\.claude" -Force
New-Item "$env:USERPROFILE\.claude\settings.json" -Force
```
### 写入配置内容 [#写入配置内容]
用文本编辑器打开 `settings.json`，写入以下内容（将密钥替换为你的）：
```json
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.lmuai.ai",
"ANTHROPIC_AUTH_TOKEN": "sk-你的灵眸API密钥",
"API_TIMEOUT_MS": "3000000",
"CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
}
}
```
* `ANTHROPIC_AUTH_TOKEN` 填写你在灵眸后台生成的 API Key（`sk-` 开头）
* 不要填写 Anthropic 官方的 API Key
* 若之前配置过官方 Key，请先清除旧配置再重新写入
* `CLAUDE_CODE_ATTRIBUTION_HEADER` 设为 `"0"` 可关闭请求中附带的来源标识，有利于缓存命中、提高 Token 利用率
***
## Claude Code 启用 1M 上下文（可选） [#claude-code-启用-1m-上下文可选]
Claude Opus 4.8 / Sonnet 5 支持 **1M token 长上下文窗口**（默认为 200K），适合处理超长仓库、大段日志、跨多文件重构等场景。在模型 ID 后加 `[1M]` 后缀即可启用。
### 方式 A：手动 /model 切换（推荐临时使用） [#方式-a手动-model-切换推荐临时使用]
**保留最简 settings.json**（只有 `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`），启动 Claude Code 后直接在对话框输入：
```
/model claude-opus-5[1M]
```
或：
```
/model claude-sonnet-5[1M]
```
即可切到 1M 版本，无需改任何配置文件。当次会话生效，退出后自动恢复。
### 方式 B：settings.json 里常驻默认（推荐日常长时间使用） [#方式-bsettingsjson-里常驻默认推荐日常长时间使用]
在 `settings.json` 的 `env` 段追加两条，让 `/model opus` / `/model sonnet` 默认就走 1M 版本：
```json
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.lmuai.ai",
"ANTHROPIC_AUTH_TOKEN": "sk-你的灵眸API密钥",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5[1M]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5[1M]",
"API_TIMEOUT_MS": "3000000",
"CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
}
}
```
保存后重启 Claude Code，在 `/model` 命令里选 opus / sonnet 时会自动使用 1M 版本。
**字段说明**
| 字段 | 作用 |
| -------------------------------- | ---------------------------------- |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Claude Code 里选 `opus` 时实际发送的模型 ID |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 同上，对应 `sonnet` |
| `[1M]` 后缀 | 启用该模型的 1M token 长上下文模式；不带则走默认 200K |
* **计费不同**：1M 上下文模式按 Anthropic 分档定价，每 token 单价通常**高于默认 200K 模式**，长文本任务开销会显著上涨，非必要不常开
* **仅部分模型支持**：`claude-opus-5`、`claude-fable-5`、`claude-opus-4-8`、`claude-opus-4-7`、`claude-sonnet-5` 等 Opus / Sonnet 主线模型支持 `[1M]` 后缀；Haiku 系列以及更旧的模型不支持。具体以 [模型广场](../guide/models) 的可用清单为准
* **偶尔用一次**选方式 A、**常态化使用**选方式 B —— 两种方式二选一即可
***
## 使用国产模型（可选） [#使用国产模型可选]
灵眸支持国产大模型（如通义千问 Qwen 系列）。通过在 `settings.json` 中指定 `model`，**每次启动 Claude Code 无需手动 `/model` 切换**，直接使用指定模型。
```json
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.lmuai.ai",
"ANTHROPIC_AUTH_TOKEN": "sk-你的灵眸API密钥",
"CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
},
"model": "qwen3.8-max-preview",
"effortLevel": "medium"
}
```
**字段说明：**
| 字段 | 说明 |
| -------------------------------- | ------------------------------------------------- |
| `model` | 默认使用的模型名称，启动时自动加载，无需每次手动切换 |
| `effortLevel` | 推理强度：`low` / `medium` / `high`，国产模型建议用 `medium` |
| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设为 `"0"` 可关闭请求中附带的来源标识，有利于缓存命中、提高 Token 利用率，兼容性更好 |
* `qwen3.8-max-preview` — 通义千问 3.8 Max Preview（最新）
* `qwen3.7-max` — 通义千问 3.7 Max
* `glm-5.2` — 智谱 GLM-5.2
* `deepseek-v4-pro` — DeepSeek V4 Pro
* `kimi-k3` — Kimi K3
具体可用模型以灵眸后台「可用模型」列表为准。
| | 国产模型 | Claude 官方模型 |
| ------ | ---- | ----------- |
| 费用 | 更低 | 较高 |
| 中文理解 | 优秀 | 良好 |
| 代码能力 | 优秀 | 优秀 |
| 默认模型设置 | ✅ 支持 | ✅ 支持 |
***
## 第四步：启动 Claude Code [#第四步启动-claude-code]
在项目目录下打开终端，运行：
```bash
claude
```
### 免审批模式（推荐） [#免审批模式推荐]
```bash
claude --dangerously-skip-permissions
```
> 此模式下 Claude Code 无需每步确认即可自动执行命令，适合在项目目录中使用。
***
## 验证配置 [#验证配置]
启动后在 Claude Code 交互界面输入：
```
/status
```
将显示当前的：
* 模型名称
* API Base URL（应显示 `https://api.lmuai.ai`）
* API Key 状态
确认 Base URL 正确即说明配置成功。
***
## 常见问题 [#常见问题]
### 报错 401 Unauthorized [#报错-401-unauthorized]
**原因：** API Key 不正确，或请求仍走的是 Anthropic 官方。
**解决：**
1. 确认 `settings.json` 中 `ANTHROPIC_AUTH_TOKEN` 填的是灵眸后台的密钥
2. 检查是否有 Shell 环境变量覆盖了配置
```bash
echo $ANTHROPIC_BASE_URL
```
```powershell
echo $env:ANTHROPIC_BASE_URL
```
3. 重新打开终端后再启动 Claude Code
### 报错 stream disconnected / 断流 [#报错-stream-disconnected--断流]
**原因：** 本地网络不稳定，或开启了魔法 / VPN / 系统代理——代理自动切换 IP 会导致连接中断。
**解决：** 关闭 VPN / 系统代理后重试。灵眸海外网关境外直连，直连即最快最稳定。
### 报错 503 No available accounts [#报错-503-no-available-accounts]
**原因：** 多半是 `~/.zshrc` 或 `~/.bashrc` 里配置了 `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` 等全局环境变量，覆盖了 `settings.json` 里的配置。
**解决：** 把这几行从 shell 配置里删掉，或移到独立文件仅在启动 Claude Code 时 `source` 加载。详见[常见问题 · 问题 6](../guide/faq#问题-6503-no-available-accounts环境变量覆盖密钥)。
### 响应超时 [#响应超时]
**原因：** 默认超时时间较短。
**解决：** 确认 `API_TIMEOUT_MS` 已设置为 `3000000`（50分钟），避免长任务超时中断。
***
## 使用技巧 [#使用技巧]
* 在项目根目录启动 Claude Code，它会自动读取项目结构
* 使用 `claude "帮我重构这个函数"` 直接传入指令
* `Ctrl+C` 中断当前任务，`/exit` 退出
* 输入 `?` 或 `/help` 查看所有可用命令
***
## 用 /goal 让 Claude Code 自动干到目标达成（可选） [#用-goal-让-claude-code-自动干到目标达成可选]
`/goal` 是 Claude Code 内置的斜杠命令（自 **v2.1.139**、2026 年 5 月起提供），用来给当前会话设定一个**完成条件**。设定后，Claude 会**连续多轮自动往下干**，直到条件被判定达成才把控制权交还给你——而不是「它自己觉得做完了」就停下。用灵眸跑那种「一口气干到底」的长任务（大仓库重构、按验收标准实现、清 issue backlog）时尤其顺手。
> 旧版本没有这个命令。若输入后提示未知命令，先把 Claude Code 升级到最新版再试。
### 基本用法 [#基本用法]
| 命令 | 作用 |
| -------------- | --------------------------------------------------------- |
| `/goal <完成条件>` | 设定目标；Claude 立即开始一轮，之后自动续跑直到条件达成 |
| `/goal` | 查看当前（或最近一次）目标的状态与进度 |
| `/goal clear` | 提前清除当前目标（`stop` / `off` / `reset` / `cancel` / `none` 同效） |
一个会话**同一时刻只有一个目标**；再设一个新的会替换掉旧的，并立即开始新的一轮。
### 它怎么判断「达成了」 [#它怎么判断达成了]
每轮结束后，Claude Code 把**你的完成条件 + 本轮对话记录**交给一个小而快的模型（默认 **Haiku**）评判。评判**只看已经摆进对话里的证据**——测试输出、构建日志、文件 diff 等，**不会背着你去重跑整条 CI**。所以条件要写成 Claude 能在对话里「拿出证据」的形式。
目标会在以下**任一情况自动清除**：
* 条件被判定**达成**；
* 模型判断该条件**不可能满足**；
* 某一轮**撞上需要你介入修的报错**。
### 写好一个目标条件 [#写好一个目标条件]
* **用可验证的终态**：例如「`npm test` 退出码为 0」「`tsc --noEmit` 无报错」，而不是「把代码写好看点」这类主观描述；
* **让证据落进对话**：每轮把测试 / 构建结果打印出来，评判模型才看得到；
* **圈范围 + 封顶轮数**：例如「只改 `src/auth/` 下的文件，最多 20 轮后停」，避免空转；
* 需要\*\*可信工作区（启用 hooks）\*\*才能生效。
`/goal` 每多跑一轮就多消耗一次 token（还含每轮评判的少量 Haiku 开销）。用灵眸跑长目标时，建议在条件里写清**终态**和**最多轮数**，别让它在一个不可验证的目标上空转烧量。想做「反复自我纠正直到校验通过」的循环，可把 `/goal` 与 `/loop` 搭配使用。