Claude Code 設定

Claude Code 提供多種設定選項，以滿足您的需求。您可以在使用互動式 REPL 時執行 /config 命令來配置 Claude Code。

設定檔案

新的 settings.json 檔案格式是我們透過階層式設定配置 Claude Code 的官方機制：

使用者設定定義在 ~/.claude/settings.json 中，適用於所有專案。
專案設定保存在您的專案目錄下的 .claude/settings.json（用於共享設定）和 .claude/settings.local.json（用於本地專案設定）。當創建 .claude/settings.local.json 時，Claude Code 會配置 git 忽略該檔案。
對於 Claude Code 的企業部署，我們還支援企業管理策略設定。這些設定優先於使用者和專案設定。系統管理員可以在 macOS 上將策略部署到 /Library/Application Support/ClaudeCode/policies.json，在 Linux 和透過 WSL 的 Windows 上部署到 /etc/claude-code/policies.json。

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

可用設定

settings.json 支援多種選項：

鍵	描述	範例
`apiKeyHelper`	生成 Anthropic API 金鑰的自定義腳本	`/bin/generate_temp_api_key.sh`
`cleanupPeriodDays`	本地保留聊天記錄的時間（預設：30 天）	`20`
`env`	將應用於每個會話的環境變數	`{"FOO": "bar"}`
`includeCoAuthoredBy`	是否在 git 提交和拉取請求中包含 `co-authored-by Claude` 署名（預設：`true`）	`false`
`permissions`	`allow` 和 `deny` 鍵是權限規則的列表	`{"allow": [ "Bash(npm run lint)" ]}`

設定優先順序

設定按照優先順序應用：

企業策略
命令行參數
本地專案設定
共享專案設定
使用者設定

權限

您可以使用 /permissions 查看和管理 Claude Code 的工具權限。此 UI 列出所有權限規則及其來源的 settings.json 檔案。

允許規則將允許 Claude Code 使用指定的工具，無需進一步手動批准。
拒絕規則將阻止 Claude Code 使用指定的工具。拒絕規則優先於允許規則。

權限規則使用以下格式：Tool(optional-specifier)

僅包含工具名稱的規則匹配該工具的任何使用。例如，將 Bash 添加到允許規則列表中，將允許 Claude Code 使用 Bash 工具而無需用戶批准。查看 Claude 可用工具列表。

特定工具的權限規則

某些工具使用可選說明符來進行更精細的權限控制。例如，帶有 Bash(git diff:*) 的允許規則將允許以 git diff 開頭的 Bash 命令。以下工具支援帶有說明符的權限規則：

Bash

Bash(npm run build) 匹配確切的 Bash 命令 npm run build
Bash(npm run test:*) 匹配以 npm run test 開頭的 Bash 命令。

Claude Code 了解 shell 運算符（如 &&），因此像 Bash(safe-cmd:*) 這樣的前綴匹配規則不會授予它運行 safe-cmd && other-cmd 命令的權限

Read 與 Edit

Edit 規則適用於所有編輯檔案的內建工具。 Claude 將盡最大努力將 Read 規則應用於所有讀取檔案的內建工具，如 Grep、Glob 和 LS。

Read 和 Edit 規則都遵循 gitignore 規範。模式相對於包含 .claude/settings.json 的目錄解析。要引用絕對路徑，請使用 //。對於相對於您的主目錄的路徑，請使用 ~/。

