Claude Code 安装与国内模型配置指南

G_whang

153人浏览 · 2026-06-13 11:22:10

G_whang · 2026-06-13 11:22:10 发布

1. Claude Code 概述

Claude Code 是 Anthropic 官方推出的终端 AI 编程助手（Agentic CLI），能在命令行中读取、理解、修改代码并执行 Shell 命令。其 Agent 框架深度集成：文件读写、Git 操作、Bash 执行、MCP 工具调用、子 Agent 调度。

1.1 核心能力

能力	说明
代码理解与生成	基于 tree-sitter 的 AST 解析 + LLM 推理
Shell 集成	PreToolUse/PostToolUse Hook 系统，自动拦截和改写命令
多模型路由	环境变量或 `/model` 命令动态切换后端
MCP 协议	接入外部工具（数据库、API、知识图谱等）
子 Agent 调度	通过 Task/Agent 将任务拆分到独立上下文执行
Worktree 隔离	Git worktree 级别的并行开发隔离

2. 安装

2.1 前置条件

依赖	版本要求
Node.js	≥ 18.0.0（推荐 22 LTS）
npm	≥ 9
Git	Windows 需安装 Git for Windows（提供 Bash 环境）

2.2 方式一：npm 全局安装

# 配置国内镜像加速
npm config set registry https://registry.npmmirror.com

# 安装
npm install -g @anthropic-ai/claude-code

# 验证
claude --version

2.3 方式二：官方脚本

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

2.4 首次运行——绕过登录引导

国内网络可能无法完成 OAuth 登录，手动编辑 ~/.claude.json：

{
  "autoUpdatesProtectedForNative": true,
  "hasCompletedOnboarding": true
}

3. 配置体系

3.1 文件层级

文件	位置	纳入版本控制	用途
`settings.json`	`~/.claude/`	❌	用户全局默认值、全局 deny 规则
`CLAUDE.md`	`~/.claude/`	❌	用户全局指令、技术栈身份
`settings.json`	`项目/.claude/`	可选	项目级权限与 Hooks
`settings.local.json`	`项目/.claude/`	❌（自动 gitignore）	个人机器级敏感覆盖
`CLAUDE.md`	项目根目录/	可选	项目约定、架构说明
`.mcp.json`	项目根目录/	可选	项目级 MCP 服务器注册

3.2 优先级（从高到低）

企业管理策略（无法覆盖）
  ↓
CLI 参数（--disallowedTools 等）
  ↓
.claude/settings.local.json     （项目-个人）
  ↓
.claude/settings.json           （项目级）
  ↓
~/.claude/settings.local.json   （用户-个人）
  ↓
~/.claude/settings.json         （用户-全局）

3.3 settings.json 结构

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [],
    "ask": [],
    "deny": []
  },
  "hooks": {},
  "env": {},
  "model": "",
  "modelOverrides": {},
  "effortLevel": "high",
  "autoMode": {
    "hard_deny": [],
    "soft_deny": [],
    "allow": []
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "apiKeyHelper": ""
}

3.4 权限模式

运行时用 Shift+Tab 切换：

模式	行为
`normal`	所有操作询问
`acceptEdits`	自动接受文件编辑，Bash 依然询问
`plan`	只读，不允许编辑和命令执行
`auto`	Agent 基于分类器 + `autoMode` 规则自主决策

claude --permission-mode auto   # 启动即进入自动模式

4. 接入国内大模型

4.1 核心配置原理

Claude Code 使用 Anthropic Messages API 格式。国内厂商已推出兼容端点，只需设置三个环境变量：

环境变量	用途
`ANTHROPIC_BASE_URL`	API 端点 URL（Claude Code 自动拼接路径，不要加 `/v1`）
`ANTHROPIC_AUTH_TOKEN`	API Key
`ANTHROPIC_MODEL`	默认模型名称

辅助变量：

