Claude Code CLI 配置 2026：5 分钟快速上手

如何配置 Claude Code？ 使用 npm install -g @anthropic-ai/claude-code 全局安装 CLI，通过浏览器完成身份认证，然后在项目根目录创建 CLAUDE.md 文件，写入技术栈细节和编码约定。在 .claude/settings.json 中配置权限，并添加格式化钩子，使每次编辑后都能自动修正代码风格。整套配置用时不超过五分钟。 {.answer-block}

目前 ServiceNow 已有超过 29,000 名开发者每日使用 Claude Code¹，Allianz 也在 2026 年初于公司范围内全面推行²。该工具的采纳曲线揭示出一种规律：开发者一旦在自己的终端里体验过 Agent 化编程，就不会再回到从聊天窗口复制粘贴的老路。本快速上手指南是我的 AI 工程系列的一部分——面向使用 Claude 进行开发的工程师的实用指南。下文将带您用约五分钟从零构建出一个可用的 Claude Code 会话，同时提供可长期沿用的真实配置。

TL;DR： 通过 npm install -g @anthropic-ai/claude-code 安装 Claude Code，经浏览器完成身份认证，创建包含项目上下文的 CLAUDE.md 文件，并在 .claude/settings.json 中配置权限。添加一个 Prettier 钩子，每次写入文件后自动格式化。整个配置过程不到五分钟,且配置在会话之间持久保留。

关键要点

独立开发者： CLAUDE.md 加一个格式化钩子即可满足 80% 的需求。建议从默认权限开始,在建立信任的过程中逐步预批准工具。
团队负责人： 将 .claude/settings.json 提交到仓库,让整个团队共享相同的权限白名单和钩子。
安全工程师： 三层权限模型⁴（Ask、Allowlisted、--dangerously-skip-permissions）与信任等级直接对应。Ask 模式要求对每一次写入和每一次命令执行都给出明确批准。

前置条件

在安装 Claude Code 之前,您需要准备三样东西：

Node.js 18 或更高版本。 Claude Code 以 npm 包形式发布³。检查版本：

node --version
# v18.0.0 or higher

如需安装或升级 Node.js,可使用 nvm 或直接从 nodejs.org 下载。

具备 API 访问权限的 Anthropic 账户。 在 console.anthropic.com 的 Settings > API Keys 中创建 API 密钥。Claude Code 按 token 从您的 API 余额中扣费,或者您也可以使用 Max 订阅计划（截至 2026 年 3 月,个人版每月 100 美元,团队版每月 200 美元）⁶。请妥善保存密钥,稍后在认证步骤会用到。

一个终端。 Claude Code 可运行在任意终端模拟器中：Terminal.app、iTerm2、Windows Terminal、Alacritty,或 VS Code 的集成终端。建议使用宽度至少 120 列的终端,因为 Claude Code 会显示文件 diff 和工具输出,这类内容在较宽的水平空间中更易阅读。

安装

通过 npm 全局安装 Claude Code：

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

验证安装是否成功：

claude --version

您应当能在 stdout 看到打印出的版本号。如果提示 “command not found”,说明 npm 的全局 bin 目录未加入 PATH。运行 npm config get prefix,将其 /bin 子目录添加到 shell 的 PATH 中。在通过 Homebrew 安装 Node 的 macOS 上,prefix 通常为 /usr/local,如果 /usr/local/bin 尚未加入 PATH,请将其加入。

常见安装问题： 如果在 npm install -g 过程中遇到 EACCES 权限错误,不要使用 sudo。正确做法是将 npm 配置为使用用户可写目录⁷：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to your shell profile (~/.zshrc or ~/.bashrc):
export PATH="$HOME/.npm-global/bin:$PATH"

首次启动时,Claude Code 会打开浏览器进入 Anthropic 控制台完成 OAuth 认证。您登录并授权后,Claude Code 会将 token 保存在本地 ~/.claude/ 目录中。另一种方式是在启动前设置 ANTHROPIC_API_KEY 环境变量。无论采用哪种方式,凭据都只存储在您本机,且仅用于对 API 请求进行身份认证。

首次会话

进入任意项目目录并运行：

cd ~/Projects/my-app
claude

Claude Code 会启动一个交互式 REPL 会话。在新项目中首次启动时,Claude 会自动完成以下几件事：

扫描目录结构,了解项目布局
读取配置文件,如 package.json、pyproject.toml 或 Cargo.toml,以识别技术栈
查找项目根目录的 CLAUDE.md 文件,以获取项目特定指令

试着输入一条简单提示,确认一切正常：

> Explain the structure of this project

Claude 会读取您的文件、归纳架构,并在终端中给出回复。您会实时看到工具调用（每一次文件读取、每一次命令执行）,在任何写入操作之前也会先请求您的许可。

