Claude Code - 非线智能-NoneLinear技术文档

接入 Claude Code

Claude Code 是 Anthropic 推出的 AI 编程 CLI 工具。

1. 安装步骤

前提条件：

系统需安装 Node.js (版本 >= 18)。
Windows 用户建议安装 Git Bash。

在命令行界面，执行以下命令安装 Claude Code：

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

安装结束后，执行以下命令查看安装结果，若显示版本号则安装成功：

claude --version

2. 配置工具

Claude Code 推荐优先使用 Anthropic 格式接入 NoneLinear。该方式直接使用 Claude Code 原生支持的 ANTHROPIC_ 配置项，不需要额外安装路由工具。如果你需要多个供应商、多模型路由，或者希望通过 OpenAI Compatible 接口统一管理，也可以使用 ClaudeCodeRouter。

2.1. Anthropic 格式（推荐）

需要配置以下信息：

ANTHROPIC_BASE_URL：https://api.nonelinear.com/anthropic
ANTHROPIC_AUTH_TOKEN：从 NoneLinear 官网获取 API Key
ANTHROPIC_MODEL：按需选择模型，可在模型列表查看可用模型

下面配置里的 gpt-5.5、claude-opus-4.8、deepseek-v4-pro 都是示例模型 ID。实际使用时可以直接复制这些示例；如果需要换成其他模型，请先到模型列表查询对应模型 ID，并保持大小写、连字符和版本号一致。

2.1.1. macOS & Linux

在终端执行以下命令进入 Claude Code 配置文件：

vim ~/.claude/settings.json

编辑配置文件，文件内容如下。请将 你的 NoneLinear API Key 替换为实际 API Key。

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "你的 NoneLinear API Key",
        "ANTHROPIC_BASE_URL": "https://api.nonelinear.com/anthropic",
        "ANTHROPIC_MODEL": "gpt-5.5",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5.5",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4.8",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-pro",
        "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
    }
}

然后重新打开终端窗口，配置才能生效。

Linux 多用户与权限注意事项在多用户共享的 Linux 服务器上，或者存在 root 账户交替操作时，请注意以下两点，避免配置失效或启动时报错：

避免使用 sudo 启动或配置 Claude Code：使用 sudo 可能会将 ~/.claude 目录的所有权变更为 root，导致普通用户无法读取配置。若配置未生效，可以执行：

sudo chown -R $USER:$USER ~/.claude

共享临时沙箱冲突：若因其他用户或 root 优先启动，导致出现 /tmp/claude 权限不足报错，可以清理 Claude Code 的临时沙箱目录：

sudo rm -rf /tmp/claude

启动 Claude Code：进入项目目录，执行 claude 命令，即可开始使用。下面的 your_project 需要替换为你的项目路径。

cd your_project
claude

2.1.2. Windows

在 Windows 系统下长期开发，建议直接使用 setx，但 setx 更改后，必须关闭当前窗口，重新打开一个新的 CMD 窗口，新的值才会生效。

API Key 获取地址：https://nonelinear.com/static/apikey.html
可用模型列表：https://nonelinear.com/static/models.html

使用 setx 写入配置，请将下方的 你的 NoneLinear API Key 替换为实际 API Key。写入 ANTHROPIC_AUTH_TOKEN 时，需要用英文双引号包裹，避免 API Key 中的特殊字符被 CMD 解析或截断。模型 ID 同样建议用英文双引号包裹。下面的 gpt-5.5、claude-opus-4.8、deepseek-v4-pro 是示例模型 ID，实际使用时可以直接复制这些示例。如果需要更换其他模型，请先到模型列表查询对应模型 ID。

setx ANTHROPIC_AUTH_TOKEN "你的 NoneLinear API Key"
setx ANTHROPIC_BASE_URL "https://api.nonelinear.com/anthropic"
setx ANTHROPIC_MODEL "gpt-5.5"
setx ANTHROPIC_DEFAULT_SONNET_MODEL "gpt-5.5"
setx ANTHROPIC_DEFAULT_OPUS_MODEL "claude-opus-4.8"
setx ANTHROPIC_DEFAULT_HAIKU_MODEL "deepseek-v4-pro"
setx CLAUDE_CODE_ATTRIBUTION_HEADER "0"

然后关闭当前 CMD（或 Git CMD）窗口，重新打开一个新窗口，执行以下命令检查环境变量是否生效：

echo %ANTHROPIC_AUTH_TOKEN%
echo %ANTHROPIC_BASE_URL%
echo %ANTHROPIC_MODEL%

启动 Claude Code：进入项目目录，执行 claude 命令，即可开始使用。下面的 your_project 需要替换为你的项目路径。

cd your_project
claude

配置多个模型后切换模型

如果你按上面的方式同时配置了 ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL，进入 Claude Code 后可以直接在对话框输入：

