附录 B：配置与环境变量

本附录详细说明 Claude Code 的配置系统和环境变量。

Note

环境变量配置文件位于 .env.example，配置文件通常存放在 .claude/ 目录。

B.1 环境变量详解

B.1.1 API 认证配置

变量	必填	说明
`ANTHROPIC_API_KEY`	二选一	API Key，通过 `x-api-key` 请求头发送
`ANTHROPIC_AUTH_TOKEN`	二选一	Auth Token，通过 `Authorization: Bearer` 请求头发送

Warning

两种认证方式二选一，不能同时使用。ANTHROPIC_API_KEY 适用于直接 API 调用，ANTHROPIC_AUTH_TOKEN 适用于 OAuth 认证场景。

B.1.2 API 端点配置

变量	必填	说明
`ANTHROPIC_BASE_URL`	否	自定义 API 端点，默认为 Anthropic 官方 API

Tip

设置 ANTHROPIC_BASE_URL 可接入兼容 Anthropic API 的第三方服务（如 MiniMax、OpenRouter 等）。

B.1.3 模型配置

变量	必填	说明
`ANTHROPIC_MODEL`	否	默认使用的模型名称
`ANTHROPIC_DEFAULT_SONNET_MODEL`	否	Sonnet 级别模型映射
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	否	Haiku 级别模型映射
`ANTHROPIC_DEFAULT_OPUS_MODEL`	否	Opus 级别模型映射

// 模型配置示例（MiniMax API）
ANTHROPIC_MODEL=MiniMax-M2.7-highspeed
ANTHROPIC_DEFAULT_SONNET_MODEL=MiniMax-M2.7-highspeed
ANTHROPIC_DEFAULT_HAIKU_MODEL=MiniMax-M2.7-highspeed
ANTHROPIC_DEFAULT_OPUS_MODEL=MiniMax-M2.7-highspeed

B.1.4 超时与性能配置

变量	必填	说明
`API_TIMEOUT_MS`	否	API 请求超时时间（毫秒），默认 600000（10分钟）

B.1.5 遥测与网络配置

变量	必填	说明
`DISABLE_TELEMETRY`	否	设为 `1` 禁用遥测数据收集
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	否	设为 `1` 禁用非必要网络请求

Note

建议在本地运行时设置 DISABLE_TELEMETRY=1 和 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 以减少不必要的网络请求。

B.1.6 完整 .env 配置示例

# API 认证（二选一）
ANTHROPIC_API_KEY=sk-xxx
# ANTHROPIC_AUTH_TOKEN=sk-xxx

# API 端点（可选）
ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic

# 模型配置
ANTHROPIC_MODEL=MiniMax-M2.7-highspeed
ANTHROPIC_DEFAULT_SONNET_MODEL=MiniMax-M2.7-highspeed
ANTHROPIC_DEFAULT_HAIKU_MODEL=MiniMax-M2.7-highspeed
ANTHROPIC_DEFAULT_OPUS_MODEL=MiniMax-M2.7-highspeed

# 超时配置（毫秒）
API_TIMEOUT_MS=3000000

# 禁用遥测和非必要网络请求
DISABLE_TELEMETRY=1
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

B.2 配置文件说明

B.2.1 .claude/ 目录配置

.claude/ 目录是 Claude Code 的项目配置目录，包含以下配置文件：

文件	用途
`settings.json`	项目级设置，包含权限规则、MCP 服务器配置等
`settings.local.json`	本地设置（不提交到版本控制）
`commands/`	自定义命令目录
`skills/`	自定义 Skill 目录
`agents/`	Agent 定义目录

// settings.json 示例
{
  "permissions": {
    "allow": ["Bash(git *)", "Read", "Edit"],
    "deny": ["Bash(rm -rf *)"]
  },
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-playwright"]
    }
  }
}

B.2.2 MCP 服务器配置

MCP (Model Context Protocol) 服务器配置支持多种格式：

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server-name"],
      "env": {
        "API_KEY": "xxx"
      }
    },
    "remote-server": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer xxx"
      }
    }
  }
}

B.2.3 Skills 配置

Skills 可以通过多种方式配置：

内置 Skills: 通过 BundledSkillDefinition 注册
项目 Skills: 在 .claude/skills/ 目录中定义
插件 Skills: 通过插件系统加载

// BundledSkillDefinition 结构
type BundledSkillDefinition = {
  name: string;
  description: string;
  aliases?: string[];
  argumentHint?: string;
  allowedTools?: string[];
  model?: string;
  disableModelInvocation?: boolean;
  userInvocable?: boolean;
  isEnabled?: () => boolean;
  hooks?: HooksSettings;
  context?: 'inline' | 'fork';
  agent?: string;
  files?: Record<string, string>;
  getPromptForCommand(args, context): Promise<ContentBlockParam[]>;
};

B.2.4 权限配置

权限系统支持三种配置方式：

{
  "permissions": {
    "allow": ["Bash(git *)", "Read", "Edit", "Grep"],
    "deny": ["Bash(rm -rf /*)", "Bash(sudo *)"],
    "ask": ["Bash(npm install *)"]
  },
  "permissionMode": "default"
}

权限模式	说明
`default`	默认模式，根据规则决定
`acceptEdits`	自动接受编辑操作
`bypassPermissions`	绕过所有权限检查
`dontAsk`	不询问用户，自动决策
`plan`	计划模式

B.2.5 Hooks 配置

Hooks 系统支持多种事件类型：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Tool use detected'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "callback",
            "callback": "async (input) => { return { continue: true } }"
          }
        ]
      }
    ]
  }
}

支持的 Hook 事件类型：

事件	触发时机
`PreToolUse`	工具执行前
`PostToolUse`	工具执行后
`PostToolUseFailure`	工具执行失败后
`UserPromptSubmit`	用户提交消息后
`SessionStart`	会话开始时
`Setup`	设置阶段
`SubagentStart`	子 Agent 启动时
`PermissionDenied`	权限拒绝时
`Notification`	通知事件
`PermissionRequest`	权限请求时
`Elicitation`	引导请求时
`CwdChanged`	工作目录变更时
`FileChanged`	文件变更时
`WorktreeCreate`	Worktree 创建时

B.3 命令行参数

B.3.1 启动参数

参数	说明
`-p, --print`	无头模式，单次问答
`--resume`	恢复上次会话
`--session-id`	指定会话 ID
`--permission-mode`	设置权限模式
`--mcp-config`	指定 MCP 配置文件
`--verbose`	详细输出模式
`--debug`	调试模式

B.3.2 模型参数

参数	说明
`--model`	指定使用的模型
`--fallback-model`	设置备用模型

B.3.3 其他参数

参数	说明
`--worktree`	在 Worktree 中运行
`--agent`	指定 Agent 类型
`--help`	显示帮助信息

Tip

完整的命令行参数可通过 ./bin/claude-haha --help 查看。

Keyboard shortcuts

Claude Code 源码解析