首次会话时需要留意什么。 请重点关注两件事：工具调用（在每次动作前实时显示）和权限提示。工具调用会揭示 Claude 浏览代码库的方式。您会发现它读取了一些您可能没想到要查看的文件,这往往能带来有用的上下文。权限提示则让您在任何内容落盘之前,清晰看到 Claude 打算做什么。如果某次提议的修改看起来不对,请拒绝并给出说明。Claude 会在会话中根据您的反馈调整方向⁸。

设置 CLAUDE.md

CLAUDE.md 是高效使用 Claude Code 时最重要的一个文件。没有它,Claude 就只能从文件内容推断您的技术栈,做出合理的猜测。有了它,Claude 从第一条提示开始就能严格遵循您的约定。这一差别至关重要,因为基于推断的行为会漂移：Claude 可能在 ESM 项目中使用 CommonJS、选错测试运行器,或忽视您的数据库迁移流程。CLAUDE.md 正是消除这种漂移的手段。

在项目根目录创建该文件：

touch CLAUDE.md

下面是一个面向 Python 项目的实用起始模板：

# My App

## Project Context
FastAPI backend with HTMX frontend. PostgreSQL database.

## Stack
- Backend: Python 3.11, FastAPI, SQLAlchemy 2.0 (async)
- Frontend: HTMX + Alpine.js, Jinja2 templates
- Database: PostgreSQL 16, Alembic migrations
- Testing: pytest with pytest-asyncio

## Code Standards
- Type hints on all function signatures
- Pydantic v2 models for request/response validation
- Async database operations only (no sync SQLAlchemy)

## Commands
- `source venv/bin/activate` before any Python command
- `uvicorn app.main:app --reload` starts the dev server
- `python -m pytest -v` runs the test suite
- `alembic upgrade head` applies database migrations

对于 JavaScript/TypeScript 项目,结构类似：

# My App

## Stack
- Backend: Node.js 20, Express 4, TypeScript
- Frontend: React 18, Vite
- Database: PostgreSQL 16, Prisma ORM
- Testing: Vitest for unit, Playwright for e2e

## Code Standards
- ESM imports only (no require())
- All API endpoints need input validation with Zod
- Tests required for new endpoints before merging

## Commands
- `npm run dev` starts the dev server on port 3000
- `npm test` runs the test suite
- `npx prisma migrate dev` runs database migrations

CLAUDE.md 中最有价值的章节,是那些能够避免重复犯错的章节。如果 Claude 总是使用 require() 而不是 import,就在 Code Standards 中加入 “ESM imports only”。如果您的测试命令需要先激活虚拟环境,就把这一步骤记录下来。Claude 在每次会话开始时都会读取 CLAUDE.md,因此其中每一行都会成为一条持久化的指令,在数百次交互中不断发挥作用。我在 AGENTS.md Patterns 中探讨了让 CLAUDE.md 文件真正奏效的模式,也在 context is architecture 中探讨了上下文即架构这一更宏观的原则。AGENTS.md 开放规范⁹ 针对其他 Agent 化工具采用了类似模式,但 CLAUDE.md 支持 skill 和 rule 目录等更丰富的能力。

层级顺序很重要。 您可以将 CLAUDE.md 放在三处位置,Claude 会按从通用到具体的顺序合并它们：

~/.claude/CLAUDE.md：适用于所有项目的全局指令（您个人的编码偏好）
./CLAUDE.md：项目级指令（提交到仓库,与团队共享）
./src/CLAUDE.md：目录级指令（仅作用于 monorepo 中的某个模块或子系统）

项目级 CLAUDE.md 是您应提交到版本控制的那一份。使用 Claude Code 的团队成员会自动继承您的约定。

权限基础

Claude Code 采用三层权限模型⁴,决定 Agent 的自主程度。您选择的层级直接控制一项根本性权衡：自主程度越高,会话越快,但对改动的可见性就越低。

Ask 模式（默认）要求在每次文件写入、命令执行或破坏性操作前都取得批准。您可以清楚看到 Claude 打算做什么,并逐步批准或拒绝。建议从这里起步,因为权限提示会让您逐渐熟悉 Claude Code 的工作方式。几次会话之后,您自然会形成直觉,知道哪些操作可以预先批准、哪些操作每次都值得仔细审视。

白名单权限让您预先批准特定工具和模式,这样 Claude 就不必每次都询问。可以在项目的 .claude/settings.json 中进行配置：

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(python -m pytest*)",
      "Bash(alembic upgrade head)"
    ]
  }
}

上述配置允许 Claude 读取文件、在代码库中搜索,以及运行您的测试和迁移命令,无需再次确认。但在写入文件或运行任何其他 bash 命令前,它仍会主动询问。请注意这一规律：读操作和已知安全的命令进入白名单,写操作则保留在 Ask 模式下,这样您可以在改动落盘之前逐一审阅 Claude 的写入内容。