/model

Claude Code 会弹出模型选择列表，里面会显示默认模型以及已配置的 Sonnet / Opus / Haiku 槽位。用方向键选择要使用的模型，按回车确认即可切换。 Claude Code 模型切换列表

以上图为例：

Default 使用当前默认模型，即 ANTHROPIC_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL 对应的模型。
claude-opus-4.8 来自 ANTHROPIC_DEFAULT_OPUS_MODEL。
gpt-5.5 来自 ANTHROPIC_DEFAULT_SONNET_MODEL。
deepseek-v4-pro 来自 ANTHROPIC_DEFAULT_HAIKU_MODEL。

如果修改了 ~/.claude/settings.json 或系统环境变量中的模型配置，需要退出当前 Claude Code 会话并重新执行 claude，新的模型列表才会生效。

Claude 系列模型使用建议与缓存设置1. 为什么问一句“您好”，Claude Opus 就花费几块钱Claude Code 是编程 Agent，不是普通聊天窗口。即使用户只输入“您好”，请求里也会包含系统提示词、工具定义、会话状态、历史上下文，以及可能读取到的项目文件、命令结果等内容。账单按完整请求计算，不只按用户输入的几个字计算。Claude Opus 系列输入价格较高，一句简单问候，就会产生几块钱费用。2. 按任务类型选择模型

连通性测试：建议在空目录或小目录中测试，优先使用deepseek-v4-flash 等性价比更高的模型，不建议直接用 Claude 系列模型测试。
规划、复杂拆解、关键判断：可以使用 Claude 系列或 GPT 系列等更强模型。
常规代码修改、调试、批量文档编辑：优先使用 deepseek-v4、GPT 系列等更经济的模型。
长时间连续开发：建议通过 /model 按任务切换模型，不要所有任务都固定使用 Claude 系列模型。

3. Claude 系列模型的缓存命中率问题Claude 系列模型的缓存复用要求比较严格：两次请求中的系统提示词、工具定义、历史对话等内容需要尽量保持一致，才更容易触发缓存复用。在 Claude Code 里，请求上下文会随着文件读取、工具调用、命令结果和会话状态变化而变化，缓存命中率通常不稳定。对成本敏感时，建议把 Claude 系列模型留给关键判断和复杂推理。4. 空槽位会使用 Claude Code 默认模型名Claude Code 的 /model 会按 Sonnet、Opus、Haiku 等角色槽位切换模型。如果只配置了其中一个槽位，其他槽位留空，切换到空槽位时，Claude Code 会使用该角色的默认模型名发起请求。NoneLinear 可以接收并处理这类请求，因此会出现“我没有配置 Opus 槽位，但后台看到 Opus 相关消耗”的情况。建议把 Sonnet、Opus、Haiku 槽位都明确绑定到你希望使用的模型；如果不希望使用 Opus，就不要让 Opus 槽位保持空配置。5. 闲置或结束后会出现 Haiku 槽位的 recap 消耗新版 Claude Code 默认启用会话自动摘要机制（Session recap / Away Summary）。当终端结束交互、离开或保持闲置时，Claude Code 会在后台调用 Haiku 槽位模型，对当前会话做 recap，总结开发上下文。如果没有配置 Haiku 槽位，Claude Code 会默认使用 Haiku 4.5 模型做 recap。如果 Haiku 槽位映射为 deepseek-v4-pro，即使用户没有继续输入，也会在后台看到 deepseek-v4-pro 的 API 消耗记录；如果 Haiku 槽位为空，则会看到 claude-haiku-4.5 相关消耗。对成本敏感时，建议给 Haiku 槽位绑定更经济的模型，并把这类后台摘要消耗纳入预期。6. 关闭 Claude Code 动态 attribution header另外，新版本 Claude Code 会在请求里自动加入一行包含动态随机哈希值的 attribution header，这会让请求内容每次都发生变化，从而影响缓存命中。建议在 Claude Code 配置的 env 字段里加入：

{
    "env": {
        "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
    }
}

如果配置文件里已经有 env，不要新建第二个 env，直接把 "CLAUDE_CODE_ATTRIBUTION_HEADER": "0" 追加到现有 env 对象里即可。常见配置文件位置如下：

系统	Claude Code 配置文件位置
macOS / Linux	`~/.claude/settings.json`
Windows	`C:\Users\<你的Windows用户名>\.claude\settings.json`
WSL	`~/.claude/settings.json`

如果是通过系统环境变量配置，也可以按系统写入环境变量，例如 Windows 可执行：

setx CLAUDE_CODE_ATTRIBUTION_HEADER "0"

2.1.3. CC-Switch 安装与配置（可选，图形化多供应商管理）