环境变量	用途	建议值
`ANTHROPIC_SMALL_FAST_MODEL`	轻量任务模型	同 `ANTHROPIC_MODEL`
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Haiku 别名映射
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Sonnet 别名映射
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Opus 别名映射
`API_TIMEOUT_MS`	请求超时（ms）	`600000`（10 分钟）
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	禁止遥测	`1`

4.2 硅基流动 SiliconFlow（推荐首选）

国内直连、注册即送额度、一个 Key 通吃 DeepSeek/GLM/Qwen/Kimi。

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的APIKey",
    "ANTHROPIC_BASE_URL": "https://api.siliconflow.cn",
    "ANTHROPIC_MODEL": "deepseek-ai/DeepSeek-V3.2",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-ai/DeepSeek-V3.2"
  }
}

⚠️ 注意： SiliconFlow 的 ANTHROPIC_BASE_URL 不要加 /v1 后缀，Claude Code 会自动拼接路径。

可用模型 ID：

模型	模型 ID
DeepSeek V3.2	`deepseek-ai/DeepSeek-V3.2`
DeepSeek R1	`Pro/deepseek-ai/DeepSeek-R1`
DeepSeek R2	`Pro/deepseek-ai/DeepSeek-R2`
GLM-5.1	`Pro/zai-org/GLM-5.1`
GLM-4.7	`Pro/zai-org/GLM-4.7`
Qwen3-Plus	`Qwen/Qwen3-Plus`
Kimi K2	`moonshotai/Kimi-K2-Instruct-0905`

一键配置脚本：

bash -c "$(curl -fsSL https://sf-maas-uat-prod.oss-cn-shanghai.aliyuncs.com/sample/ccsf_v260130.sh)"

4.3 DeepSeek 官方 API

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你的DeepSeek_API_Key",
    "ANTHROPIC_MODEL": "deepseek-chat",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat",
    "API_TIMEOUT_MS": 600000,
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  }
}

模型	用途	输入价格	输出价格
`deepseek-chat`	常规编码	$0.27/M	$1.10/M
`deepseek-reasoner`	复杂推理	$0.55/M	$2.19/M

API Key 获取： platform.deepseek.com
上下文： 100 万 Token
性价比： 约为 Claude 的 1/10–1/20

4.4 阿里云百炼——通义千问 Qwen

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://dashscope-intl.aliyuncs.com/apps/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你的DashScope_API_Key",
    "ANTHROPIC_MODEL": "qwen3.6-plus",
    "ANTHROPIC_SMALL_FAST_MODEL": "qwen3-coder-plus"
  }
}

推荐模型：

模型	说明
`qwen3.6-plus`	旗舰 480B 参数，综合能力最强
`qwen3-coder-plus`	专为编程优化（需订阅 Coding Plan）

按量付费端点：https://dashscope.aliyuncs.com/compatible-mode/

魔搭免费额度： https://api-inference.modelscope.cn（每日 2000 次免费调用）

4.5 智谱 AI——GLM 系列

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你的智谱API_Key",
    "ANTHROPIC_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.6",
    "API_TIMEOUT_MS": 3000000
  }
}

一键配置脚本：

curl -fsSL "https://cdn.bigmodel.cn/install/claude_code_env.sh" | bash

4.6 月之暗面——Kimi

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.moonshot.cn/v1",
    "ANTHROPIC_AUTH_TOKEN": "你的Moonshot_API_Key",
    "ANTHROPIC_MODEL": "kimi-k2.5"
  }
}

4.7 MiniMax

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.minimax.io/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你的MiniMax_API_Key",
    "ANTHROPIC_MODEL": "MiniMax-M2.7"
  }
}

4.8 国内厂商配置速查表

平台	ANTHROPIC_BASE_URL	推荐模型
SiliconFlow	`https://api.siliconflow.cn`	`deepseek-ai/DeepSeek-V3.2`
DeepSeek	`https://api.deepseek.com/anthropic`	`deepseek-chat`
阿里百炼	`https://dashscope-intl.aliyuncs.com/apps/anthropic`	`qwen3.6-plus`
智谱 GLM	`https://open.bigmodel.cn/api/anthropic`	`glm-4.6`
Kimi	`https://api.moonshot.cn/v1`	`kimi-k2.5`
MiniMax	`https://api.minimax.io/anthropic`	`MiniMax-M2.7`
魔搭免费	`https://api-inference.modelscope.cn`	每日 2000 次免费

