部落格 / 開發工具

Claude Code settings.json 層級、優先順序與 env 配置

2026-10-22cdnping 編輯部約 6 分鐘讀完

Claude Code settings.json 一共有四個位置：使用者級 ~/.claude/settings.json、專案共享的 .claude/settings.json、專案本地的 .claude/settings.local.json，以及管理員下發的託管策略檔案。同一個欄位在多處出現時，越靠近“當前這臺機器、這個專案”的越優先，託管策略最高。介面地址、代理這類變數寫在 env 欄位裡，寫完以後用 /status 看實際生效值，不要靠猜。

下面按“檔案在哪、誰覆蓋誰、寫什麼、怎麼驗證”的順序展開。欄位名和路徑以 Anthropic 官方 settings 文件 為準，Claude Code 更新頻繁，遇到出入請以文件當前版本為準。

#settings.json 有幾個，分別放在哪？

幾點容易混淆的地方：

• ~/.claude.json（注意沒有子目錄）是 Claude Code 自己維護的狀態檔案，裡面有登入狀態、專案歷史、MCP 伺服器等內容，它不是 settings.json，一般不需要手改。
• CLAUDE.md 是給模型讀的專案說明，屬於“記憶”，不是配置。許可權、環境變數不要寫進 CLAUDE.md，寫了也不會被當作設定執行。
• settings.local.json 由 Claude Code 建立時，會自動配置 git 忽略它；如果你是手動建的，最好自己檢查一下 .gitignore。

#多個檔案衝突時，誰說了算？

官方文件給出的優先順序從高到低是：

1. 託管策略（managed-settings.json）
2. 命令列引數（例如 --model、--settings <檔案>、--permission-mode）
3. 專案本地 .claude/settings.local.json
4. 專案共享 .claude/settings.json
5. 使用者級 ~/.claude/settings.json

也就是常說的“5 層優先順序”。只看順序容易誤判，還要記住兩條規則：

標量欄位按優先順序覆蓋。 比如 model 在使用者級寫了一個值、專案本地又寫了一個，生效的是專案本地那個。env 裡的同名變數也一樣，高優先順序的那一層贏。

許可權規則是合併的，不是覆蓋。 permissions.allow、permissions.deny 這類陣列會把各層的規則合起來一起判斷，而 deny 優先於 allow。所以如果團隊在專案共享配置裡 deny 了 Bash(curl:*)，你在本地 allow 它也沒用。託管策略裡的 deny，使用者在任何一層都改不掉。

#常用欄位一張表

寫之前可以在檔案頂部加一行 "$schema": "https://json.schemastore.org/claude-code-settings.json"，VS Code 等編輯器會據此做欄位補全和校驗，拼錯欄位名能當場看出來。

#env 裡放介面地址和代理，作用範圍是什麼？

env 的效果相當於在啟動 Claude Code 之前替你 export 了這些變數，作用於 Claude Code 程序本身；Claude Code 透過 Bash 工具執行的命令一般也能讀到這些變數。它不會改你的系統環境，也不會影響你在另一個終端裡手動執行的程式。

常見的變數可以分成三類，放的位置不同：

幾個實際會踩到的點：

代理變數會被子命令繼承。 你在 env 裡設了 HTTPS_PROXY，Claude Code 幫你跑 npm install、git fetch 時也會走這個代理。如果內網倉庫或國內映象不該走代理，就要在 NO_PROXY 裡列出來，例如 "NO_PROXY": "localhost,127.0.0.1,.internal.example.com"。

介面地址只在一個專案裡改，就寫進本地檔案。 假設你平時用官方介面，只有某個專案要走公司閘道器，把 ANTHROPIC_BASE_URL 寫進那個專案的 .claude/settings.local.json 即可，其他專案不受影響。介面地址具體怎麼填、Codex 和 OpenCode 對應寫在哪，見 Claude Code 自定義 API 與 Codex、OpenCode 介面地址配置，這裡不重複。

shell 裡也設了同名變數時，以 /status 為準。 按官方說法，settings 裡的 env 會應用到每個會話；但不同版本對“shell 已有變數”和“settings 變數”同名時的處理細節可能變化。遇到“我明明改了卻不生效”，第一步是看下面的驗證步驟，而不是反覆改檔案。

程序啟動時就要讀的變數放 shell。 像 NODE_EXTRA_CA_CERTS（公司自簽證書）這種 Node.js 啟動階段讀取的變數，寫在 settings 的 env 裡可能來不及生效，穩妥做法是在 shell 配置裡 export。