危险跳过权限（--dangerously-skip-permissions）会禁用所有确认提示。该标志仅适用于 CI/CD 流水线和无人值守的自动化流程。绝不要在您在乎的代码库上以交互方式使用它。

正是这套权限系统让 Claude Code 可以安全地用于真实项目。推进节奏是经过深思熟虑的：先在 Ask 模式下建立理解,再把那些重复出现的操作加入白名单,而写操作始终受控,这样改动落盘前您总能审查一遍。

您的第一个钩子

钩子是在 Claude Code 生命周期的特定阶段执行的 shell 命令⁵。我撰写过一份完整的钩子教程,从零开始构建五个生产级钩子,另一篇关于自定义 skill 构建的文章则介绍了更高一层的自动化。钩子所解决的,是基于 LLM 的工具的根本问题：模型大多数时候会遵守您的格式规则,但 “大多数时候” 意味着每十次文件编辑就可能出现一次风格不一致。模型提供的是概率性保证,钩子提供的则是确定性保证。格式化钩子会在每次文件写入后都运行您的格式化工具,无一例外,不论模型做了什么决定。下面是一个实用的首个钩子：在 Claude 编辑文件后自动对其进行格式化。

在项目中创建或编辑 .claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

PostToolUse 钩子⁵ 会在每次 Edit 或 Write 工具调用之后触发。Claude Code 会将 $FILE_PATH 设置为被修改文件的路径,Prettier 就地完成格式化,而 || true 则保证即使 Prettier 未安装或文件类型不受支持,非零退出码也不会阻塞 Claude⁵。

其他值得推荐的入门钩子：

Bash 上的 PreToolUse：阻止 rm -rf / 或 git push --force 等危险命令
SessionStart：将当前日期、活跃的 git 分支或环境变量注入上下文（SessionStart 钩子的 stdout 会进入 Claude 的上下文）
Stop：在 Claude 完成任务时自动运行您的测试套件

钩子会把 Claude Code 从一个对话式工具,转变为一个受治理的开发环境。哪怕只是一两个精心挑选的钩子,也能消除整类错误。

遇到问题时

使用 Claude Code 的头一周,有三种情况反复出现。提前了解它们,可以省下大量调试时间。

Claude 忽视您的 CLAUDE.md 指令。 最常见的原因是：Claude 已经读过该文件并缓存了理解,而您是之后才做的编辑。运行 /clear 重置上下文,或开启新会话。Claude 只在会话开始时读取 CLAUDE.md,而不是在每条提示时重新读取。如果在新会话中 Claude 仍然不理会相关指令,请检查是否有更高优先级的 CLAUDE.md（例如用户级 ~/.claude/CLAUDE.md）与您的项目级文件冲突。

Claude 做出了您未批准的改动。 如果您把某个模式列入白名单时过于宽松（例如使用 Bash(*) 而非 Bash(python -m pytest*)）,Claude 就可能不经询问执行命令。请收紧白名单模式。最安全的做法是：只将读操作和具体命名的命令加入白名单。若 Claude 已经做出不想要的改动,可用 git diff 查看具体变更,再用 git checkout -- <file> 进行回退。

长会话中上下文窗口填满。 当 200K 上下文窗口填满时,Claude Code 会压缩较早的消息,但压缩过程可能丢弃对话早期的一些关键细节。对于超过 30 分钟的会话,建议定期提交工作成果,并通过 /clear 开启新会话。全新的上下文会重新读取 CLAUDE.md,从干净状态开始。我习惯在每完成一个子任务后就提交,这样既有回滚点,也天然形成了会话的边界。

Claude 改了错误的文件或做出多余的改动。 当 Claude 开始 “改进” 您并未要求它修改的代码时,问题通常出在提示词含糊。与其说 “清理一下 auth 模块”,不如说 “在 app/auth/handlers.py 中,将 verify_user 重命名为 verify_user_credentials,并更新所有调用方”。越具体,越能减少意外的副作用。如果 Claude 已经做出不想要的改动,git diff 能展示具体变更,git checkout -- <file> 可以逐个回退文件而不丢失其他工作。

后续步骤

上文已覆盖核心要点：安装、首次会话、项目配置、权限和一个起步钩子。若想将 Claude Code 与其他 Agent 化工具进行对比,请参阅 Claude Code vs Codex。如需完整参考,覆盖全部五大核心系统（CLAUDE.md 层级、完整权限模型、钩子架构、自定义斜杠命令,以及多 Agent 工作流）,请阅读The Complete Guide to Claude Code。