5. 持久化配置——三种方式

5.1 settings.json（推荐）

mkdir -p ~/.claude

编辑 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的APIKey",
    "ANTHROPIC_MODEL": "deepseek-chat"
  }
}

5.2 Shell 配置文件

# ~/.bashrc 或 ~/.zshrc
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="sk-你的APIKey"
export ANTHROPIC_MODEL="deepseek-chat"

# 重新加载
source ~/.bashrc

5.3 Windows 永久环境变量

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.deepseek.com/anthropic", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "你的API Key", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "deepseek-chat", "User")

6. 多模型切换方案

6.1 Shell 函数——会话级切换

# ~/.bashrc
deepseek() {
    export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
    export ANTHROPIC_AUTH_TOKEN="${DEEPSEEK_API_KEY}"
    export ANTHROPIC_MODEL="deepseek-chat"
    export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
    claude "$@"
}

qwen() {
    export ANTHROPIC_BASE_URL="https://dashscope-intl.aliyuncs.com/apps/anthropic"
    export ANTHROPIC_AUTH_TOKEN="${DASHSCOPE_API_KEY}"
    export ANTHROPIC_MODEL="qwen3.6-plus"
    claude "$@"
}

glm() {
    export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic"
    export ANTHROPIC_AUTH_TOKEN="${ZHIPU_API_KEY}"
    export ANTHROPIC_MODEL="glm-4.6"
    claude "$@"
}

6.2 Claude Code Router（CCR）——会话内动态切换

npm install -g @taohaowei/claude-code-router
ccr code   # 启动路由增强版

在聊天中直接使用：

/model deepseek,deepseek-reasoner     # 切换到 DeepSeek 推理模式
/model openrouter,anthropic/claude-3.7-sonnet:thinking
/model ollama,qwen2.5-coder:latest    # 本地模型

命令在请求中间阶段被检测，最高路由优先级
仅影响当前消息（不跨会话持久化）
@taohaowei 分支支持 DeepSeek reasoning_content 多轮回放，修复 Thinking 模式 400 错误

6.3 CC-Switch——图形化桌面工具

GitHub： github.com/farion1231/cc-switch
跨平台桌面应用，GUI 一键切换 API 服务商
预置 20+ 服务商模板
支持配置同步

6.4 claude-shadow——命令行配置向导

npm install -g claude-shadow
claude-shadow
# 交互式选择 provider（DeepSeek / SiliconFlow / Ollama 等）
# 支持 on/off 在代理和原生模式间切换

7. 权限配置——常用实践

7.1 项目级配置（`.claude/settings.json`）

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Write(/src/**)",
      "Edit(/src/**)",
      "Bash(npm run *)",
      "Bash(npm test *)",
      "Bash(npm build *)",
      "Bash(npm lint *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(gh pr *)",
      "Bash(npx prisma *)",
      "Bash(* --version)",
      "Bash(* --help)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(.env*)",
      "Read(**/*.pem)",
      "Read(**/*secret*)",
      "Edit(.env*)",
      "Edit(/.github/workflows/**)"
    ]
  }
}

7.2 权限模式语法

模式	匹配
`Bash(npm run *)`	以 `npm run` 开头的命令（空格前 `*` 强制词边界）
`Bash(ls*)`	`ls -la`、`lsof` 等（无词边界）
`Read(.env*)`	所有 `.env` 文件
`Edit(/src/**)`	`src/` 下的文件（相对项目根）
`Read(//etc/passwd)`	绝对路径（双斜杠前缀）
`mcp__server-name__tool-name`	特定 MCP 工具
`mcp__github__*`	某 MCP 服务器的全部工具

8. Hooks——确定性执行保障

8.1 17 个生命周期事件

