Claude Code 技术笔记

一、安装与启动

bash

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

启动命令：

bash

claude                          # 交互模式
claude -p "prompt"              # 打印模式（执行后退出）
claude -c -p "prompt"           # 继续上次会话并执行
claude -r "session-id"          # 恢复指定会话
claude --resume <id>            # 恢复
claude --resume <id> --fork-session  # 恢复并派生新会话
claude --init-only              # 只运行初始化，不进入对话
claude --maintenance            # 维护模式
claude update                   # 更新到最新版本

二、文件与配置

配置文件层级

位置	作用域	是否可提交到 git
`~/.claude/settings.json`	用户级，所有项目	否
`.claude/settings.json`	项目级	是
`.claude/settings.local.json`	项目级本地	否（自动 gitignore）
`/Library/Application Support/ClaudeCode/managed-settings.json` （macOS）	组织管理级	是（管理员控制）
`/etc/claude-code/managed-settings.json` （Linux/WSL）	组织管理级	是（管理员控制）

其他重要路径

路径	说明
`~/.claude/`	用户级配置根目录
`~/.claude/keybindings.json`	键盘快捷键覆盖
`~/.claude/hooks/`	Hook 脚本存放处
`~/.claude/agents/`	用户级子 Agent 定义
`~/.claude/commands/`	用户级 Slash 命令
`~/.claude/skills/`	用户级 Skills
`~/.claude/output-styles/`	输出样式
`~/.claude/memory/`	自动记忆文件
`~/.claude/sessions/`	保存的会话记录
`~/.claude/logs/`	本地日志
`.claude/worktrees/`	Worktree 状态
`CLAUDE.md`	项目级指令文件

配置示例（settings.json）

json

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-...",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-20250514",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-20250514",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-20250514",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-20250514",
    "ANTHROPIC_AUTH_TOKEN": "...",
    "ANTHROPIC_CUSTOM_HEADERS": "x-custom-header: value"
  },
  "model": "claude-sonnet-4-20250514",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Edit(.claude/)",
      "Bash(git log)",
      "Bash(git diff)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(sudo *)"
    ]
  },
  "disableBundledSkills": false,
  "effortLevel": "medium"
}

模型覆盖（modelOverrides）

当提供商的模型 ID 与 Anthropic 默认 ID 不同时使用：

json

{
  "modelOverrides": {
    "claude-sonnet-4-20250514": "bedrock-model-id-xxx",
    "claude-opus-4-20250514": "azure-deployment-name-yyy"
  }
}

三、权限模式

Claude Code 的所有操作均受权限控制。每次执行工具前，系统会根据当前模式决定是否需要用户确认。

五种权限模式

模式	说明	编辑文件	执行命令	切换方式
`default`	默认，每次都问	需确认	需确认	`Shift+Tab` 切换
`acceptEdits`	编辑无需确认，命令仍需确认	自动通过	需确认	`Shift+Tab`
`plan`	规划模式，先出计划再执行	需确认	需确认	`/plan` 或 `Shift+Tab`
`auto`	自动模式，大模型分类器审核	分类器审核	分类器审核	`Shift+Tab`
`dontAsk`	不问（但仍有简单屏障）	自动通过	自动通过	`Shift+Tab`
`bypassPermissions`	绕过一切权限检查（最危险）	全部自动	全部自动	`Shift+Tab` 或 `--dangerously-skip-permissions`

分类器（Auto Mode Classifier）

Auto 模式的核心机制。Claude Code 使用两层模型分类器：

读取层：判断哪些文件/网页可以读取
执行层：判断哪些 Bash/Edit/WebFetch 命令可以执行

分类器本身是一个独立的大模型调用，每次工具调用前都会走一次分类器判断。如果分类器拦截，会显示拦截原因，用户可以手动覆盖。

启用 auto 模式：

bash

claude --permission-mode auto

bypassPermissions 的危险

bypassPermissions 模式会移除所有权限弹窗，Claude 可以：

直接执行 rm -rf 等破坏性命令
直接修改任何文件，包括系统文件
直接发送网络请求
通过写 Python 脚本或 Bash 命令操控整个电脑

开启方式：

bash

claude --permission-mode bypassPermissions
claude --dangerously-skip-permissions

或在 VS Code 插件中勾选 "Allow Dangerously Skip Permissions"。

命令行参数

bash

claude --permission-mode default         # 默认
claude --permission-mode acceptEdits     # 编辑无需确认
claude --permission-mode plan            # 规划模式
claude --permission-mode auto            # 自动模式
claude --permission-mode dontAsk         # 不问
claude --permission-mode bypassPermissions  # 绕过权限

