← 返回首页
ClaudeCode Agent

Claude Code 的配置与权限

Claude Code

安装

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

设置

设置文件

settings.json 文件是通过分层设置配置 Claude Code 的官方机制：

  • 用户设置 在 ~/.claude/settings.json 中定义，适用于所有项目。
  • 项目设置 保存在您的项目目录中：
    • .claude/settings.json 用于检入源代码控制并与团队共享的设置
    • .claude/settings.local.json 用于不检入的设置，对个人偏好和实验很有用。Claude Code 会在创建时配置 git 忽略 .claude/settings.local.json。
  • 对于 Claude Code 的企业部署，还支持企业托管策略设置。这些设置优先于用户和项目设置。系统管理员可以将策略部署到：
    • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
    • Linux 和 WSL: /etc/claude-code/managed-settings.json
    • Windows: C:\ProgramData\ClaudeCode\managed-settings.json

示例 settings.json

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

可用设置

settings.json 支持多个选项：

键描述示例
apiKeyHelper自定义脚本，在 /bin/sh 中执行，生成认证值。此值将作为 X-Api-Key 和 Authorization: Bearer 标头发送给模型请求/bin/generate_temp_api_key.sh
cleanupPeriodDays基于最后活动日期本地保留聊天记录的时间（默认：30天）20
env将应用于每个会话的环境变量{"FOO": "bar"}
includeCoAuthoredBy是否在 git 提交和拉取请求中包含 co-authored-by Claude 署名（默认：true）false
permissions权限结构见下表。👇
hooks配置在工具执行前后运行的自定义命令。参见钩子文档{"PreToolUse": {"Bash": "echo 'Running command...'"}}
disableAllHooks禁用所有钩子true
model覆盖 Claude Code 使用的默认模型"claude-3-5-sonnet-20241022"
statusLine配置自定义状态行以显示上下文。参见statusLine 文档{"type": "command", "command": "~/.claude/statusline.sh"}
outputStyle配置输出样式以调整系统提示。参见输出样式文档"Explanatory"
forceLoginMethod使用 claudeai 限制登录到 Claude.ai 账户，console 限制登录到 Anthropic Console（API 使用计费）账户claudeai
forceLoginOrgUUID指定组织的 UUID 以在登录期间自动选择它，绕过组织选择步骤。需要设置 forceLoginMethod"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
enableAllProjectMcpServers自动批准项目 .mcp.json 文件中定义的所有 MCP 服务器true
enabledMcpjsonServers从 .mcp.json 文件中批准的特定 MCP 服务器列表["memory", "github"]
disabledMcpjsonServers从 .mcp.json 文件中拒绝的特定 MCP 服务器列表["filesystem"]

权限设置

键描述示例
allow允许工具使用的权限规则数组。注意： Bash 规则使用前缀匹配，不是正则表达式[ "Bash(git diff:*)" ]
ask在工具使用时要求确认的权限规则数组。[ "Bash(git push:*)" ]
deny拒绝工具使用的权限规则数组。使用此选项也可以排除敏感文件不被 Claude Code 访问。注意： Bash 模式是前缀匹配，可以被绕过（参见Bash 权限限制）[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]
additionalDirectoriesClaude 可以访问的额外工作目录
defaultMode打开 Claude Code 时的默认权限模式"acceptEdits"
disableBypassPermissionsMode设置为 "disable" 以防止激活 bypassPermissions 模式。参见托管策略设置"disable"

设置优先级

设置按优先级顺序应用（从高到低）：

  1. 企业托管策略（managed-settings.json）

    • 由 IT/DevOps 部署
    • 无法被覆盖

  2. 命令行参数

    • 特定会话的临时覆盖

  3. 本地项目设置（.claude/settings.local.json）

    • 个人项目特定设置

  4. 共享项目设置（.claude/settings.json）

    • 源代码控制中的团队共享项目设置

  5. 用户设置（~/.claude/settings.json）

    • 个人全局设置

此层次结构确保企业安全策略始终得到执行，同时仍允许团队和个人自定义其体验。