如果你需要在多个 API 供应商之间快速切换，或者希望以图形界面管理多个 API Key，推荐使用 CC-Switch 工具。CC-Switch 是一款跨平台桌面应用，本质是”配置切换器”——它会把你选中的供应商信息写入 ~/.claude/settings.json，免去手动编辑配置文件的麻烦。

2.1.3.1. 下载与安装

CC-Switch 开源项目地址：https://github.com/farion1231/cc-switch ，从 Releases 页面里，找到 “Assets” (资产/附件) 列表，下载对应平台的安装包。 cc-switch下载界面

（1） macOS 推荐使用 Homebrew 一行安装：

brew tap farion1231/ccswitch
brew install --cask cc-switch

或从 Releases 页面下载 .dmg 文件（区分 Apple Silicon 和 Intel 芯片），双击安装后拖入”应用程序”文件夹。首次启动若提示”未识别的开发者”，请进入 系统设置 → 隐私与安全性，在底部点击”仍要打开”。（2） Windows 从 Releases 页面下载 CC-Switch-vX.X.X-Windows.msi（推荐，支持自动更新）或便携版 zip，双击 msi 文件按引导安装即可。（3） Linux Releases 页面提供 .deb、.rpm、.AppImage、.flatpak 四种分发格式，按你的发行版选择。Arch 用户可直接执行：

paru -S cc-switch-bin

2.1.3.2. 添加 NoneLinear 供应商

以 Windows 系统为例，启动 CC-Switch 后，按以下步骤添加 NoneLinear 配置： cc-switch添加供应商

Step 1. 右上角 + 按钮，选择”Claude”类型，再选择”自定义配置”（NoneLinear 暂未收录为内置预设）。 Step 2. 在”添加新供应商”页面填写基础信息：

字段	填写内容
供应商名称	`NoneLinear`（自定义，便于识别即可）
官网链接	`https://nonelinear.com/`
API Key	从账号页面获取
请求地址	`https://api.nonelinear.com/anthropic`

填写完成后，点击右下角”+ 添加”按钮。 cc-switch编辑供应商高级选项

Step 3. 进入”编辑供应商”页面，展开 高级选项，按以下方式配置：

字段	填写内容
API 格式	选择 `Anthropic Messages (原生)`
认证字段	保持默认 `ANTHROPIC_AUTH_TOKEN（默认）`

模型映射部分，按需填入模型列表中的模型 ID。新版 CC-Switch 的 Claude 配置里，主要是配置 Sonnet、Opus、Haiku 三个槽位；每个槽位通常包含一个显示名称和一个实际请求模型。下表仅为示例，如果需要换成其他模型，请以模型列表中的实际模型 ID 为准。新版 CC-Switch 也可以在配置页点击 获取模型列表，直接读取 NoneLinear 可用模型，并在模型映射下拉框中选择模型： cc-switch 获取 NoneLinear 模型列表

槽位	显示名称示例	实际请求模型示例
Sonnet	`gpt-5.5`	`gpt-5.5`
Opus	`claude-opus-4.8`	`claude-opus-4.8`
Haiku	`deepseek-v4-pro`	`deepseek-v4-pro`

默认兜底模型 只在 Claude Code 请求没有明确落到 Sonnet、Opus 或 Haiku 角色时使用，通常可以留空，也可以按实际需要填入一个兜底模型。填好后勾选右上角”写入通用配置”，然后点击右下角”保存”按钮。CC-Switch 会自动将配置写入 ~/.claude/settings.json 的 env 字段。如果使用的是新版 Claude Code，建议同时在 CC-Switch 的 JSON 配置模块里写入下面的环境变量，用于关闭动态 attribution header，减少它对缓存复用的影响：

{
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
}

cc-switch 配置 Claude Code attribution header

Step 4. 在供应商列表中点击 NoneLinear 条目右侧的”启用”按钮。 Step 5. 重新打开终端后运行 claude 命令，即可开始使用。 cc-switch配置后在Windows上运行Claude Code

2.1.3.3. 切换供应商

后续需要切换时，有两种方式：

方式一：打开 CC-Switch 主界面，点击目标供应商的”启用”按钮。
方式二：在系统托盘（macOS 菜单栏 / Windows 任务栏右下角）右键点击 CC-Switch 图标，从快捷菜单中直接选中目标供应商。

切换完成后，需要重启 claude 命令（退出当前会话并在新终端重新执行 claude），新配置才会生效。

2.2. ClaudeCodeRouter / OpenAI Compatible 格式（可选）

ClaudeCodeRouter 适合需要在 Claude Code 中接入 OpenAI Compatible 接口。先安装 ClaudeCodeRouter：

npm install -g @musistudio/claude-code-router

配置 API 有两种方式，一种通过 CCR 的配置界面，另一种则是通过 config.json。

2.2.1. UI 配置界面

启动配置界面：

ccr ui