四、常用命令与快捷键

Slash 命令

在输入框中输入 / 列出所有命令。

命令	作用
`/`	列出所有命令
`/clear`	清空当前会话上下文
`/compact`	压缩对话历史以节省 token
`/config` 或 `/settings`	打开配置界面
`/cost`	查看当前会话 token 消耗
`/diff`	查看未提交的代码变更
`/help`	帮助
`/init`	初始化当前项目的 CLAUDE.md
`/keybindings`	打开键盘快捷键配置
`/login`	重新登录
`/logout`	退出登录
`/memory`	查看当前记忆
`/model`	切换模型
`/permissions` 或 `/allowed-tools`	管理工具权限
`/plan`	切换到规划模式
`/resume`	查看可恢复的会话
`/rewind`	回滚到之前的状态
`/status`	查看当前模型/提供商状态

快捷键

快捷键	作用
`Shift+Tab`	循环切换权限模式（default → acceptEdits → auto → dontAsk → bypassPermissions → default）
`Tab`	切换 extended thinking 模式
`Ctrl+O`	切换 verbose 模式（显示 Claude 的推理过程）
`Ctrl+V` / `Cmd+V`	直接粘贴图片（多模态）
`@`	引用文件路径，触发自动补全
`!`	Shell 模式：直接运行命令并将输出加入会话
`:`	Emoji shortcode
`Esc Esc`	打开 rewind 菜单（回滚选项）
`Alt+P`	切换活动模型，保留已输入的文本

命令行参数

bash

claude --model claude-opus-4            # 指定模型
claude --effort low|medium|high|xhigh|max|ultracode  # 设置努力级别
claude --disable-slash-commands         # 禁用 slash 命令
claude --disallowed-tools "Edit" "Bash"  # 禁用指定工具
claude --system-prompt "自定义系统提示词"     # 自定义系统提示词
claude --system-prompt-file ./prompt.md  # 从文件加载系统提示词
claude --exclude-dynamic-system-prompt-sections  # 排除动态系统提示词部分

五、接入第三方模型

Claude Code 的协议层是 Anthropic Messages API。要用 DeepSeek、字节方舟、OpenAI 等第三方模型，必须通过 Anthropic API 兼容的代理层。

方案一：OpenRouter

OpenRouter 提供 Anthropic Messages API 兼容端点。

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api/v1",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-v1-...",
    "ANTHROPIC_MODEL": "openrouter/auto",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek/deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek/deepseek-v4-flash"
  }
}

注意事项：

Claude Code 的多轮对话功能（如 Thinking blocks）在一些非 Claude 模型上可能出 400 错误
Anthropic 原生功能（如 tool use 格式）需要提供商正确翻译
推荐将 Anthropic 1P 设为 OpenRouter 中的高优先级提供商

方案二：LiteLLM 自建代理

对于 OpenAI 格式或本地模型（如 Ollama），需要 LiteLLM 做协议翻译：

bash

pip install litellm
litellm --model openai/gpt-5.4 --port 4000

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_API_KEY": "sk-xxx"
  }
}

方案三：Anthropic 兼容提供商

Z.AI、DeepSeek 等部分提供商原生支持 Anthropic Messages API。配置方式与 OpenRouter 类似，将 ANTHROPIC_BASE_URL 指向对方的 Anthropic-compatible endpoint。

环境变量汇总

变量	说明
`ANTHROPIC_API_KEY`	Anthropic API Key（直接调用时）
`ANTHROPIC_AUTH_TOKEN`	Bearer Token（网关/代理时更常用）
`ANTHROPIC_BASE_URL`	API 基础 URL，用于切换提供商
`ANTHROPIC_MODEL`	默认模型
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Sonnet 级别模型
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Opus 级别模型
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Haiku 级别模型
`ANTHROPIC_SMALL_FAST_MODEL`	快速/轻量模型
`ANTHROPIC_CUSTOM_HEADERS`	自定义请求头

六、Hooks 机制

Claude Code 支持在会话生命周期的多个节点插入自定义逻辑。

事件类型

事件	触发时机
`SessionStart`	会话开始或恢复
`Setup`	`claude --init-only` 或 `claude -p --init` /、`--maintenance` 运行时
`UserPromptSubmit`	用户提交 prompt 之前
`UserPromptExpansion`	用户输入的命令展开为 prompt 之前（可阻止展开）
`PreToolUse`	工具调用之前
`PostToolUse`	工具调用之后
`Stop`	会话结束

匹配器（Matcher）