配置系统的关键点

  • 内存文件（CLAUDE.md）：包含 Claude 在启动时加载的指令和上下文
  • 设置文件（JSON）：配置权限、环境变量和工具行为
  • 斜杠命令：可以在会话期间使用 /command-name 调用的自定义命令
  • MCP 服务器：使用额外的工具和集成扩展 Claude Code
  • 优先级：更高级别的配置（企业）覆盖较低级别的配置（用户/项目）
  • 继承：设置被合并，更具体的设置添加到或覆盖更广泛的设置

排除敏感文件

要防止 Claude Code 访问包含敏感信息的文件（例如，API 密钥、秘密、环境文件），请在您的 .claude/settings.json 文件中使用 permissions.deny 设置：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

匹配这些模式的文件将对 Claude Code 完全不可见，防止任何意外暴露敏感数据。

环境变量

Claude Code 支持以下环境变量来控制其行为：

这作为自动为每个会话设置环境变量的方式很有用，或者为您的整个团队或组织推出一组环境变量。

变量目的
ANTHROPIC_API_KEY作为 X-Api-Key 标头发送的 API 密钥，通常用于 Claude SDK（对于交互式使用，运行 /login）
ANTHROPIC_AUTH_TOKENAuthorization 标头的自定义值（您在此处设置的值将以 Bearer 为前缀）
ANTHROPIC_CUSTOM_HEADERS您想要添加到请求的自定义标头（以 Name: Value 格式）
ANTHROPIC_MODEL要使用的模型设置名称
BASH_DEFAULT_TIMEOUT_MS长时间运行的 bash 命令的默认超时
BASH_MAX_OUTPUT_LENGTHbash 输出在中间截断之前的最大字符数
BASH_MAX_TIMEOUT_MS模型可以为长时间运行的 bash 命令设置的最大超时
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR在每个 Bash 命令后返回到原始工作目录
CLAUDE_CODE_API_KEY_HELPER_TTL_MS凭证应刷新的间隔（毫秒）（使用 apiKeyHelper 时）
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL跳过 IDE 扩展的自动安装
CLAUDE_CODE_MAX_OUTPUT_TOKENS为大多数请求设置最大输出令牌数
CLAUDE_CODE_SUBAGENT_MODEL参见模型配置
DISABLE_TELEMETRY设置为 1 以选择退出 Statsig 遥测（注意 Statsig 事件不包括用户数据，如代码、文件路径或 bash 命令）
MAX_MCP_OUTPUT_TOKENSMCP 工具响应中允许的最大令牌数。当输出超过 10,000 个令牌时，Claude Code 显示警告（默认：25000）
MAX_THINKING_TOKENS强制模型预算的思考
MCP_TIMEOUTMCP 服务器启动的超时（毫秒）
MCP_TOOL_TIMEOUTMCP 工具执行的超时（毫秒）
USE_BUILTIN_RIPGREP设置为 0 以使用系统安装的 rg 而不是 Claude Code 包含的 rg

子代理配置

Claude Code 支持可以在用户和项目级别配置的自定义 AI 子代理。这些子代理存储为带有 YAML 前言的 Markdown 文件：

  • 用户子代理：~/.claude/agents/ - 在您的所有项目中可用
  • 项目子代理：.claude/agents/ - 特定于您的项目，可以与您的团队共享

子代理文件定义具有自定义提示和工具权限的专门 AI 助手。在子代理文档中了解更多关于创建和使用子代理的信息。

可用的工具

Claude Code 可以访问一组强大的工具，帮助它理解和修改您的代码库：

工具描述需要权限
Bash在您的环境中执行 shell 命令是
LS列出当前工作目录中的文件否
Glob基于模式匹配查找文件否
Grep在文件内容中搜索模式否
Read读取文件内容否
Write创建或覆盖文件是
Edit对特定文件进行有针对性的编辑是
MultiEdit在单个文件上原子性地执行多个编辑是
NotebookEdit修改 Jupyter notebook 单元格是
NotebookRead读取和显示 Jupyter notebook 内容否
Task运行子代理来处理复杂的多步骤任务否
TodoWrite创建和管理结构化任务列表否
WebFetch从指定 URL 获取内容是
WebSearch执行带有域过滤的网络搜索是