Edit(docs/**) 匹配對專案中 docs 目錄中檔案的編輯
Read(~/.zshrc) 匹配對您的 ~/.zshrc 檔案的讀取
Edit(//tmp/scratch.txt) 匹配對 /tmp/scratch.txt 的編輯

WebFetch

WebFetch(domain:example.com) 匹配對 example.com 的獲取請求

MCP

mcp__puppeteer 匹配由 puppeteer 伺服器提供的任何工具（名稱在 Claude Code 中配置）
mcp__puppeteer__puppeteer_navigate 匹配由 puppeteer 伺服器提供的 puppeteer_navigate 工具

自動更新器權限選項

當 Claude Code 檢測到它沒有足夠的權限來寫入您的全域 npm 前綴目錄（自動更新所需）時，您會看到一個警告，指向本文檔頁面。有關自動更新器問題的詳細解決方案，請參閱故障排除指南。

推薦：創建新的使用者可寫入 npm 前綴

# 首先，保存現有全域套件列表以便日後遷移
npm list -g --depth=0 > ~/npm-global-packages.txt

# 為全域套件創建一個目錄
mkdir -p ~/.npm-global

# 配置 npm 使用新的目錄路徑
npm config set prefix ~/.npm-global

# 注意：根據您的 shell 將 ~/.bashrc 替換為 ~/.zshrc、~/.profile 或其他適當的檔案
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# 應用新的 PATH 設定
source ~/.bashrc

# 現在在新位置重新安裝 Claude Code
npm install -g @anthropic-ai/claude-code

# 可選：在新位置重新安裝您之前的全域套件
# 查看 ~/npm-global-packages.txt 並安裝您想保留的套件
# npm install -g package1 package2 package3...

為什麼我們推薦這個選項：

避免修改系統目錄權限
為您的全域 npm 套件創建一個乾淨、專用的位置
遵循安全最佳實踐

由於 Claude Code 正在積極開發中，我們建議使用上述推薦選項設置自動更新。

禁用自動更新器

如果您更喜歡禁用自動更新器而不是修復權限，您可以將 DISABLE_AUTOUPDATER 環境變數設置為 1

優化您的終端設置

Claude Code 在正確配置的終端中效果最佳。請遵循以下指南來優化您的體驗。

支援的 shell：

Bash
Zsh
Fish

主題和外觀

Claude 無法控制您終端的主題。這由您的終端應用程式處理。您可以在入門過程中或隨時通過 /config 命令將 Claude Code 的主題與您的終端匹配

換行

您有幾種選項可以在 Claude Code 中輸入換行：

快速轉義：輸入 \ 後跟 Enter 創建一個新行
鍵盤快捷鍵：在正確配置的情況下按 Option+Enter（Meta+Enter）

要在您的終端中設置 Option+Enter：

對於 Mac Terminal.app：

打開設置 → 配置文件 → 鍵盤
勾選 “使用 Option 作為 Meta 鍵”

對於 iTerm2 和 VSCode 終端：

打開設置 → 配置文件 → 按鍵
在通用下，將左/右 Option 鍵設置為 “Esc+”

iTerm2 和 VSCode 用戶提示：在 Claude Code 中運行 /terminal-setup 自動配置 Shift+Enter 作為更直觀的替代方案。

通知設置

通過正確的通知配置，永遠不會錯過 Claude 完成任務的時刻：

終端鈴聲通知

啟用任務完成時的聲音提醒：

claude config set --global preferredNotifChannel terminal_bell

對於 macOS 用戶：不要忘記在系統設置 → 通知 → [您的終端應用] 中啟用通知權限。

iTerm 2 系統通知

對於 iTerm 2 在任務完成時的提醒：

打開 iTerm 2 偏好設置
導航至配置文件 → 終端
啟用 “靜音鈴聲” 和過濾提醒 → “發送由轉義序列生成的提醒”
設置您偏好的通知延遲

請注意，這些通知是 iTerm 2 特有的，在默認的 macOS 終端中不可用。

處理大量輸入

當處理大量代碼或長指令時：

避免直接粘貼：Claude Code 可能難以處理非常長的粘貼內容
使用基於檔案的工作流：將內容寫入檔案並要求 Claude 讀取
注意 VS Code 限制：VS Code 終端特別容易截斷長粘貼

Vim 模式

Claude Code 支援一部分 Vim 鍵綁定，可以通過 /vim 啟用或通過 /config 配置。

支援的子集包括：

模式切換：Esc（到 NORMAL），i/I，a/A，o/O（到 INSERT）
導航：h/j/k/l，w/e/b，0/$/^，gg/G
編輯：x，dw/de/db/dd/D，cw/ce/cb/cc/C，.（重複）

環境變數

Claude Code 支援以下環境變數來控制其行為：

所有環境變數也可以在 settings.json 中配置。這是為每個會話自動設置環境變數的有用方法，或者為您的整個團隊或組織推出一組環境變數。

變數	用途
`ANTHROPIC_API_KEY`	API 金鑰，僅在使用 Claude SDK 時（對於互動式使用，運行 `/login`）
`ANTHROPIC_AUTH_TOKEN`	`Authorization` 和 `Proxy-Authorization` 標頭的自定義值（您在此處設置的值將以 `Bearer` 為前綴）
`ANTHROPIC_CUSTOM_HEADERS`	您想添加到請求的自定義標頭（格式為 `Name: Value`）
`ANTHROPIC_MODEL`	要使用的自定義模型名稱（參見模型配置）
`ANTHROPIC_SMALL_FAST_MODEL`	用於背景任務的 Haiku 級模型的名稱
`BASH_DEFAULT_TIMEOUT_MS`	長時間運行的 bash 命令的默認超時
`BASH_MAX_TIMEOUT_MS`	模型可以為長時間運行的 bash 命令設置的最大超時
`BASH_MAX_OUTPUT_LENGTH`	bash 輸出在中間截斷前的最大字符數
`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`	應刷新憑證的間隔（使用 `apiKeyHelper` 時）
`CLAUDE_CODE_USE_BEDROCK`	使用 Bedrock（參見 Bedrock 和 Vertex）
`CLAUDE_CODE_USE_VERTEX`	使用 Vertex（參見 Bedrock 和 Vertex）
`CLAUDE_CODE_SKIP_VERTEX_AUTH`	跳過 Vertex 的 Google 認證（例如，使用代理時）
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	相當於設置 `DISABLE_AUTOUPDATER`、`DISABLE_BUG_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY`
`DISABLE_AUTOUPDATER`	設置為 `1` 以禁用自動更新器
`DISABLE_BUG_COMMAND`	設置為 `1` 以禁用 `/bug` 命令
`DISABLE_COST_WARNINGS`	設置為 `1` 以禁用成本警告消息
`DISABLE_ERROR_REPORTING`	設置為 `1` 以選擇退出 Sentry 錯誤報告
`DISABLE_TELEMETRY`	設置為 `1` 以選擇退出 Statsig 遙測（請注意，Statsig 事件不包括用戶數據，如代碼、檔案路徑或 bash 命令）
`HTTP_PROXY`	指定網絡連接的 HTTP 代理伺服器
`HTTPS_PROXY`	指定網絡連接的 HTTPS 代理伺服器
`MAX_THINKING_TOKENS`	強制為模型預算設置思考
`MCP_TIMEOUT`	MCP 伺服器啟動的超時（毫秒）
`MCP_TOOL_TIMEOUT`	MCP 工具執行的超時（毫秒）

配置選項

我們正在將全域配置遷移到 settings.json。

claude config 將被 settings.json 取代

要管理您的配置，請使用以下命令：

列出設定：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>：

鍵	描述	範例
`autoUpdaterStatus`	啟用或禁用自動更新器（默認：`enabled`）	`disabled`
`preferredNotifChannel`	您希望接收通知的位置（默認：`iterm2`）	`iterm2`、`iterm2_with_bell`、`terminal_bell` 或 `notifications_disabled`
`theme`	顏色主題	`dark`、`light`、`light-daltonized` 或 `dark-daltonized`
`verbose`	是否顯示完整的 bash 和命令輸出（默認：`false`）	`true`

Claude Code

​設定檔案

​可用設定

​設定優先順序

​權限

​特定工具的權限規則

​Bash

​Read 與 Edit

​WebFetch

​MCP

​自動更新器權限選項

​推薦：創建新的使用者可寫入 npm 前綴

​禁用自動更新器

​優化您的終端設置

​主題和外觀

​換行

​通知設置

​終端鈴聲通知

​iTerm 2 系統通知

​處理大量輸入

​Vim 模式

​環境變數

​配置選項

​全域配置

設定檔案

可用設定

設定優先順序

權限

特定工具的權限規則

Bash

Read 與 Edit

WebFetch

MCP

自動更新器權限選項

推薦：創建新的使用者可寫入 npm 前綴

禁用自動更新器

優化您的終端設置

主題和外觀

換行

通知設置

終端鈴聲通知

iTerm 2 系統通知

處理大量輸入

Vim 模式

環境變數

配置選項

全域配置