该指南涵盖上下文窗口管理、子 Agent 委派、skill 自动激活,以及数月每日使用 Claude Code 后才会沉淀下来的模式。如果您觉得本快速上手有帮助,那份完整指南便是顺理成章的下一步。若需对每个命令、参数和快捷键进行快速查阅,请参阅 Claude Code Cheat Sheet。

参考资料

FAQ

安装 Claude Code 需要哪些条件？

您需要 Node.js 18 或更高版本（Claude Code 以 npm 包形式发布）、一个具有 API 访问权限的 Anthropic 账户或 Max 订阅,以及任意终端模拟器。Claude Code 可在 macOS、Linux 和 Windows（通过 WSL 或原生运行）上使用。除 Node.js 之外,不需要任何额外依赖、Docker 容器或语言运行时。安装命令为 npm install -g @anthropic-ai/claude-code。

什么是 CLAUDE.md？我为什么需要它？

CLAUDE.md 是位于项目根目录的 markdown 文件,用于告诉 Claude Code 您的技术栈、编码约定和常用命令。没有它,Claude 就只能从文件内容推断您的环境,作出合理的猜测——但这些猜测会在不同会话之间漂移。有了 CLAUDE.md,Claude 从第一条提示开始,每一次会话都能严格遵循您的约定。它支持三级层级：用户级（~/.claude/CLAUDE.md）、项目级（./CLAUDE.md）和目录级（./src/CLAUDE.md）,按从通用到具体的顺序合并。

Claude Code 的费用是多少？

Claude Code 支持两种计费模式。API 按量付费按 token 以 Anthropic 标准 API 价格计费⁶。典型的 30 至 60 分钟会话费用为 0.50 到 3.00 美元,具体取决于代码库规模和生成量。另一种方式是 Anthropic 的 Max 计划⁶(截至 2026 年 3 月,个人版每月 100 美元,团队版每月 200 美元),包含更高速率限额下的 Claude Code 使用。您可以在 console.anthropic.com 监控 API 使用情况。

可以配合 VS Code 使用 Claude Code 吗？

可以。Claude Code 可在任意终端中运行,包括 VS Code 的集成终端。在 VS Code 中打开终端面板,进入项目目录,然后像在独立终端中一样运行 claude。Claude Code 直接读写磁盘上的文件,因此改动会立即体现在 VS Code 的编辑器标签页中。无需额外的 VS Code 扩展。有些开发者会在编辑器旁单独保留一个用于 Claude Code 的终端分屏,这样便于实时查看变更。

在生产代码库上使用 Claude Code 安全吗？

Claude Code 的 Ask 模式会在每次文件写入和命令执行前要求明确批准。未经您确认,磁盘上的任何内容都不会改变。权限系统配合可用于阻止强制推送或破坏性 shell 命令的钩子,使 Claude Code 足以胜任生产级工作。我每天都在服务真实用户的项目上使用 Claude Code。关键在于:从 Ask 模式起步,在批准前先理解每次工具调用的含义,并只对信任的操作逐步放宽白名单。版本控制是最后的安全网:在开启任何重要的 Claude Code 会话之前先提交,这样您随时可以回滚。

新手最常犯的错误是什么？

在提示词里塞给 Claude 过多上下文,而没有把它放进 CLAUDE.md。新手往往把完整的编码规范粘贴到每条提示里,这样既浪费上下文窗口空间,又会让不同会话之间的结果不一致。正确的做法是把反复出现的指令一次性迁移到 CLAUDE.md,提示词只用于处理会话特定的请求。第二常见的错误是:将 Bash(*) 而非具体命令加入白名单。通配符形式的 Bash 白名单,会让 Claude 无需询问就执行任意 shell 命令,这就违背了权限系统本来的意义。

Anthropic, “ServiceNow Customer Story.” anthropic.com/customers/servicenow ↩
Anthropic, “Allianz Customer Story.” anthropic.com/customers/allianz ↩
Anthropic, “Claude Code Overview.” docs.anthropic.com/en/docs/claude-code/overview. Source: github.com/anthropics/claude-code ↩
Anthropic, “Claude Code Permissions.” docs.anthropic.com/en/docs/claude-code/security ↩↩
Anthropic, “Claude Code Hooks.” docs.anthropic.com/en/docs/claude-code/hooks ↩↩↩
Anthropic, “Pricing.” platform.claude.com/docs/en/about-claude/pricing ↩↩↩
npm Documentation, “Resolving EACCES permissions errors when installing packages globally.” docs.npmjs.com/resolving-eacces-permissions-errors ↩
Anthropic, “Effective usage of Claude Code.” docs.anthropic.com/en/docs/claude-code/best-practices ↩
Linux Foundation Agentic AI Foundation, “AGENTS.md Specification.” github.com/anthropics/agent-instructions ↩