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
範例 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-KeyAuthorization: Bearer 標頭發送給模型請求/bin/generate_temp_api_key.sh
cleanupPeriodDays根據最後活動日期在本地保留聊天記錄的時間長度(預設:30 天)20
env將應用於每個會話的環境變數{"FOO": "bar"}
includeCoAuthoredBy是否在 git 提交和拉取請求中包含 co-authored-by Claude 署名(預設:truefalse
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/**)" ]
additionalDirectoriesClaude 可以存取的額外工作目錄[ "../docs/" ]
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.ai 不同,我們不在此網站上發布 Claude Code 的內部系統提示。使用 CLAUDE.md 檔案或 --append-system-prompt 來為 Claude Code 的行為添加自訂指令。

排除敏感檔案

為了防止 Claude Code 存取包含敏感資訊的檔案(例如 API 金鑰、機密、環境檔案),請在您的 .claude/settings.json 檔案中使用 permissions.deny 設定:

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

這取代了已棄用的 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_TOKENAuthorization 標頭的自訂值(您在此設定的值將以 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_LENGTHbash 輸出在中間截斷之前的最大字元數
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_AUTOUPDATERDISABLE_BUG_COMMANDDISABLE_ERROR_REPORTINGDISABLE_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_TIMEOUTMCP 伺服器啟動的逾時(毫秒)
MCP_TOOL_TIMEOUTMCP 工具執行的逾時(毫秒)
MAX_MCP_OUTPUT_TOKENSMCP 工具回應中允許的最大權杖數(預設: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您想要接收通知的位置(預設:iterm2iterm2iterm2_with_bellterminal_bellnotifications_disabled
theme色彩主題darklightlight-daltonizeddark-daltonized
verbose是否顯示完整的 bash 和命令輸出(預設:falsetrue

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 操作來防止修改生產配置檔案。

另請參見