AI 相關紀錄 v4｜Claude Code settings / Codex config 基本設定

整理 Claude Code settings.json 與 Codex config.toml 的設定層級、權限控制和常見基本設定。

發布於 2026.09.04W

前面幾篇整理了：

CLAUDE.md
AGENTS.md
.claude/
.codex/
使用者層級與專案層級設定

接下來進一步看：

Claude Code / Codex 本身有哪些執行設定？

如果 CLAUDE.md、AGENTS.md 比較像是在告訴 AI：

「這個專案應該怎麼工作？」

那 settings.json、config.toml 比較像是在控制：

「Coding Agent 實際可以怎麼執行？」

例如：

使用哪個 Model
哪些操作允許執行
哪些操作需要先詢問
Sandbox 可以存取哪些範圍
Hooks
環境設定
MCP / 工具設定

先看設定檔放哪裡

Claude Code

Claude Code 主要使用 JSON 設定檔。

使用者層級：

~/.claude/
└─ settings.json

專案共用：

my-project/
└─ .claude/
   └─ settings.json

專案中的個人 Local 設定：

my-project/
└─ .claude/
   └─ settings.local.json

可以先簡單記成：

~/.claude/settings.json
↓
自己的預設設定

.claude/settings.json
↓
專案共同使用的設定

.claude/settings.local.json
↓
自己在這個專案使用的設定

Codex

Codex 主要使用：

config.toml

使用者層級：

~/.codex/
└─ config.toml

Windows 通常可以寫成：

%USERPROFILE%\.codex\
└─ config.toml

專案設定則可以放：

my-project/
└─ .codex/
   └─ config.toml

可以簡單記成：

~/.codex/config.toml
↓
自己的 Codex 預設設定

.codex/config.toml
↓
目前專案的 Codex 設定

Codex 只有在專案被視為 Trusted 時，才會讀取專案裡的 .codex/config.toml。

Claude Code：`settings.json`

Claude Code 的主要設定檔使用 JSON。

例如可以設定：

Permission
Hooks
環境變數
Plugin
工具行為
其他 Claude Code 設定

使用者設定：`~/.claude/settings.json`

如果希望某些設定套用到自己使用 Claude Code 的多個專案，可以放在：

~/.claude/settings.json

例如這些比較偏向：

自己平常使用 Claude Code 的預設習慣。

專案設定：`.claude/settings.json`

如果設定只屬於某個專案，或希望整個團隊共同使用，可以放：

my-project/
└─ .claude/
   └─ settings.json

例如：

專案允許使用哪些 Command
專案需要哪些 Hook
團隊共同使用的 Permission
專案相關工具設定

這類設定就比較適合跟著專案一起管理。

個人專案設定：`.claude/settings.local.json`

另外還有：

.claude/settings.local.json

可以把它理解成：

我自己在「這個專案」裡使用的設定。

例如有某個 Permission：

自己開發時需要
其他開發者不一定需要
不適合直接變成整個團隊的設定

這時就可以放在：

.claude/settings.local.json

這類 Local 設定通常不需要提交給其他開發者。

簡單理解：

settings.json
↓
專案共用

settings.local.json
↓
專案裡自己使用

Claude Code 設定層級

如果先不討論企業環境的 Managed Settings，可以大致理解成：

使用者設定
~/.claude/settings.json
        ↓

專案設定
.claude/settings.json
        ↓

專案 Local 設定
.claude/settings.local.json

越接近目前專案與個人的設定，可以補充或覆蓋比較上層的設定。

所以：

~/.claude/settings.json

適合放自己的預設值；

.claude/settings.json

放這個專案共同使用的內容；

.claude/settings.local.json

則放只有自己在這個專案需要的設定。

Claude Code Permission

其中我覺得很重要的一項就是 Permission。

Claude Code 可以設定哪些操作：

allow
↓
允許執行

ask
↓
執行前先詢問

deny
↓
禁止執行

禁止讀取敏感檔案

例如不希望 Claude Code 讀取 .env：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

這樣除了在 CLAUDE.md 裡告訴 AI：

不要讀取 .env

還可以直接透過 Permission 限制工具行為。

兩者概念其實不太一樣：

CLAUDE.md
↓
告訴 AI 不應該做什麼

Permission
↓
直接限制工具能不能做

如果是敏感資訊，我會比較傾向不只依賴 Prompt，而是搭配 Permission。

允許特定 Command

也可以允許某些常用 Command。

例如：

{
  "permissions": {
    "allow": [
      "Bash(npm lint)",
      "Bash(npm test *)"
    ]
  }
}

代表這些操作可以直接執行，不需要每次都重新詢問。

例如專案經常需要執行：

npm lint

或：

npm test

就可以依照自己的使用需求決定是否加入。

`deny`、`ask`、`allow` 的優先順序

Claude Code 判斷 Permission 時，可以先記一個順序：

deny
↓
ask
↓
allow

也就是：

deny 的限制優先。

假設某個操作同時符合 allow 與 deny，仍然會被禁止。

所以敏感操作可以優先放在：

{
  "permissions": {
    "deny": []
  }
}

避免因為其他比較寬鬆的 Allow Rule 而被放行。

Codex：`config.toml`

Codex 主要使用：

config.toml

來控制 Codex 本身的執行設定。

例如：

