Claude Code 单路径配置：安装 → 认证 → 项目指引 → 权限 → hooks → MCP。日常使用前需达到的状态。

Claude Code 是 Anthropic 官方的代理式 CLI。配置到位后非常强大，但如果安装时跳过了权限模型、CLAUDE.md、Hooks 和 MCP，日后每天都要重复相同的手动工作。本指南按顺序讲解 macOS / Linux / Windows（Git Bash 或 WSL2） 的安装 → 认证 → 项目指引 → 权限 → Hooks → MCP。

我认为初次配置的质量决定了后续所有会话的体验上限。以前我们把 Claude Code 当作普通命令行工具；如今结合 CLAUDE.md 和 Hooks，它更像是拥有项目记忆的协作者，因为配置层正是那个记忆的载体。

面向熟悉 git/Node 的开发者 — 无论是刚接触 Claude Code，还是一直在没有整理配置的情况下使用。

TL;DR

Node.js 20+ → npm install -g @anthropic-ai/claude-code → claude → 浏览器认证
在项目根目录放置 CLAUDE.md（1–2 屏）+ .claude/settings.json（权限 / 环境 / Hooks）
入门三条 slash command：/help、/config、/init
某命令持续被拒绝时，在 permissions.allow 中添加对应模式
按需添加 MCP server — 优先使用本地 stdio，密钥放在环境变量中

前提条件

Node.js 20+ — node -v。版本过旧？通过 mise 或 nvm 升级
Anthropic 账户 — console.anthropic.com 或 Claude.ai Pro/Max 订阅
Git — CLI 用于检查项目。macOS 参见 /mac/initial-setup
操作系统：macOS / Linux / Windows（推荐 Git Bash 或 WSL2；原生 PowerShell 也可以，但基于 sh 的 hook 兼容性降低）

1. 安装 — 5 分钟

1.1 npm 全局安装

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

权限错误？ 不要用 sudo，改为将 npm prefix 移至主目录：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

1.2 首次运行 + 认证

进入你想工作的项目目录并运行：

cd ~/projects/my-repo
claude

首次运行时会弹出浏览器标签页进行 Anthropic 认证。登录后 CLI 启动对话。token 存储在操作系统钥匙链中，无需每次重新认证。

1.3 验证

claude --version
# 打印类似 0.x.x 的版本号

2. 先掌握三个斜杠命令

在 CLI 中，以 / 开头的命令即 slash command。入门掌握三条已足够：

命令	用途
`/help`	所有可用命令 + 快捷键
`/config`	模型 · 主题 · 默认权限模式（交互式 UI）
`/init`	分析当前目录并生成 `CLAUDE.md` 草稿

每个新项目运行一次 /init — 它会扫描目录结构、语言和构建工具，生成一份合理的起始草稿供你完善。

3. `CLAUDE.md` — 项目指引（最重要）

CLAUDE.md 是放在项目根目录的 Markdown 文件，每次会话开始时自动加载。其中写明的规则在整个会话中具有最高优先级。

优质的 `CLAUDE.md`

# 项目 — Claude 指引
 
## 角色
（可选）角色提示，如「扮演一位严格审查 diff 的高级工程师」。
 
## 技术栈
- 框架：Next.js 16（App Router）
- 语言：TypeScript strict
- 数据库：Supabase
 
## 命令
- 开发服务器：`pnpm dev`
- 构建：`pnpm build`
- 测试：`pnpm test`
 
## 约定
- 不使用 `any`（TS strict）
- 文件名：kebab-case（路由），camelCase（工具函数）
- 永远不要硬编码密钥
 
## Git
- 提交：`[Project] {type}: {desc}` — feat/fix/refactor/...
- 直接推送 main：OK（个人）/ 需要 PR（团队）
 
## 工作原则
1. 变更涉及 5+ 文件 / 新模块 / 架构时，先制定计划
2. 代码变更后，lint+构建+测试通过前不声明「完成」
3. 密钥 · 数据库迁移 · 外部推送需要明确批准

建议

保持简短 — 1–2 屏即可。更详细的内容放入 memory/rules/{topic}.md，并在 CLAUDE.md 中链接引用。
使用项目专属文件；跨项目通用指引放在 ~/.claude/CLAUDE.md。
将 CLAUDE.md 提交到 git，便于团队成员和其他机器共享。

4. `.claude/settings.json` — 权限、环境、hooks

控制运行时行为的核心配置文件，最常编辑的部分是 permissions。

4.1 骨架

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(pnpm test:*)",
      "Read(/Users/me/projects/**)"
    ],
    "deny": [
      "Bash(rm -rf /:*)",
      "Bash(sudo *)"
    ]
  },
  "env": {
    "EDITOR": "code --wait"
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "echo '[Session start] $(date)'" }
        ]
      }
    ]
  }
}

4.2 权限规则（`permissions.allow` / `deny`）

某个 Bash(...) 持续被拒绝时，将其作为模式加入 allow
模式为前缀匹配 — Bash(pnpm:*) 允许任何以 pnpm 开头的命令
将危险模式（rm -rf、sudo、curl … | bash）固定到 deny 中以保障安全

💡 批量添加常用只读命令，可在 CLI 内运行内置 Skill /fewer-permission-prompts — 它会扫描会话记录并推荐 allow-list。

4.3 可下载的模板

与上述相同配置的现成文件（使用前请验证）：

settings.example.json

# 1. 下载
curl -fsSL https://devalice.jaceclub.com/assets/ai-agents/claude-code/settings.example.json -o .claude/settings.example.json
 
# 2. 验证 SHA-256
shasum -a 256 .claude/settings.example.json
# 期望值：22898a20ade2b3497f8299a8ca6139112c476e0a0a4075e1a05123a02c8266ac
 
