A Complete Guide to Claude Code Configuration

前言

Claude Code 是 Anthropic 推出的 AI 编程助手。它不是一个简单的"聊天窗口"，而是一个深度集成到开发工作流中的 Agent——能读写文件、执行命令、搜索代码、管理 Git，甚至可以自动创建 PR、调度定时任务。

Claude Code 有三种形态：

三种形态共享同一套配置体系，所以无论你使用哪种，本文的配置方法都适用。本文将以 VSCode 扩展 + 远程服务器的场景为主线展开。

用好 Claude Code 的关键在于配置。本文将从头到尾覆盖所有配置维度，从基础的 settings.json 到高级的 MCP 服务器集成。

远程开发环境配置

很多开发者会在一台高配远程服务器（比如配备 RTX 4090 的开发机）上运行 Claude Code。通过 VSCode 的 Remote SSH 功能连接远程服务器，再安装 Claude 扩展，就能在远程环境里享受 AI 辅助编程。

环境搭建步骤

1. 服务器准备：确保远程服务器已安装 VSCode Server（通过 Remote SSH 首次连接时会自动安装）

2. 安装 Claude 扩展：在 VSCode 扩展市场搜索 "Claude Code" 并安装。安装后扩展会自动在远程服务器上创建 ~/.claude/ 配置目录

3. 设置工作区根目录：Claude Code 的工作范围取决于 VSCode 打开的根目录（即你在 Remote SSH 中打开的文件夹）。它默认能访问整个工作区的文件，但不会越界到根目录之外

4. 验证安装：打开 VSCode 命令面板（Ctrl+Shift+P），输入 "Claude Code: Start" 启动会话。如果看到对话界面，说明安装成功

工作区根目录的配置含义

理解 Claude Code 的"根目录"概念很重要——它决定了 AI 的感知范围和行为边界：

• 配置文件位置：项目级配置 .claude/settings.json 和 .claude/CLAUDE.md 必须放在工作区根目录下
• 命令执行上下文：所有 bash 命令默认在根目录下执行
• 文件访问权限：AI 默认只能读写根目录内的文件
• CLAUDE.md 加载：Claude 启动时会读取根目录下的 .claude/CLAUDE.md

因此，建议你在远程服务器上这样组织：

~/projects/
  ├── project-a/          # VSCode 打开此目录
  │   ├── .claude/
  │   │   ├── settings.json
  │   │   └── CLAUDE.md
  │   └── src/
  └── project-b/          # 另一个项目
      └── .claude/

如果你的项目有多个子仓库，可以将它们组织在一个父目录下统一管理。

服务器个人配置

在远程服务器上使用 Claude Code For Vscode，需要在用户目录下完成初始配置。

1. 安装 Claude Code for VSCode

在 VSCode 扩展市场搜索 "Claude Code for vscode" 并安装。安装后，扩展会自动在 ~/.claude/ 目录下创建所需的配置文件夹。你也可以手动创建：

mkdir -p ~/.claude

2. 配置 config文件 —— 跳过登录界面

在 ~/.claude/ 目录下创建 config.json，写入apikey，不用详细api，写apikey就行：

{
  "primaryApiKey": "apikey"
}

配置好 config.json 后，启动 Claude Code 时会直接进入对话界面，跳过 API Key 的登录弹窗。这对远程服务器这种非交互式场景尤其方便。

3. 配置环境变量

在 ~/.claude/ 目录下找到 settings.json（如果不存在则手动创建），通过 env 字段配置环境变量：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxx",
    "ANTHROPIC_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
    "API_TIMEOUT_MS": "3000000"
  }
}

各环境变量说明：

模型映射说明：Claude Code 内部会根据任务复杂度选择不同层级的模型（Haiku 用于简单任务、Sonnet 默认、Opus 复杂推理）。通过 ANTHROPIC_DEFAULT_*_MODEL 变量，你可以将这三个层级映射到第三方兼容模型，实现"降级平替"。如果第三方只提供一个模型，三个变量设为同一个值即可。

推荐做法：env 字段适合统一管理环境变量。敏感信息（如 ANTHROPIC_AUTH_TOKEN）建议通过 shell profile 设置而非写在 settings.json 中，避免意外提交到 Git。

配置文件总览

Claude Code 的配置体系由三个层次组成：

加载优先级：settings.local.json > settings.json > 全局 settings.json。这意味着你可以在项目级覆盖全局设置。

settings.json 配置详解

权限管理（Permissions）

Claude Code 的权限系统控制 AI 可以执行哪些操作。这是最常用的配置项：