#改完之後，怎麼確認是哪一層生效？

下面的檢查按順序做：

1. 校驗 JSON 語法。一個多餘的逗號就會讓整個檔案被忽略：

   for f in ~/.claude/settings.json .claude/settings.json .claude/settings.local.json; do
     [ -f "$f" ] && (python3 -m json.tool "$f" >/dev/null && echo "OK  $f" || echo "BAD $f")
   done
   

2. 重啟會話。settings 在啟動時讀取，已經開啟的會話不一定會重新載入 env。退出後重新執行 claude。
3. 在會話裡執行 /status。它會顯示當前的認證方式、模型、介面地址等資訊，部分版本還會列出讀取到了哪些設定來源。看這裡的介面地址和代理是不是你期望的值。
4. 執行 /permissions，列出當前生效的 allow / deny 規則。某條規則不起作用時，看看是不是被另一層的 deny 蓋住了。
5. 執行 /config，開啟設定介面，檢視和修改使用者級常用選項。注意它改的是哪一層檔案，不確定時回到第 3 步核對。
6. 讓 Claude 列印環境變數。直接讓它執行 env | grep -iE 'proxy|anthropic'，看 Bash 工具拿到的值。輸出裡可能有金鑰，只在自己機器上看，不要貼到群裡或 issue 裡。
7. 出問題時執行 /doctor。它會檢查安裝狀態和配置問題，部分版本會提示設定檔案裡的無效欄位。

如果 /status 顯示配置都對，但請求還是超時或報錯，問題多半不在配置檔案，而在網路或服務端。這時按 Claude Code 連線超時和報錯怎麼排查：四層網路檢查清單 逐層看；也可以先開啟 Claude Code 掛了嗎 和 Anthropic API 狀態 確認服務端當前有沒有故障，排除對方的問題再查自己。代理是否真正生效、出口 IP 在哪，可以用 IP 與環境檢測 看一眼。

#團隊共享配置和個人配置怎麼分開放？

一個比較穩的分法：倉庫裡只放“所有人都該一樣”的東西，凡是跟人、跟機器、跟金鑰有關的都留在本地。

專案共享 .claude/settings.json（提交到倉庫）示例：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "DISABLE_TELEMETRY": "1"
  },
  "includeCoAuthoredBy": false
}

專案本地 .claude/settings.local.json（不提交）示例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.example.com",
    "ANTHROPIC_AUTH_TOKEN": "替換為你自己的金鑰",
    "HTTPS_PROXY": "http://127.0.0.1:7890",
    "NO_PROXY": "localhost,127.0.0.1"
  },
  "permissions": {
    "additionalDirectories": ["../my-scratch"]
  }
}

上面的地址、埠和目錄都是示例，請換成你自己的值。

.gitignore 里加上：

# Claude Code 個人配置，不進倉庫
.claude/settings.local.json
# 如果有人習慣在專案裡放 CLAUDE.local.md，也一起忽略
CLAUDE.local.md

提交前可以再確認一次：

git check-ignore -v .claude/settings.local.json   # 應輸出命中的忽略規則
git ls-files .claude/                              # 不應出現 settings.local.json

如果金鑰已經被提交過，光加 .gitignore 不夠，需要到服務商後臺把這把金鑰作廢重建。把程式碼和配置交給第三方介面之前，先看一下對方的資料政策，可以參考 用第三方 AI API 時，程式碼和對話會被看到嗎。

#幾個常見問題

#改了 settings.json 沒反應？

按順序排查：JSON 是否合法 → 是否重啟了會話 → 是否有更高一層的同名欄位覆蓋 → shell 裡是否有同名變數 → /status 顯示的值是什麼。大部分情況停在前三步。

#能不能只在某次啟動時臨時換一套配置？

可以用 claude --settings ./某個檔案.json 載入額外的設定檔案，它的優先順序在命令列引數這一層，高於專案和使用者配置，適合臨時測試另一個介面地址或模型，不用改動常用檔案。

#配置都對，就是慢？

那就不是配置問題了。延遲通常來自網路路徑、代理節點或服務端排隊，可以看 Claude Code 響應很慢：延遲來自哪裡，怎麼判斷和最佳化。需要放行哪些域名和埠，見 Claude Code 與 Codex 的網路要求。在瀏覽器裡也可以用 cdnping 線上測速 看一下到各家 API 的首次連線和往返時間，作為參考。

最後提醒一句：透過代理或第三方介面使用 Claude Code 時，請遵守 Anthropic 的服務條款和所在地的法規，地區可用性以官方說明為準。