匹配器	触发条件
`init`	`claude --init-only` 或 `claude -p --init`
`maintenance`	`claude -p --maintenance`
`Read`	读取文件工具
`Write｜Edit`	写入/编辑文件工具
`Bash(...)`	Bash 命令匹配，如 `Bash(rm *)`
`*`	匹配所有

Hook 配置示例

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "jq -e '.tool_input | select(.offset == null or .limit == null)' >/dev/null 2>&1 && echo '{\"systemMessage\": \"token\u8282约规则: 未指定 offset/limit\u7684读取检测\"}' || true"
          }
        ]
      },
      {
        "matcher": "Bash(rm *)",
        "hooks": [
          {
            "type": "ask",
            "message": "即将执行删除操作，是否确认？"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "system_message",
            "message": "每次对话前先检查 CLAUDE.md 中的项目规则"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/session-end-to-vault.sh"
          }
        ]
      }
    ]
  }
}

Hook 类型

类型	作用
`command`	执行 shell 命令
`system_message`	向当前会话插入系统消息
`ask`	向用户提问，据返回决定是否继续
`block`	阻止当前操作

PreToolUse 返回结构

json

{
  "permissionDecision": "allow|ask|deny",
  "systemMessage": "可选的系统消息",
  "userMessage": "可选的用户消息"
}

已知 bug：当 PreToolUse 返回 "ask" 并被用户确认后，bypassPermissions 模式可能会永久丢失，后续所有工具调用都需要手动确认。

七、CLAUDE.md

项目根目录放置 CLAUDE.md，会话开始时自动读取。

markdown

# CLAUDE.md

## 技术栈
- 语言: TypeScript
- 框架: Next.js 14
- 测试: Vitest

## 编码规范
- 使用单引号字符串
- 导入使用绝对路径
- 每个函数需有 JSDoc 注释

## 架构约定
- 业务逻辑放 `src/lib/`
- UI 组件放 `src/components/`
- API 路由放 `src/app/api/`

作用范围：

不是强制约束，是 prompt 级引导
强制约束需要通过 permissions 和 hooks实现

八、模型与努力级别

模型切换

bash

/model sonnet     # 探索和文件阅读
/model opus       # 复杂问题
/model haiku      # 简单任务，省 token

努力级别

级别	说明
`low`	最快，质量最低
`medium`	默认
`high`	更深入推理
`xhigh`	深度推理
`max`	最大推理
`ultracode`	最高级别，用于极复杂代码任务

命令行设置：

bash

claude --effort high

九、其他重要设置

json

{
  "disableBundledSkills": true,
  "permissions": {
    "defaultMode": "default",
    "allow": ["Edit(.claude/)"],
    "deny": ["Bash(rm *)"]
  }
}

设置	说明
`disableBundledSkills`	禁用内置 skills，减少提示词脆胃
`permissions.defaultMode`	默认权限模式
`permissions.allow`	白名单规则数组
`permissions.deny`	黑名单规则数组

版本与发行日期：2026 年 8 月。具体参数以 Anthropic 官方文档为准。

Claude Code 技术笔记 ​

一、安装与启动 ​

二、文件与配置 ​

配置文件层级 ​

其他重要路径 ​

配置示例（settings.json） ​

模型覆盖（modelOverrides） ​

三、权限模式 ​

五种权限模式 ​

分类器（Auto Mode Classifier） ​

bypassPermissions 的危险 ​

命令行参数 ​

四、常用命令与快捷键 ​

Slash 命令 ​

快捷键 ​

命令行参数 ​

五、接入第三方模型 ​

方案一：OpenRouter ​

方案二：LiteLLM 自建代理 ​

方案三：Anthropic 兼容提供商 ​

环境变量汇总 ​

六、Hooks 机制 ​

事件类型 ​

匹配器（Matcher） ​

Hook 配置示例 ​

Hook 类型 ​

PreToolUse 返回结构 ​

七、CLAUDE.md ​

八、模型与努力级别 ​

模型切换 ​

努力级别 ​

九、其他重要设置 ​

Claude Code 技术笔记

一、安装与启动

二、文件与配置

配置文件层级

其他重要路径

配置示例（settings.json）

模型覆盖（modelOverrides）

三、权限模式

五种权限模式

分类器（Auto Mode Classifier）

bypassPermissions 的危险

命令行参数

四、常用命令与快捷键

Slash 命令

快捷键

命令行参数

五、接入第三方模型

方案一：OpenRouter

方案二：LiteLLM 自建代理

方案三：Anthropic 兼容提供商

环境变量汇总

六、Hooks 机制

事件类型

匹配器（Matcher）

Hook 配置示例

Hook 类型

PreToolUse 返回结构

七、CLAUDE.md

八、模型与努力级别

模型切换

努力级别

九、其他重要设置