{
  "permissions": {
    "allow": [
      "bash: npm",
      "bash: git",
      "bash: npx",
      "bash: cargo",
      "bash: go",
      "read"
    ],
    "allowSettings": [
      "Bash",
      "Read",
      "Edit",
      "Write"
    ],
    "defaultBehavior": "allow-once"
  }
}

• allow：自动允许的命令前缀匹配列表
• allowSettings：允许的工具（无需每次确认）
• defaultBehavior：未匹配时的行为，可选 allow、deny、allow-once

技巧：可以用 fewer-permission-prompts 技能自动分析你的使用习惯并生成权限白名单。

模型选择

{
  "model": "claude-sonnet-4-6",
  "fastModel": "claude-haiku-4-5-20251001"
}

• model：主模型，用于复杂推理和代码生成
• fastModel：简单任务使用的轻量模型，通过 /fast 命令切换

可用模型包括 Claude Opus 4.7、Sonnet 4.6、Haiku 4.5 等。日常开发推荐 Sonnet，复杂重构切 Opus。

主题与外观

{
  "theme": {
    "mode": "dark",
    "codeBlockTheme": "monokai",
    "markdownRenderer": "enhanced"
  }
}

在 VSCode 扩展中，主题跟随 IDE 设置；在终端中使用时，可以单独配置。通过 /config 命令可以快速切换 theme 和 model。

代理与网络

{
  "proxy": {
    "url": "http://127.0.0.1:7890",
    "noProxy": ["localhost", "127.0.0.1", ".internal.com"]
  }
}

如果你的网络环境需要代理才能访问 API，在这里配置。noProxy 用于排除不需要代理的地址。

API Key 配置

Claude Code 需要 API Key 才能工作。配置方式取决于你使用的形态：

方式一：环境变量（推荐）

# 写入 shell 配置文件（~/.bashrc、~/.zshrc 等）
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"

这是最推荐的方式——配置一次，所有形态（CLI、VSCode 扩展、桌面 App）都会自动读取，而且不会意外提交到 Git。

方式二：VSCode 扩展（config.json）

VSCode 扩展没有内置的 API Key 输入界面。安装扩展后，在 ~/.claude/config.json 中配置：

{
  "primaryApiKey": "sk-ant-xxxxxxxxxxxx"
}

配置好 primaryApiKey 后，启动 Claude Code 时会直接进入对话界面，跳过登录弹窗。这个文件保存在用户目录下，不会因为切换项目而丢失。

方式三：CLI 登录

claude login

按提示输入 API Key，CLI 会自动将其保存到 ~/.claude/credentials。

API Key 推荐实践

1. 使用 API Key 而不是直接付费订阅：通过 Anthropic API 按量付费，在 console.anthropic.com 申请。API Key 模式更灵活，支持更精细的用量控制

2. 额度管理：在 Anthropic Console 中设置用量限额（Spend Limits），防止意外高额账单。建议先设一个较低的月限额，了解用量后再调整

3. 国内网络访问：如果服务器位于国内直连 Anthropic API 不稳定，有以下方案：

   • 配合上面的 proxy 配置走代理
   • 使用 Anthropic 官方支持的第三方代理服务
   • 自建反向代理转发 API 请求

4. 多 Key 轮换：对于高频使用场景，可以准备多个 API Key，但 Claude Code 本身不内置轮换机制，需要自己在外层管理

5. 安全提醒：永远不要将 API Key 提交到 Git 仓库。建议将 ANTHROPIC_API_KEY 加入 .gitignore，或使用环境变量方式配置

本地 CLI 多配置管理（ccswitch）

如果你使用 Claude Code CLI 并需要在多个 API 后端或模型之间切换，ccswitch 是一个轻量的客户端管理工具。

安装

npm install -g ccswitch

交互式客户端

安装后，直接在终端运行 ccswitch 即可进入交互式选择界面：

ccswitch

你会看到一个带编号的列表，显示所有已配置的环境，例如：

❯ ccswitch

  Available Configurations:
  ┌──────────────────────────────────────────────────┐
  │  1) official    ◄ 当前使用                         │
  │  2) deepseek                                      │
  │  3) local                                         │
  └──────────────────────────────────────────────────┘
  Enter number (or q to quit):

输入编号即可无缝切换。切换后 Claude Code 会立即读取新配置，无需退出当前会话。

其他命令

ccswitch list      # 列出所有配置并标注当前使用的配置
ccswitch current   # 查看当前激活的配置名称

配置管理

ccswitch 的配置文件位于 ~/.ccswitch/config.json，每套配置就是一组环境变量：