访问控制和权限

支持细粒度权限，以便您能够精确指定代理被允许做什么（例如运行测试、运行linter）以及不被允许做什么（例如更新云基础设施）。这些权限设置可以检入版本控制并分发给您组织中的所有开发者，也可以由个别开发者自定义。

权限系统

Claude Code使用分层权限系统来平衡功能和安全性：

工具类型示例需要批准”是的，不要再问”行为
只读文件读取、LS、Grep否不适用
Bash命令Shell执行是每个项目目录和命令永久生效
文件修改编辑/写入文件是直到会话结束

配置权限

您可以使用/permissions查看和管理Claude Code的工具权限。此UI列出所有权限规则和它们来源的settings.json文件。

  • 允许规则将允许Claude Code使用指定工具而无需进一步的手动批准。
  • 询问规则将在Claude Code尝试使用指定工具时询问用户确认。询问规则优先于允许规则。
  • 拒绝规则将阻止Claude Code使用指定工具。拒绝规则优先于允许和询问规则。
  • 附加目录将Claude的文件访问扩展到初始工作目录之外的目录。
  • 默认模式控制Claude在遇到新请求时的权限行为。

权限规则使用格式：工具或工具(可选说明符)

仅为工具名称的规则匹配该工具的任何使用。例如，将Bash添加到允许规则列表中将允许Claude Code使用Bash工具而无需用户批准。

权限模式

Claude Code支持几种权限模式，可以在设置文件中设置为defaultMode：

模式描述
default标准行为 - 在首次使用每个工具时提示权限
acceptEdits自动接受会话的文件编辑权限
plan计划模式 - Claude可以分析但不能修改文件或执行命令
bypassPermissions跳过所有权限提示（需要安全环境 - 请参阅下面的警告）

工作目录

默认情况下，Claude可以访问启动它的目录中的文件。您可以扩展此访问权限：

  • 启动期间：使用--add-dir <path> CLI参数
  • 会话期间：使用/add-dir斜杠命令
  • 持久配置：添加到设置文件中的additionalDirectories

附加目录中的文件遵循与原始工作目录相同的权限规则 - 它们变得可读而无需提示，文件编辑权限遵循当前权限模式。

工具特定权限规则

某些工具支持更细粒度的权限控制：