Model
Reasoning
Approval
Sandbox
MCP
Agent
其他執行設定

使用者設定

自己的預設設定可以放在：

~/.codex/config.toml

Windows：

%USERPROFILE%\.codex\config.toml

例如：

model = "gpt-5.6"

代表設定自己的預設 Model。

專案設定

如果某個設定只想套用到特定專案，可以建立：

my-project/
└─ .codex/
   └─ config.toml

例如：

~/.codex/config.toml
↓
自己的預設設定

.codex/config.toml
↓
這個專案的特殊設定

所以如果不同專案需要不同的 Sandbox、MCP 或其他設定，就不需要全部放在自己的全域設定裡。

Codex 基本設定範例

例如：

model = "gpt-5.6"

approval_policy = "on-request"

sandbox_mode = "workspace-write"

先簡單理解：

model
↓
預設使用哪個模型

approval_policy
↓
Codex 在什麼情況可以要求使用者批准操作

sandbox_mode
↓
Codex 執行 Command 時，可以存取哪些範圍

`model`

例如：

model = "gpt-5.6"

用來設定預設使用的 Model。

如果平常固定使用某個模型，就可以放在自己的：

~/.codex/config.toml

如果某個專案有不同需求，也可以在專案設定中調整。

`approval_policy`

例如：

approval_policy = "on-request"

可以先理解成：

Codex 在需要額外權限時，可以詢問使用者是否批准。

Approval 與 Sandbox 是兩個很容易混在一起的概念。

Approval 比較偏向：

「這個操作需要問我嗎？」

而 Sandbox 比較偏向：

「這個操作本身可以碰到哪裡？」

`sandbox_mode`

例如：

sandbox_mode = "workspace-write"

Sandbox 是用來限制 Codex 執行 Command 時能操作的範圍。

常見模式可以先簡單理解成：

read-only
↓
主要只能讀取

workspace-write
↓
可以在目前 Workspace 中寫入

danger-full-access
↓
限制非常少

一般開發情境下：

workspace-write

會比直接開放完整系統存取更容易控制範圍。

而：

danger-full-access

代表更高的操作能力，也代表需要更清楚自己正在開放什麼權限。

Approval 和 Sandbox 差在哪？

這兩個第一次看到很容易搞混。

我會先這樣記：

Approval
↓
要不要先問我？


Sandbox
↓
就算允許執行，可以碰到哪裡？

例如 Codex 想執行某個 Command。

第一個問題可能是：

這個操作需不需要使用者批准？

接著才是：

即使允許執行，Sandbox 可以讓它讀寫哪些檔案與資源？

所以兩者是不同層級的安全控制。

`CLAUDE.md` / `AGENTS.md` 和設定檔差在哪？

寫到這裡，我覺得這是最容易混淆的地方。

前面介紹的：

CLAUDE.md
AGENTS.md

也是在「設定 AI」。

那跟：

settings.json
config.toml

到底有什麼差別？

可以先簡單理解：

CLAUDE.md / AGENTS.md
↓
告訴 AI「工作應該怎麼做」


settings.json / config.toml
↓
控制 Coding Agent「實際可以怎麼執行」

例如：

專案統一使用 npm

比較適合：

CLAUDE.md
AGENTS.md

因為這是：

專案工作規範。

修改完成後一定執行 lint

也比較偏向：

CLAUDE.md
AGENTS.md

例如：

修改完成後執行：

- npm lint
- npm test

是否允許直接執行 lint

這就比較偏向：

settings.json
config.toml

因為這是在控制：

Coding Agent 有沒有權限實際執行 Command。

不要讀取 `.env`

則兩邊都可以處理，但目的不同。

在：

CLAUDE.md

寫：

- 不要讀取 `.env`。

是告訴 AI：

這是專案規則。

而在 Permission 裡：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

則是：

直接限制工具的能力。

所以比較重要的限制，不一定只能依靠其中一種方式。

我自己會怎麼分？

目前我會先這樣判斷。

如果問題是：

AI 應該怎麼工作？

放：

CLAUDE.md
AGENTS.md

例如：

Coding Style
專案架構
測試流程
套件管理規則
修改完成後要做什麼
哪些事情原則上不要做

如果問題是：

AI 實際可以怎麼執行？

放：

settings.json
config.toml

例如：

Permission
Approval
Sandbox
Model
Hook
MCP
工具執行設定

最後簡單整理

Claude Code：

~/.claude/settings.json
↓
使用者預設設定

.claude/settings.json
↓
專案共用設定

.claude/settings.local.json
↓
自己在目前專案使用的設定

Codex：

~/.codex/config.toml
↓
使用者預設設定

.codex/config.toml
↓
目前專案設定

而整個概念可以先記成：

CLAUDE.md / AGENTS.md
↓
工作規則


settings.json / config.toml
↓
工具執行設定

第一次接觸不用急著把所有 Permission、Sandbox、Approval、Hook 都設定好。

我自己會比較傾向：

先使用預設設定，實際遇到需要控制權限或工作流程的情況，再逐步增加。

不然一開始設定太多，反而很難知道到底是哪一條規則影響了 Agent 的行為。

先理解：

規則是什麼、工具能做什麼、哪些操作需要批准。

後面再繼續深入 Permission、Sandbox、Hook 等設定，會比較容易理解。

分享這篇

X Facebook LINE Threads