# 3. 检查后复制到位
less .claude/settings.example.json
cp .claude/settings.example.json .claude/settings.json

不要将密钥（API key 等）粘贴到 settings.json。请从操作系统环境变量或已加入 .gitignore 的 .env 文件中读取。

4.4 全局 vs 项目 vs 本地

文件	位置	用途
`~/.claude/settings.json`	主目录	跨项目默认设置（如始终允许 `git status`）
`<project>/.claude/settings.json`	项目根目录（git 追踪）	团队共享的权限/hooks
`<project>/.claude/settings.local.json`	项目根目录（.gitignore）	每台机器的覆盖设置（个人 token、路径）

5. Hooks — 自动化触发器

Hooks 在特定事件发生时运行 shell 命令。主要事件：

事件	时机
`SessionStart`	会话开始
`PreToolUse`	工具调用前（可验证 / 阻止）
`PostToolUse`	工具调用后
`Stop`	Claude 回复结束
`UserPromptSubmit`	用户提交 prompt 后

示例 1：会话开始时打印环境信息

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "printf '[Session start] %s\\nBranch: %s\\n' \"$(date '+%F %T')\" \"$(git branch --show-current 2>/dev/null || echo none)\""
          }
        ]
      }
    ]
  }
}

示例 2：阻止写入密钥文件

PreToolUse 可通过退出码阻止工具调用。（1 = 警告，2 = 阻止。）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -qE '\\.env$|secrets/|private_key' && { echo 'BLOCKED: secret file'; exit 2; } || exit 0"
          }
        ]
      }
    ]
  }
}

规范详情：/help → 文档链接，或参见 Claude Code Hooks 官方文档。调试时，先用单行 echo Hook 确认是否触发。

6. MCP 服务器 — 仅在需要时添加

MCP（Model Context Protocol）是向 Claude Code 暴露外部工具的标准协议。已有 GitHub、Slack、Linear、Figma 等集成，也可以自行编写 MCP server。

注册

在 .claude/settings.json 的 mcpServers 中添加：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

${GITHUB_TOKEN} 会从 shell 环境变量中展开 — 在 .zshrc 或 .envrc（direnv）中 export GITHUB_TOKEN=...，避免将密钥写入 settings.json。

安全

优先使用本地 stdio 服务器（command: "npx" 或本地二进制）— 攻击面远小于网络 RPC 服务器
只用已审核的包 — @modelcontextprotocol/*、@upstash/* 等。未知包请先核查
密钥通过环境变量传入 — settings.json 往往会提交到 git；不要在其中内联写 token

7. IDE 集成 — VS Code · Cursor

Claude Code 是 CLI，但与 IDE 配合良好：

VS Code / Cursor 集成终端 — 直接运行 claude，在 IDE 中编辑文件，在终端对话。最简单的方式。
VS Code 扩展 — 在扩展市场搜索「Claude Code」，在侧边面板打开。
JetBrains（IntelliJ/PyCharm/WebStorm 等）— 可在 JetBrains Marketplace 找到插件。

如果已在使用 AI 原生编辑器（Cursor、Windsurf），可将 Claude Code 留给「多文件 / shell / git」类任务，编辑器内置 AI 负责内联编码。

8. 验证 — 配置是否完成？

# 1. 安装
claude --version
 
# 2. 项目配置文件
ls -la CLAUDE.md .claude/settings.json
 
# 3. 全局配置（可选）
ls -la ~/.claude/settings.json 2>/dev/null && echo "global OK" || echo "no global"
 
# 4. 认证 — 运行 `claude` 查看欢迎横幅
#    > claude
#    │ Welcome to Claude Code!

四项全绿则配置完成。第一个真实任务：在项目目录中运行 claude，然后问类似「用一段话描述这个 repo 的结构」的问题。

9. 故障排查

`command not found: claude`

npm 全局 bin 不在 PATH 中。npm config get prefix 找到它 → 将 <prefix>/bin 添加到 ~/.zshrc / ~/.bashrc
Windows Git Bash：npm config get prefix 应为 C:\Users\<you>\AppData\Roaming\npm，该路径必须在 PATH 中

首次运行时浏览器认证未打开

无头环境（SSH、WSL2）：将 CLI 中的 URL 手动复制到浏览器
认证仍失败？删除 ~/.claude/ 下的 token 缓存后重试

每次 Bash 命令都出现「Permission?」提示

在 .claude/settings.json 的 permissions.allow 中添加常用只读命令
或通过 /config → 将权限模式设为 acceptEdits（自动批准文件编辑，shell 命令仍需询问）

Hooks 不触发

# 1. JSON 是否有效？
cat .claude/settings.json | jq .
 
# 2. 简化命令后检查
# command: "echo HOOK_FIRED >> /tmp/claude-hook.log"

JSON 损坏会静默禁用整个 Hooks 配置块。

MCP server 未显示

在 CLI 中输入 /mcp — 查看已注册的 server 及其状态
确认 command 在 PATH 中（which npx）
日志位于 ~/.claude/logs/ 或 stderr

10. 下一步

本指南结束于「Claude Code 可日常使用」的状态。后续：

工作流模式 — 多代理、计划模式、Subagents（待更新）
与 Cursor 的对比 — /ai-agents/cursor-setup
进阶 Hooks — SessionStart 内存同步、PreToolUse 安全门禁
编写自定义 MCP server — 暴露内部工具（待更新）

参考资料

更新日志

2026-05-12 — 初始英文翻译（devAlice M2 i18n 种子）

Claude Code 配置 — 在第一个小时内完成安装、权限、hooks 和 MCP