Bash

  • Bash(npm run build) 匹配确切的Bash命令npm run build
  • Bash(npm run test:*) 匹配以npm run test开头的Bash命令
  • Bash(curl http://site.com/:*) 匹配以确切的curl http://site.com/开头的curl命令

Claude Code了解shell操作符（如&&），因此像Bash(safe-cmd:*)这样的前缀匹配规则不会给它运行命令safe-cmd && other-cmd的权限

Bash权限模式的重要限制：

  1. 此工具使用前缀匹配，而不是正则表达式或glob模式
  2. 通配符:*只能在模式末尾使用以匹配任何延续
  3. 像Bash(curl http://github.com/:*)这样的模式可以通过多种方式绕过：
    • URL前的选项：curl -X GET http://github.com/...不会匹配
    • 不同协议：curl https://github.com/...不会匹配
    • 重定向：curl -L http://bit.ly/xyz（重定向到github）
    • 变量：URL=http://github.com && curl $URL不会匹配
    • 额外空格：curl http://github.com不会匹配

为了更可靠的URL过滤，请考虑：

  • 使用带有WebFetch(domain:github.com)权限的WebFetch工具
  • 通过CLAUDE.md指示Claude Code您允许的curl模式
  • 使用钩子进行自定义权限验证

读取和编辑

Edit规则适用于所有编辑文件的内置工具。Claude将尽力将Read规则应用于所有读取文件的内置工具，如Grep、Glob和LS。

读取和编辑规则都遵循gitignore规范，具有四种不同的模式类型：

模式含义示例匹配
//path从文件系统根目录的绝对路径Read(//Users/alice/secrets/**)/Users/alice/secrets/**
~/path从主目录的路径Read(~/Documents/*.pdf)/Users/alice/Documents/*.pdf
/path相对于设置文件的路径Edit(/src/**/*.ts)<设置文件路径>/src/**/*.ts
path或./path相对于当前目录的路径Read(*.env)<cwd>/*.env

像/Users/alice/file这样的模式不是绝对路径 - 它是相对于您的设置文件的！使用//Users/alice/file表示绝对路径。

  • Edit(/docs/**) - 在<项目>/docs/中编辑（不是/docs/！）
  • Read(~/.zshrc) - 读取您主目录的.zshrc
  • Edit(//tmp/scratch.txt) - 编辑绝对路径/tmp/scratch.txt
  • Read(src/**) - 从<当前目录>/src/读取

WebFetch

  • WebFetch(domain:example.com) 匹配对example.com的获取请求

MCP

  • mcp__puppeteer 匹配puppeteer服务器提供的任何工具（在Claude Code中配置的名称）
  • mcp__puppeteer__puppeteer_navigate 匹配puppeteer服务器提供的puppeteer_navigate工具
  • 与其他权限类型不同，MCP权限不支持通配符（*）。

斜杠命令

在交互式会话中使用斜杠命令控制 Claude 的行为。

内置斜杠命令

命令用途
/add-dir添加额外的工作目录
/agents管理用于专门任务的自定义 AI 子代理
/bug报告错误（将对话发送给 Anthropic）
/clear清除对话历史
/compact [instructions]压缩对话，可选择性地提供重点指令
/config查看/修改配置
/cost显示令牌使用统计
/doctor检查您的 Claude Code 安装的健康状况
/help获取使用帮助
/init使用 CLAUDE.md 指南初始化项目
/login切换 Anthropic 账户
/logout从您的 Anthropic 账户注销
/mcp管理 MCP 服务器连接和 OAuth 身份验证
/memory编辑 CLAUDE.md 内存文件
/model选择或更改 AI 模型
/permissions查看或更新权限
/pr_comments查看拉取请求评论
/review请求代码审查
/status查看账户和系统状态
/terminal-setup安装 Shift+Enter 键绑定用于换行（仅限 iTerm2 和 VSCode）
/vim进入 vim 模式以在插入和命令模式之间切换

自定义斜杠命令

自定义斜杠命令允许您将经常使用的提示定义为 Markdown 文件，Claude Code 可以执行这些文件。命令按范围（项目特定或个人）组织，并通过目录结构支持命名空间。

语法

/<command-name> [arguments]

参数

参数描述
<command-name>从 Markdown 文件名派生的名称（不包含 .md 扩展名）
[arguments]传递给命令的可选参数

命令类型

项目命令

存储在您的存储库中并与您的团队共享的命令。在 /help 中列出时，这些命令在其描述后显示”(project)”。

位置: .claude/commands/

在以下示例中，我们创建 /optimize 命令：

# 创建项目命令
mkdir -p .claude/commands
echo "分析此代码的性能问题并建议优化：" > .claude/commands/optimize.md
个人命令

在您的所有项目中可用的命令。在 /help 中列出时，这些命令在其描述后显示”(user)”。

位置: ~/.claude/commands/

在以下示例中，我们创建 /security-review 命令：

# 创建个人命令
mkdir -p ~/.claude/commands
echo "审查此代码的安全漏洞：" > ~/.claude/commands/security-review.md

功能

命名空间

在子目录中组织命令。子目录用于组织并出现在命令描述中，但它们不影响命令名称本身。描述将显示命令是来自项目目录（.claude/commands）还是用户级目录（~/.claude/commands），以及子目录名称。

不支持用户级和项目级命令之间的冲突。否则，具有相同基本文件名的多个命令可以共存。

例如，位于 .claude/commands/frontend/component.md 的文件创建命令 /component，描述显示”(project:frontend)”。 同时，位于 ~/.claude/commands/component.md 的文件创建命令 /component，描述显示”(user)“。

参数

使用参数占位符将动态值传递给命令：

使用 $ARGUMENTS 的所有参数

$ARGUMENTS 占位符捕获传递给命令的所有参数：

# 命令定义
echo '按照我们的编码标准修复问题 #$ARGUMENTS' > .claude/commands/fix-issue.md

# 使用
> /fix-issue 123 high-priority
# $ARGUMENTS 变为："123 high-priority"
使用 $1、$2 等的单个参数

使用位置参数单独访问特定参数（类似于 shell 脚本）：

# 命令定义  
echo '审查 PR #$1，优先级为 $2，分配给 $3' > .claude/commands/review-pr.md

# 使用
> /review-pr 456 high alice
# $1 变为 "456"，$2 变为 "high"，$3 变为 "alice"

在以下情况下使用位置参数：

  • 需要在命令的不同部分单独访问参数
  • 为缺失的参数提供默认值
  • 构建具有特定参数角色的更结构化的命令
Bash 命令执行

使用 ! 前缀在斜杠命令运行之前执行 bash 命令。输出包含在命令上下文中。您必须包含带有 Bash 工具的 allowed-tools，但您可以选择要允许的特定 bash 命令。

例如：

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: 创建 git 提交
---

## 上下文

- 当前 git 状态：!`git status`
- 当前 git 差异（已暂存和未暂存的更改）：!`git diff HEAD`
- 当前分支：!`git branch --show-current`
- 最近的提交：!`git log --oneline -10`

## 您的任务

基于上述更改，创建单个 git 提交。
文件引用

使用 @ 前缀在命令中包含文件内容以引用文件。

例如：

# 引用特定文件

审查 @src/utils/helpers.js 中的实现

# 引用多个文件

比较 @src/old-version.js 与 @src/new-version.js
思考模式

斜杠命令可以通过包含扩展思考关键词来触发扩展思考。

前置元数据

命令文件支持前置元数据，对于指定命令的元数据很有用：

前置元数据用途默认值
allowed-tools命令可以使用的工具列表从对话中继承
argument-hint斜杠命令期望的参数。示例：argument-hint: add [tagId] | remove [tagId] | list。此提示在用户自动完成斜杠命令时显示给用户。无
description命令的简要描述使用提示的第一行
model特定的模型字符串（参见模型概述）从对话中继承

例如：

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: 创建 git 提交
model: claude-3-5-haiku-20241022
---

使用消息创建 git 提交：$ARGUMENTS

使用位置参数的示例：

---
argument-hint: [pr-number] [priority] [assignee]
description: 审查拉取请求
---

审查 PR #$1，优先级为 $2，分配给 $3。
专注于安全性、性能和代码风格。

MCP 斜杠命令

MCP 服务器可以将提示公开为斜杠命令，这些命令在 Claude Code 中变为可用。这些命令从连接的 MCP 服务器动态发现。

命令格式

MCP 命令遵循以下模式：

/mcp__<server-name>__<prompt-name> [arguments]

功能

动态发现

MCP 命令在以下情况下自动可用：

  • MCP 服务器已连接并处于活动状态
  • 服务器通过 MCP 协议公开提示
  • 在连接期间成功检索提示
参数

MCP 提示可以接受服务器定义的参数：

# 不带参数
> /mcp__github__list_prs

# 带参数
> /mcp__github__pr_review 456
> /mcp__jira__create_issue "Bug title" high
命名约定
  • 服务器和提示名称被规范化
  • 空格和特殊字符变为下划线
  • 名称小写以保持一致性

管理 MCP 连接

使用 /mcp 命令来：

  • 查看所有配置的 MCP 服务器
  • 检查连接状态
  • 使用启用 OAuth 的服务器进行身份验证
  • 清除身份验证令牌
  • 查看每个服务器的可用工具和提示

MCP 权限和通配符

在为 MCP 工具配置权限时，请注意不支持通配符：

  • ✅ 正确: mcp__github（批准来自 github 服务器的所有工具）
  • ✅ 正确: mcp__github__get_issue（批准特定工具）
  • ❌ 错误: mcp__github__*（不支持通配符）

要批准来自 MCP 服务器的所有工具，只需使用服务器名称：mcp__servername。要仅批准特定工具，请单独列出每个工具。

参考资料

🤖

智能问答助手

Ollama + AI 问答

⏳ 初始化...

💡 配置和聊天记录仅保存在本地浏览器中