Claude Code 設定
透過全域和專案層級設定以及環境變數來配置 Claude Code。
Claude Code 提供各種設定來配置其行為以滿足您的需求。您可以在使用互動式 REPL 時執行 /config
命令來配置 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
- macOS:
可用設定
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...'"}} |
model | 覆蓋 Claude Code 使用的預設模型 | "claude-3-5-sonnet-20241022" |
statusLine | 配置自訂狀態列以顯示上下文。請參見statusLine 文件 | {"type": "command", "command": "~/.claude/statusline.sh"} |
forceLoginMethod | 使用 claudeai 限制登入到 Claude.ai 帳戶,console 限制登入到 Anthropic Console(API 使用計費)帳戶 | claudeai |
enableAllProjectMcpServers | 自動核准專案 .mcp.json 檔案中定義的所有 MCP 伺服器 | true |
enabledMcpjsonServers | 從 .mcp.json 檔案中核准的特定 MCP 伺服器清單 | ["memory", "github"] |
disabledMcpjsonServers | 從 .mcp.json 檔案中拒絕的特定 MCP 伺服器清單 | ["filesystem"] |
awsAuthRefresh | 修改 .aws 目錄的自訂腳本(請參見進階憑證配置) | aws sso login --profile myprofile |
awsCredentialExport | 輸出包含 AWS 憑證的 JSON 的自訂腳本(請參見進階憑證配置) | /bin/generate_aws_grant.sh |
權限設定
鍵 | 描述 | 範例 |
---|---|---|
allow | 允許工具使用的權限規則陣列 | [ "Bash(git diff:*)" ] |
ask | 在工具使用時要求確認的權限規則陣列。 | [ "Bash(git push:*)" ] |
deny | 拒絕工具使用的權限規則陣列。使用此選項也可以將敏感檔案排除在 Claude Code 存取之外。 | [ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ] |
additionalDirectories | Claude 可以存取的額外工作目錄 | [ "../docs/" ] |
defaultMode | 開啟 Claude Code 時的預設權限模式 | "acceptEdits" |
disableBypassPermissionsMode | 設定為 "disable" 以防止啟用 bypassPermissions 模式。請參見管理政策設定 | "disable" |
設定優先順序
設定按優先順序(從高到低)應用:
-
企業管理政策(
managed-settings.json
)- 由 IT/DevOps 部署
- 無法被覆蓋
-
命令列參數
- 特定會話的臨時覆蓋
-
本地專案設定(
.claude/settings.local.json
)- 個人專案特定設定
-
共享專案設定(
.claude/settings.json
)- 原始碼控制中的團隊共享專案設定
-
使用者設定(
~/.claude/settings.json
)- 個人全域設定
此階層確保企業安全政策始終得到執行,同時仍允許團隊和個人自訂其體驗。
配置系統的要點
- 記憶檔案(CLAUDE.md):包含 Claude 在啟動時載入的指令和上下文
- 設定檔案(JSON):配置權限、環境變數和工具行為
- 斜線命令:可在會話期間使用
/command-name
調用的自訂命令 - MCP 伺服器:使用額外工具和整合擴展 Claude Code
- 優先順序:較高層級的配置(企業)覆蓋較低層級的配置(使用者/專案)
- 繼承:設定會合併,更具體的設定會添加到或覆蓋更廣泛的設定
系統提示可用性
與 claude.ai 不同,我們不在此網站上發布 Claude Code 的內部系統提示。使用 CLAUDE.md 檔案或 --append-system-prompt
來為 Claude Code 的行為添加自訂指令。
排除敏感檔案
為了防止 Claude Code 存取包含敏感資訊的檔案(例如 API 金鑰、機密、環境檔案),請在您的 .claude/settings.json
檔案中使用 permissions.deny
設定:
這取代了已棄用的 ignorePatterns
配置。符合這些模式的檔案將對 Claude Code 完全不可見,防止任何意外暴露敏感資料。
子代理配置
Claude Code 支援可在使用者和專案層級配置的自訂 AI 子代理。這些子代理儲存為帶有 YAML 前言的 Markdown 檔案:
- 使用者子代理:
~/.claude/agents/
- 在您的所有專案中可用 - 專案子代理:
.claude/agents/
- 特定於您的專案,可與您的團隊共享
子代理檔案定義具有自訂提示和工具權限的專門 AI 助手。在子代理文件中了解更多關於建立和使用子代理的資訊。
環境變數
Claude Code 支援以下環境變數來控制其行為:
所有環境變數也可以在settings.json
中配置。這是為每個會話自動設定環境變數或為整個團隊或組織推出一組環境變數的有用方法。
變數 | 目的 |
---|---|
ANTHROPIC_API_KEY | 作為 X-Api-Key 標頭發送的 API 金鑰,通常用於 Claude SDK(對於互動使用,執行 /login ) |
ANTHROPIC_AUTH_TOKEN | Authorization 標頭的自訂值(您在此設定的值將以 Bearer 為前綴) |
ANTHROPIC_CUSTOM_HEADERS | 您想要添加到請求的自訂標頭(以 Name: Value 格式) |
ANTHROPIC_MODEL | 要使用的自訂模型名稱(請參見模型配置) |
ANTHROPIC_SMALL_FAST_MODEL | 背景任務的 Haiku 級模型名稱 |
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION | 使用 Bedrock 時覆蓋小型/快速模型的 AWS 區域 |
AWS_BEARER_TOKEN_BEDROCK | 用於認證的 Bedrock API 金鑰(請參見Bedrock API 金鑰) |
BASH_DEFAULT_TIMEOUT_MS | 長時間執行的 bash 命令的預設逾時 |
BASH_MAX_TIMEOUT_MS | 模型可以為長時間執行的 bash 命令設定的最大逾時 |
BASH_MAX_OUTPUT_LENGTH | 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_USE_BEDROCK | 使用Bedrock |
CLAUDE_CODE_USE_VERTEX | 使用Vertex |
CLAUDE_CODE_SKIP_BEDROCK_AUTH | 跳過 Bedrock 的 AWS 認證(例如使用 LLM 閘道時) |
CLAUDE_CODE_SKIP_VERTEX_AUTH | 跳過 Vertex 的 Google 認證(例如使用 LLM 閘道時) |
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | 等同於設定 DISABLE_AUTOUPDATER 、DISABLE_BUG_COMMAND 、DISABLE_ERROR_REPORTING 和 DISABLE_TELEMETRY |
CLAUDE_CODE_DISABLE_TERMINAL_TITLE | 設定為 1 以停用基於對話上下文的自動終端標題更新 |
DISABLE_AUTOUPDATER | 設定為 1 以停用自動更新。這優先於 autoUpdates 配置設定。 |
DISABLE_BUG_COMMAND | 設定為 1 以停用 /bug 命令 |
DISABLE_COST_WARNINGS | 設定為 1 以停用成本警告訊息 |
DISABLE_ERROR_REPORTING | 設定為 1 以選擇退出 Sentry 錯誤報告 |
DISABLE_NON_ESSENTIAL_MODEL_CALLS | 設定為 1 以停用非關鍵路徑(如風味文字)的模型呼叫 |
DISABLE_TELEMETRY | 設定為 1 以選擇退出 Statsig 遙測(請注意 Statsig 事件不包含使用者資料,如程式碼、檔案路徑或 bash 命令) |
HTTP_PROXY | 為網路連線指定 HTTP 代理伺服器 |
HTTPS_PROXY | 為網路連線指定 HTTPS 代理伺服器 |
MAX_THINKING_TOKENS | 強制模型思考預算 |
MCP_TIMEOUT | MCP 伺服器啟動的逾時(毫秒) |
MCP_TOOL_TIMEOUT | MCP 工具執行的逾時(毫秒) |
MAX_MCP_OUTPUT_TOKENS | MCP 工具回應中允許的最大權杖數(預設:25000) |
USE_BUILTIN_RIPGREP | 設定為 0 以使用系統安裝的 rg 而不是 Claude Code 包含的 rg |
VERTEX_REGION_CLAUDE_3_5_HAIKU | 使用 Vertex AI 時覆蓋 Claude 3.5 Haiku 的區域 |
VERTEX_REGION_CLAUDE_3_5_SONNET | 使用 Vertex AI 時覆蓋 Claude Sonnet 3.5 的區域 |
VERTEX_REGION_CLAUDE_3_7_SONNET | 使用 Vertex AI 時覆蓋 Claude 3.7 Sonnet 的區域 |
VERTEX_REGION_CLAUDE_4_0_OPUS | 使用 Vertex AI 時覆蓋 Claude 4.0 Opus 的區域 |
VERTEX_REGION_CLAUDE_4_0_SONNET | 使用 Vertex AI 時覆蓋 Claude 4.0 Sonnet 的區域 |
VERTEX_REGION_CLAUDE_4_1_OPUS | 使用 Vertex AI 時覆蓋 Claude 4.1 Opus 的區域 |
配置選項
要管理您的配置,請使用以下命令:
- 列出設定:
claude config list
- 查看設定:
claude config get <key>
- 變更設定:
claude config set <key> <value>
- 推送到設定(對於清單):
claude config add <key> <value>
- 從設定中移除(對於清單):
claude config remove <key> <value>
預設情況下,config
會變更您的專案配置。要管理您的全域配置,請使用 --global
(或 -g
)標誌。
全域配置
要設定全域配置,請使用 claude config set -g <key> <value>
:
鍵 | 描述 | 範例 |
---|---|---|
autoUpdates | 是否啟用自動更新(預設:true )。啟用時,Claude Code 會在背景自動下載和安裝更新。重新啟動 Claude Code 時會應用更新。 | false |
preferredNotifChannel | 您想要接收通知的位置(預設:iterm2 ) | iterm2 、iterm2_with_bell 、terminal_bell 或 notifications_disabled |
theme | 色彩主題 | dark 、light 、light-daltonized 或 dark-daltonized |
verbose | 是否顯示完整的 bash 和命令輸出(預設:false ) | true |
Claude 可用的工具
Claude Code 可以存取一組強大的工具,幫助它理解和修改您的程式碼庫:
工具 | 描述 | 需要權限 |
---|---|---|
Bash | 在您的環境中執行 shell 命令 | 是 |
Edit | 對特定檔案進行目標編輯 | 是 |
Glob | 基於模式匹配尋找檔案 | 否 |
Grep | 在檔案內容中搜尋模式 | 否 |
LS | 列出檔案和目錄 | 否 |
MultiEdit | 在單一檔案上原子性地執行多個編輯 | 是 |
NotebookEdit | 修改 Jupyter notebook 儲存格 | 是 |
NotebookRead | 讀取和顯示 Jupyter notebook 內容 | 否 |
Read | 讀取檔案內容 | 否 |
Task | 執行子代理來處理複雜的多步驟任務 | 否 |
TodoWrite | 建立和管理結構化任務清單 | 否 |
WebFetch | 從指定 URL 獲取內容 | 是 |
WebSearch | 執行帶有網域過濾的網路搜尋 | 是 |
Write | 建立或覆寫檔案 | 是 |
權限規則可以使用 /allowed-tools
或在權限設定中配置。
使用鉤子擴展工具
您可以使用Claude Code 鉤子在任何工具執行前後執行自訂命令。
例如,您可以在 Claude 修改 Python 檔案後自動執行 Python 格式化程式,或透過阻止對某些路徑的 Write 操作來防止修改生產配置檔案。