Claude Code CLI — Ubuntu 安装与多模型配置指南

> 涵盖安装、多模型切换、API Key 管理、上下文窗口调优、settings.json 层级、状态栏定制。

1. 安装

方式一：npm 全局安装（推荐）


# 安装 Node.js 20+（如尚未安装）
sudo apt update && sudo apt install -y nodejs npm

# 全局安装 Claude Code CLI

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

# 验证

claude --version

方式二：独立二进制


# 下载最新 release
curl -fsSL https://claude.ai/install.sh | bash

# 二进制安装在 ~/.local/bin/claude

export PATH="$HOME/.local/bin:$PATH"

初始配置

首次运行 claude 会进入 OAuth 登录流程。也可以直接用 API key：


export ANTHROPIC_API_KEY="sk-ant-..."
claude

2. 多模型切换

Claude Code CLI 支持通过环境变量或 settings.json 切换到 DeepSeek、Kimi 等第三方模型。

2.1 DeepSeek v4-pro（默认代理模型）


{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_API_KEY": "sk-your-deepseek-key",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro"
  }
}

注册并获取 key: https://platform.deepseek.com

2.2 Kimi K3


{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.moonshot.cn/anthropic",
    "ANTHROPIC_API_KEY": "sk-your-kimi-key",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "kimi-k3",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-k3",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "kimi-k3"
  }
}

注册并获取 key: https://platform.moonshot.cn

2.3 快速切换脚本

创建 /home/user/tools/switch-claude-model.sh：


#!/bin/bash
MODEL=${1:-deepseek}

CONF_FILE="$HOME/.claude/settings.json"

case "$MODEL" in

  deepseek)

    BASE_URL="https://api.deepseek.com/anthropic"

    API_KEY_ENV="DEEPSEEK_API_KEY"

    MODEL_NAME="deepseek-v4-pro"

    ;;

  kimi)

    BASE_URL="https://api.moonshot.cn/anthropic"

    API_KEY_ENV="KIMI_API_KEY"

    MODEL_NAME="kimi-k3"

    ;;

  *)

    echo "用法: $0 {deepseek|kimi}"

    exit 1

    ;;

esac

API_KEY="${!API_KEY_ENV}"

if [ -z "$API_KEY" ]; then

    echo "错误: $API_KEY_ENV 环境变量未设置"

    exit 1

fi

# 用 python3 更新 settings.json

python3 -c "

import json, os

conf_path = '$CONF_FILE'

conf = {}

if os.path.exists(conf_path):

    with open(conf_path) as f:

        conf = json.load(f)

conf['env'] = conf.get('env', {})

conf['env']['ANTHROPIC_BASE_URL'] = '$BASE_URL'

conf['env']['ANTHROPIC_API_KEY'] = '$API_KEY'

conf['env']['ANTHROPIC_DEFAULT_HAIKU_MODEL'] = '$MODEL_NAME'

conf['env']['ANTHROPIC_DEFAULT_SONNET_MODEL'] = '$MODEL_NAME'

conf['env']['ANTHROPIC_DEFAULT_OPUS_MODEL'] = '$MODEL_NAME'

os.makedirs(os.path.dirname(conf_path), exist_ok=True)

with open(conf_path, 'w') as f:

    json.dump(conf, f, indent=2)

print(f'已切换到 $MODEL_NAME')

"

使用：


export DEEPSEEK_API_KEY="sk-..."
export KIMI_API_KEY="sk-..."

# 切换到 DeepSeek

bash /home/user/tools/switch-claude-model.sh deepseek

# 切换到 Kimi

bash /home/user/tools/switch-claude-model.sh kimi

3. API Key 管理

3.1 安全存储

不要在 settings.json 中硬编码 API key。推荐三种方式：

方式	路径	优先级
环境变量	`export ANTHROPIC_API_KEY=...`	最高
`.env` 文件	项目根目录 `.env`	中
系统 keyring	`secret-tool store --label='Claude' service claude-api`	低

3.2 .bashrc 持久化


# ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-..."
export DEEPSEEK_API_KEY="sk-..."
export KIMI_API_KEY="sk-..."

3.3 按项目隔离

在项目目录下创建 .env：


# /home/user/work/my_project/.env
ANTHROPIC_API_KEY=sk-ant-project-specific-key

Claude Code 启动时会自动加载当前目录的 .env 文件。

4. 上下文窗口调优

4.1 问题描述

Claude Code 对某些代理模型会自动将上下文窗口回退到 200K tokens，即使模型的真实窗口远大于此（如 DeepSeek v4-pro 和 GLM-5.2 均支持 1M tokens）。

4.2 解决方案

在 settings.json 中显式覆盖上下文窗口：


{
  "modelContextWindow": 1000000
}

或者创建一个启动 wrapper 脚本 /home/user/tools/claude-fix-ctx.sh：


#!/bin/bash
# 覆盖上下文窗口限制为真实值

# DeepSeek v4-pro: 1M tokens

# Kimi K3: 128K tokens

# GLM-5.2: 1M tokens

REAL_CTX=${CLAUDE_CTX_WINDOW:-1000000}

# 修改 settings.json 中的 modelContextWindow

python3 -c "

import json, os

conf_path = os.path.expanduser('~/.claude/settings.json')

conf = {}

if os.path.exists(conf_path):

    with open(conf_path) as f:

        conf = json.load(f)

conf['modelContextWindow'] = $REAL_CTX

os.makedirs(os.path.dirname(conf_path), exist_ok=True)

with open(conf_path, 'w') as f:

    json.dump(conf, f, indent=2)

" && exec claude "$@"

使用：