事件	触发时机	可阻断
`SessionStart`	会话启动	—
`UserPromptSubmit`	用户提交提示词	—
`PreToolUse`	工具执行前	✅
`PostToolUse`	工具执行成功	—
`PostToolUseFailure`	工具执行失败	—
`PreCompact`	上下文压缩前	—
`Stop`	Claude 完成回复	—
`SessionEnd`	会话终止	—
`SubagentStart/Stop`	子 Agent 启停	—
`Notification`	通知发送	—
`TaskCompleted`	任务完成	—
`ConfigChange`	配置文件变更	—
`WorktreeCreate/Remove`	Worktree 创建/删除	—
`TeammateIdle`	队友空闲	—
`PermissionRequest`	权限弹窗显示	—

8.2 示例：阻止敏感命令

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/block-secrets.sh\"",
        "statusMessage": "Running security check..."
      }]
    }]
  }
}

配套脚本 block-secrets.sh：

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -qE '(password|secret|token|api.?key)'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Command contains secret information — blocked"
    }
  }'
  exit 0
fi
exit 0

9. MCP 配置

9.1 项目级 `.mcp.json`

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_DSN}"],
      "env": {
        "DB_DSN": "${DB_DSN:-postgresql://readonly:pass@localhost:5432/dev}"
      }
    }
  }
}

9.2 MCP 作用域

作用域	存储位置	范围
`local`	`~/.claude.json`	仅当前项目
`project`	`.mcp.json`	当前项目
`user`	`~/.claude.json`	所有项目

9.3 CLI 管理命令

# 添加 HTTP 传输的 MCP 服务器
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 添加 stdio 传输的 MCP 服务器
claude mcp add --transport stdio --env AIRTABLE_API_KEY=$KEY airtable -- npx -y airtable-mcp-server

10. 模型选型建议

场景	推荐模型	理由
日常编码	DeepSeek V3.2 / Qwen3.6-Plus	性价比高、中文优秀、响应速度快
复杂架构设计	DeepSeek R2 / GLM-5.1	百万上下文 + 强推理能力
代码审查	Kimi K2.6	300 并行子 Agent
省钱优先	DeepSeek + 魔搭免费额度	成本趋近于零
离线/隐私	Ollama 本地部署	数据不出网
企业合规	阿里云百炼 / 智谱 AI	国内云厂商，数据不出境

10.1 混合策略（推荐）

日常任务 → DeepSeek（省钱，缓存命中 $0.028/M token）
复杂任务 → 原生 Claude（工具调用、提示缓存、扩展思考完整能力）
代码审查 → Kimi K2.6（多 Agent 并行）
离线场景 → Ollama 本地 Qwen/DeepSeek

11. 常见问题与故障排查

问题	原因	解决方案
401 Unauthorized	API Key 错误或 Base URL 不对	检查 Key；确认 Base URL 不要加 `/v1` 后缀
Thinking 400 错误	DeepSeek R1 推理模式多轮问题	使用 `@taohaowei/cc-router` 分支；或 `/config` 关闭 thinking
网络超时	国内到海外延迟高	设置 `API_TIMEOUT_MS=600000`；配置代理 `$env:HTTPS_PROXY="http://127.0.0.1:7890"`
`claude` 命令不识别	PATH 未更新	重启终端；或手动添加 npm 全局安装路径到 PATH
`/model` 不生效	未使用代理/路由器	`/model` 是 CCR 等路由工具的功能，原生 Claude Code 不支持
工具调用退化	第三方模型 tool-calling 不完善	第三方模型在工具调用、扩展思考、提示缓存等方面会退化，这是普遍现象
权限 Deny 覆盖	项目级 permissions 替换全局	在项目 `settings.json` 中重新列出全局允许的工具
Windows Hook 不生效	Unix 依赖	使用 WSL 获完整体验；或手动编写 PowerShell Hook

12. 安全最佳实践