{
  "configs": {
    "official": {
      "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxxxxxx",
      "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
      "ANTHROPIC_MODEL": "claude-sonnet-4-6"
    },
    "deepseek": {
      "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxx",
      "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
      "ANTHROPIC_MODEL": "deepseek-v4-flash",
      "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
      "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash",
      "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro"
    },
    "local": {
      "ANTHROPIC_BASE_URL": "http://localhost:8080/anthropic",
      "ANTHROPIC_AUTH_TOKEN": "sk-test",
      "ANTHROPIC_MODEL": "local-model"
    }
  }
}

配置好之后，运行 ccswitch 选择对应编号即可切换。它的原理是切换时自动更新 ~/.claude/ 下的环境变量，对 Claude Code 完全透明，无需重启。

MCP 服务器集成

MCP（Model Context Protocol）是 Claude Code 的插件系统，让 AI 能访问外部工具和数据源：

{
  "mcpServers": {
    "github": {
      "type": "command",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/claude-mcp-github"]
    },
    "filesystem": {
      "type": "command",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/claude-mcp-fs", "/allowed/path"]
    },
    "database": {
      "type": "command",
      "command": "python",
      "args": ["mcp_servers/db_server.py"]
    }
  }
}

MCP 服务器可以赋予 Claude Code 全新的能力——查询数据库、调用 API、操作 GitHub Issues、读取监控面板等。你可以用任何语言编写自定义 MCP 服务器（官方 SDK 支持 TypeScript 和 Python）。

答案偏好

{
  "answers": {
    "allowCommands": "yes",
    "autoConfirm": ["bash: npm install", "bash: pip install"],
    "alwaysAllowBrowser": false
  }
}

将你经常需要确认的选项预设好，减少交互确认次数。

其他实用设置

{
  "maxConcurrentCommands": 3,
  "maxReadDepth": 100,
  "verbose": false,
  "clipboard": {
    "read": true,
    "write": true
  }
}

• maxConcurrentCommands：并行执行的最大命令数
• maxReadDepth：读取文件时的最大行数
• verbose：是否输出详细日志
• clipboard：是否允许访问系统剪贴板

CLAUDE.md —— 项目的"记忆"

CLAUDE.md 是项目根目录下的 Markdown 文件，它告诉 Claude Code 关于项目的一切。每次对话开始，Claude 都会自动读取这个文件。

基础结构

# Project

## Build Commands
- `npm run dev` - 启动开发服务器
- `npm run build` - 构建生产版本
- `npm test` - 运行所有测试
- `npm run test:watch` - 监听模式运行测试

## Code Style
- 使用 TypeScript，严格模式
- 缩进使用 2 空格
- 组件使用函数式 + hooks
- CSS 使用 Tailwind

## Architecture
- 前端：Next.js 14 + App Router
- 后端：Fastify + Prisma
- 数据库：PostgreSQL
- ...

## Conventions
- 文件名使用 kebab-case
- 组件名使用 PascalCase
- API 路由使用 RESTful 风格

最佳实践

1. 保持简洁：CLAUDE.md 不是文档，是速查手册。每一条都应该是 AI 需要知道的"潜规则"
2. 优先放命令：构建、测试、lint 命令放最前面——这些是最常用的
3. 记录约定：命名规范、目录结构、设计模式等代码中看不到的信息
4. 更新及时：项目架构变化时同步更新
5. 全局 vs 项目级：
   • ~/.claude/CLAUDE.md：全局指令，比如"永远用中文回答"
   • .claude/CLAUDE.md：项目特定，只影响当前仓库

配置哲学

最后分享几条配置心得：

1. 权限先宽后严：先允许所有操作，观察 Claude Code 的行为模式，然后用 fewer-permission-prompts 技能生成最小权限配置
2. CLAUDE.md 动态维护：没有一劳永逸的配置，项目演进，CLAUDE.md 也要跟着演进
3. MCP 按需添加：不要一股脑加一堆 MCP 服务器，每次只加你真正需要的

总结

Claude Code 的配置体系虽然层次不少，但核心逻辑很清晰：

• settings.json：控制 Claude Code 的行为和权限
• CLAUDE.md：告诉 Claude 你的项目怎么运作
• env 环境变量：管理 API 端点、认证和模型映射

本文介绍了最常用的配置项，但 Claude Code 的能力远不止于此。Skill 和 MCP 是两个值得深入探索的方向——Skill 提供了内置的领域专家能力（代码审查、安全扫描、架构规划等），MCP 则允许 Claude Code 接入外部工具和数据源。配置好基础环境后，建议按需启用 Skill 并逐步接入 MCP 服务器，让 Claude Code 融入你的开发工作流。