# 默认 1M 窗口
bash /home/user/tools/claude-fix-ctx.sh

# 指定窗口大小

CLAUDE_CTX_WINDOW=128000 bash /home/user/tools/claude-fix-ctx.sh

4.3 验证当前上下文窗口


# 启动 Claude Code 后，在对话中输入：
# "What is the current context window size?"
# 或者检查环境变量
echo $ANTHROPIC_CONTEXT_WINDOW

5. 模型对比

特性	DeepSeek v4-pro	Kimi K3	Claude Sonnet 4
上下文窗口	1M tokens	128K tokens	200K tokens
速度	快（~80 tok/s）	中（~50 tok/s）	中（~60 tok/s）
代码能力	强	中	很强
中文能力	很强	很强	强
价格 (输入/输出)	$0.14/$0.28 每百万	$0.12/$0.40 每百万	$3/$15 每百万
适合场景	默认编程助手	长文档处理	复杂推理
工具调用	支持	支持	原生支持
图片理解	不支持	支持	支持

选择建议：

日常开发：DeepSeek v4-pro — 性价比最高，速度快，代码能力强
长文档/翻译：Kimi K3 — 中文理解最佳
复杂架构设计：Claude Sonnet 4 — 推理最深，但价格最贵

6. settings.json 层级体系

Claude Code 支持三层配置，优先级从高到低：


优先级高 ──────────────────────────────────► 优先级低
本地           项目级           全局
./.claude/     ../.claude/       ~/.claude/
settings.local.json              settings.json
                 settings.json

6.1 全局配置（Global）— `~/.claude/settings.json`

影响所有项目的基础配置：


{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_API_KEY": "sk-..."
  },
  "model": "deepseek-v4-pro",
  "modelContextWindow": 1000000,
  "theme": "dark",
  "permissions": {
    "allow": [
      "Bash(curl:*)",
      "Bash(jq:*)",
      "Bash(npm:*)",
      "Bash(git:*)",
      "Read",
      "Write",
      "Edit"
    ]
  }
}

6.2 项目级配置（Project）— `<project>/.claude/settings.json`

覆盖全局配置，适用于特定项目的设置：


{
  "env": {
    "ANTHROPIC_API_KEY": "sk-project-specific-key",
    "PROJECT_NAME": "fpga_ila"
  },
  "permissions": {
    "allow": [
      "Bash(make:*)",
      "Bash(iverilog:*)"
    ],
    "deny": [
      "Bash(rm:-rf)"
    ]
  }
}

6.3 本地配置（Local）— `<project>/.claude/settings.local.json`

个人本地覆盖，不提交到 Git（应加入 .gitignore）：


{
  "env": {
    "DEBUG": "true",
    "LOG_LEVEL": "verbose"
  },
  "theme": "light"
}

6.4 配置生效规则

合并策略：三层配置深度合并，高优先级覆盖低优先级的同名字段
allow/deny 权限：deny 优先于 allow，本地配置优先于全局配置
env 变量：直接覆盖，不会合并嵌套对象
热加载：修改后下次启动生效，部分设置支持 /config 命令实时修改

6.5 查看当前生效配置


claude config list
# 或在对话中使用
# /config

7. 状态栏自定义

7.1 默认状态栏

Claude Code 的状态栏显示在终端底部，包含：

当前模型名称

Token 使用量

会话时长

快捷键提示

7.2 自定义状态栏内容

在 settings.json 中配置：


{
  "statusBar": {
    "enabled": true,
    "showModel": true,
    "showTokens": true,
    "showCost": true,
    "showTime": true,
    "format": "{model} | {tokens} tokens | ${cost} | {time}",
    "refreshInterval": 5
  }
}

7.3 可用的状态栏变量

变量	说明
`{model}`	当前模型名称
`{tokens}`	已使用的 token 数
`{cost}`	估算费用（美元）
`{time}`	会话持续时间
`{project}`	当前项目名
`{branch}`	Git 分支名

7.4 高级：添加自定义指标


# 创建状态栏钩子脚本
mkdir -p /home/user/.claude/hooks
cat > /home/user/.claude/hooks/statusbar.sh << 'EOF'
#!/bin/bash
# 输出额外状态信息
echo "CPU: $(top -bn1 | grep "Cpu(s)" | awk '{print $2}')%"
echo "Mem: $(free -h | awk '/^Mem:/ {print $3 "/" $2}')"
EOF
chmod +x /home/user/.claude/hooks/statusbar.sh

8. 常见问题排查

8.1 "认证失败" (Authentication failed)


# 检查 API key 是否设置
echo $ANTHROPIC_API_KEY

# 验证 key 有效性

curl -s https://api.deepseek.com/anthropic/v1/messages \

  -H "x-api-key: $ANTHROPIC_API_KEY" \

  -H "anthropic-version: 2023-06-01" \

  -H "content-type: application/json" \

  -d '{"model":"deepseek-v4-pro","max_tokens":1,"messages":[{"role":"user","content":"hi"}]}'

8.2 "模型未找到" (Model not found)

确认 settings.json 中的模型名拼写正确：

DeepSeek: deepseek-v4-pro

Kimi: kimi-k3

注意不要有多余空格或引号

8.3 上下文窗口未生效


# 检查 settings.json
cat ~/.claude/settings.json | python3 -m json.tool | grep modelContextWindow

# 确保字段名完全正确（注意驼峰命名）

8.4 代理/网络问题


# 如果公司网络需要代理
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# 或者在 settings.json 中

{

  "env": {

    "HTTP_PROXY": "http://proxy.company.com:8080",

    "HTTPS_PROXY": "http://proxy.company.com:8080"

  }

}