API Key 绝不入库：仅通过环境变量或 settings.local.json 管理。
Deny 规则不是安全边界：它们是字符串匹配，可被绕过。硬安全需求需使用 OS 级权限或容器化。
CLAUDE.md < 300 行：超长文件导致模型均匀地忽略所有指令。将工作流规则移入 /skills/。
Hooks 是强制执行层：CLAUDE.md 描述期望，PreToolUse Hooks 强制执行。
使用 settings.local.json 管理敏感信息：API Key 等私密配置放入 settings.local.json（自动 gitignore），通用的模型和 Hook 配置可放入 settings.json。
使用 $CLAUDE_PROJECT_DIR 写 Hook 脚本中的可移植路径。

参考资源

官方文档： code.claude.com/docs
npm 包： @anthropic-ai/claude-code
CC-Switch： github.com/farion1231/cc-switch
CC-Router： github.com/taohaowei/claude-code-router
claude-shadow： npmjs.com/package/claude-shadow
SiliconFlow 文档： docs.siliconflow.cn
DeepSeek API： platform.deepseek.com
阿里百炼： dashscope.aliyun.com
智谱 AI： open.bigmodel.cn

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

KV Cache 到底是什么？一文讲透大模型推理加速原理

AtomGit开源社区

【Agentic RL / 强化学习框架】Miles 项目技术分析---（2）--- 关键技术

的本质是一个适配器模式——它将"Agent 多轮交互"（业务关注点）与"RL 训练数据生产"（基础设施关注点）完全解耦。这条解耦线画在了generate()函数上。线以上是 Agent 开发者的世界——OpenAI API、工具调用、业务逻辑。线以下是 RL 基础设施的世界——Session Server、TITO、token 对齐、loss mask、异常降级。Agent 开发者不需要知道线以下

AtomGit开源社区

Faust：把 Kafka Streams 搬到 Python 里

Faust 是 Robinhood 开源的 Python 流处理库（6.8k Star），将 Kafka Streams 功能引入 Python 生态。它无需 DSL，基于 async/await 语法，支持静态类型检查，通过装饰器定义流处理逻辑。Faust 提供分布式 K/V 存储和状态管理，支持窗口聚合与故障恢复，单核每秒可处理数万事件，天然支持水平扩展。与主流 Python 库（如 NumP

AtomGit开源社区

所有评论(0)

查看更多评论

G_whang

@G_whang

已为社区贡献6条内容

Claude Code 安装与国内模型配置指南

G_whang

1. Claude Code 概述

1.1 核心能力

2. 安装

2.1 前置条件

2.2 方式一：npm 全局安装

2.3 方式二：官方脚本

2.4 首次运行——绕过登录引导

3. 配置体系

3.1 文件层级

3.2 优先级（从高到低）

3.3 settings.json 结构

3.4 权限模式

4. 接入国内大模型

4.1 核心配置原理

4.2 硅基流动 SiliconFlow（推荐首选）

4.3 DeepSeek 官方 API

4.4 阿里云百炼——通义千问 Qwen

4.5 智谱 AI——GLM 系列

4.6 月之暗面——Kimi

4.7 MiniMax

4.8 国内厂商配置速查表

5. 持久化配置——三种方式

5.1 settings.json（推荐）

5.2 Shell 配置文件

5.3 Windows 永久环境变量

6. 多模型切换方案

6.1 Shell 函数——会话级切换

6.2 Claude Code Router（CCR）——会话内动态切换

6.3 CC-Switch——图形化桌面工具

6.4 claude-shadow——命令行配置向导

7. 权限配置——常用实践

7.1 项目级配置（.claude/settings.json）

7.2 权限模式语法

8. Hooks——确定性执行保障

8.1 17 个生命周期事件

8.2 示例：阻止敏感命令

9. MCP 配置

9.1 项目级 .mcp.json

9.2 MCP 作用域

9.3 CLI 管理命令

10. 模型选型建议

10.1 混合策略（推荐）

11. 常见问题与故障排查

12. 安全最佳实践

参考资源

所有评论(0)

温馨提示：您尚未绑定手机号

G_whang

7.1 项目级配置（`.claude/settings.json`）

9.1 项目级 `.mcp.json`