浏览器会自动打开配置界面，然后就可以添加模型供应商：

在配置界面中，点击”添加供应商”。

填写以下信息：
- 供应商：填写 nonelinear
- API 完整地址：填写 https://api.nonelinear.com/v1/chat/completions
- API 密钥：可以在 NoneLinear 官网登录 GitHub 账号获取。
- 模型：可以在模型列表找到想要的模型，填入，然后点击“保存”。

上述配置保存后，在页面右侧配置路由信息。多个模型

如果你有多个模型可用：

主模型：使用较强的模型（如 deepseek-v4-pro、GLM-5.1 等）
后台/思考模型：可以使用同一个模型或稍弱的模型
长上下文模型：选择支持长上下文的模型

如果只有一个模型，所有路由都选择同一个供应商即可。配置完成后，点击 “保存并重启”。 启动 Claude Code： 重要：必须使用 ccr code 命令启动，而不是 claude 命令。如果正常响应，说明配置成功，如图所示： ccr code启动后界面

2.2.2. config.json

进入 .claude-code-router 文件夹：

cd ~/.claude-code-router

使用编辑器打开并编辑 config.json 文件（下面的模型仅供参考）：

{
  "PORT": 3456,
  "Providers": [
    {
      "name": "nonelinear",
      "api_base_url": "https://api.nonelinear.com/v1/chat/completions",
      "api_key": "NoneLinear 的 API Key",
      "models": [
        "DeepSeek-V3.2",
        "claude-sonnet-4.5"
      ]
    }
  ],
  "Router": {
    "longContextThreshold": 60000,
    "default": "nonelinear,DeepSeek-V3.2",
    "background": "nonelinear,claude-sonnet-4.5",
    "think": "nonelinear,claude-sonnet-4.5",
    "longContext": "nonelinear,claude-sonnet-4.5",
    "webSearch": "nonelinear,claude-sonnet-4.5"
  }
}

具体的操作细节：

终端输入命令：vim config.json
输入 i 切换到输入模式，在光标当前位置开始输入文本
添加上述 JSON 配置内容，可以根据自己需要选择合适的模型
编辑好之后，按 Esc 退出编辑模式，接着输入 :w 保存文件，再输入 :q 退出 vim 编辑器

然后重启 CCR：

ccr start

启动 Claude Code 时输入：

ccr code

2.3. 使用 Claude Code IDE 插件（可选）

使用 Claude Code IDE 插件前，需要先安装 Claude Code CLI。

如果已经按上方 Anthropic 格式配置好 Claude Code CLI，可以直接安装并使用 IDE 插件。
如果希望在 VS Code 插件里单独填写配置，可以参考下面的 VS Code 示例。

JetBrains 系列 (IntelliJ IDEA, PyCharm, WebStorm 等)

进入 Settings → Plugins → Marketplace。
搜索 “Claude Code” 并安装。
重启后，点击右上角的图标开始使用。

单击 Claude Code 图标，进入 Claude Code 页面开始使用 JetBrains 插件界面

VS Code

搜索 Claude Code 安装这个插件 VS 插件界面

安装好之后，打开插件的配置，如下图所示： VS 插件界面

然后填入以下信息。请将 你的 NoneLinear API Key 替换为实际 API Key；示例中的模型 ID 可以直接复制使用，如需更换模型，请到模型列表查询对应模型 ID。

{
    "claudeCode.preferredLocation": "panel",
    "claudeCode.environmentVariables": [

        {
            "name":"ANTHROPIC_BASE_URL",
            "value":"https://api.nonelinear.com/anthropic"
        },
        {
            "name":"ANTHROPIC_AUTH_TOKEN",
            "value":"你的 NoneLinear API Key"
        },
        {
            "name": "ANTHROPIC_MODEL",
            "value": "gpt-5.5"
        },
        {
            "name": "ANTHROPIC_DEFAULT_OPUS_MODEL",
            "value": "claude-opus-4.8"
        },
        {
            "name": "ANTHROPIC_DEFAULT_SONNET_MODEL",
            "value": "gpt-5.5"
        },
        {
            "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL",
            "value": "deepseek-v4-pro"
        },
        {
            "name": "CLAUDE_CODE_ATTRIBUTION_HEADER",
            "value": "0"
        }
    ],
    "workbench.colorTheme": "Default Light Modern"
}

需要注意的是，ANTHROPIC_MODEL 和 ANTHROPIC_DEFAULT_SONNET_MODEL 建议保持为同一个模型，因为 Claude Code 的 /model 切换中会使用这个默认主模型槽位。 VS 插件界面

点击 VSCode 右上角的 Claude Code 图标，进入 Claude Code 页面，即可开始使用。 VS 插件界面

​接入 Claude Code

​1. 安装步骤

​2. 配置工具

​2.1. Anthropic 格式（推荐）