12 - 設定檔與 CLI 旗標速查

← 11-非互動模式與腳本化 | 00-Index | 下一篇 → 13-實戰-套用在兩個repo

設定檔在哪、誰蓋誰

層級	位置	說明
Managed policy	系統層（IT 部署）	最高，個人無法覆蓋
User	`~/.claude/settings.json`	你所有專案
Project	`.claude/settings.json`	團隊共享，進版控
Local	`.claude/settings.local.json`	個人的專案設定，要 gitignore
CLI	`--settings <file-or-json>`	只影響這次執行，蓋掉同名 key

用 --setting-sources user,project,local 可以指定要載入哪幾層。

.claude/ 目錄整體結構見官方 .claude Directory。

一份給你的起手設定

~/.claude/settings.json：

{
  "permissions": {
    "defaultMode": "plan",
    "allow": [
      "Read",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(git push -f *)"
    ]
  },
  "autoMemoryEnabled": true,
  "model": "sonnet"
}

Obsidian-med-note/.claude/settings.json（進版控，團隊 = 你和所有 AI）：

{
  "permissions": {
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Edit(.quartzsite/**)",
      "Write(.quartzsite/**)"
    ]
  }
}

Obsidian-med-note/.claude/settings.local.json（gitignore）：

{
  "claudeMdExcludes": []
}

💡 claudeMdExcludes 在 monorepo 或有多層 CLAUDE.md 時很有用——可以用 glob 跳過不相關的祖先 CLAUDE.md。你目前用不到，但知道有這個東西。

常用設定 key

Key	說明
`permissions.defaultMode`	預設權限模式。⚠️ `auto` 在 `.claude/settings.json` 和 `.claude/settings.local.json` 會被忽略（repo 不能自己給自己 auto mode），要設在 `~/.claude/settings.json`
`permissions.allow` / `ask` / `deny`	權限規則
`permissions.additionalDirectories`	讓 `--add-dir` 的目錄跨 session 保留
`permissions.disableBypassPermissionsMode`	設 `"disable"` 擋掉 bypass 模式（managed settings）
`permissions.disableAutoMode`	設 `"disable"` 擋掉 auto mode（managed settings）
`model`	預設模型
`fallbackModel`	主模型不可用時的 fallback 鏈
`effortLevel`	預設思考力度
`autoMemoryEnabled`	auto memory 開關
`autoMemoryDirectory`	auto memory 存放位置（絕對路徑或 `~/` 開頭）
`claudeMd`	在 managed settings 裡直接放 CLAUDE.md 內容（只有 managed/policy 層有效）
`claudeMdExcludes`	用 glob 排除特定 CLAUDE.md，各層陣列會合併
`hooks`	Hook 設定（見 09-Hooks自動化）
`sandbox.enabled`	沙箱隔離
`env`	環境變數
`agent`	這個 session 用哪個自訂 agent
`teammateMode`	agent team 隊友的顯示方式
`axScreenReader`	螢幕閱讀器友善輸出
`showClearContextOnPlanAccept`	核准 plan 時多一個「順便清 context」選項
`useAutoModeDuringPlan`	plan mode 期間用 classifier 審查指令（預設開）

完整清單見官方 Settings。

CLI 旗標速查（挑常用的）

Session 控制

Flag	說明
`-p`, `--print`	非互動
`-c`, `--continue`	接續目前目錄最近一次對話
`-r`, `--resume [id\|name]`	接續指定 session，或開選單
`--fork-session`	resume 時開新 session ID 而非沿用
`-n`, `--name "x"`	設 session 顯示名稱（可用名稱 resume）
`--session-id <uuid>`	指定 session ID
`--from-pr 123`	開跟某個 PR 關聯的 session 選單
`--teleport`	把網頁 session 拉回本機終端
`--cloud "task"`	在 claude.ai 開一個網頁 session

模型與思考

Flag	說明
`--model sonnet`	指定模型（alias 或完整 ID）
`--fallback-model sonnet,haiku`	fallback 鏈
`--effort high`	`low`/`medium`/`high`/`xhigh`/`max`/`ultracode`
`--advisor opus`	開 advisor 工具（用更強模型輔助關鍵決策）

權限

Flag	說明
`--permission-mode plan`	起始權限模式
`--allowedTools "Read,Bash(git diff *)"`	免詢問的工具
`--disallowedTools "Edit"`	拒絕規則。裸工具名會把工具從 context 移除；`Bash(rm *)` 這種有範圍的只擋相符呼叫
`--tools "Bash,Edit,Read"`	限制可用的內建工具
`--dangerously-skip-permissions`	= `--permission-mode bypassPermissions` ⚠️
`--allow-dangerously-skip-permissions`	只是把 bypass 加進 `Shift+Tab` 循環，不會直接進去

Context 與設定

Flag	說明
`--add-dir ../apps ../lib`	加可存取的目錄（只給檔案存取，大部分 `.claude/` 設定不會被探索，但 `.claude/skills/` 是例外）
`--settings ./s.json`	載入設定（可用 inline JSON）
`--setting-sources user,project`	只載入指定來源
`--mcp-config ./mcp.json`	載入 MCP
`--strict-mcp-config`	只用 `--mcp-config` 的 MCP
`--agents '{"reviewer":{...}}'`	動態定義 subagent
`--plugin-dir ./my-plugin`	載入本機 plugin
`--append-system-prompt "..."`	附加到預設 system prompt
`--system-prompt "..."`	取代整個 system prompt
`--bare`	極簡模式，跳過所有自動探索
`--safe-mode`	停用所有客製（救援用）

輸出（print mode）

Flag	說明
`--output-format text\|json\|stream-json`	輸出格式
`--json-schema '{...}'`	保證符合 schema 的結構化輸出
`--include-partial-messages`	串流部分訊息
`--verbose`	完整逐輪輸出
`--max-turns 3`	限制輪數
`--max-budget-usd 5.00`	花費上限

平行與 worktree

Flag	說明
`-w`, `--worktree [name]`	在隔離 git worktree 開 session
`--tmux`	幫 worktree 開 tmux（需搭 `--worktree`）
`--bg`, `--background`	開成背景 agent，立刻返回
`--exec 'pytest -x'`	跑一個 shell 指令當背景 job（搭 `--bg`）

其他

Flag	說明
`--ide`	啟動時自動連 IDE
`--chrome` / `--no-chrome`	Chrome 整合
`--remote-control [name]`, `--rc`	開 Remote Control（可從 claude.ai / 手機控制）
`--debug "api,mcp"`	debug 模式（可分類過濾）
`--debug-file /tmp/x.log`	debug log 寫檔
`-v`, `--version`	版本

📌 claude --help 不會列出所有 flag——某個 flag 沒出現在 help 裡不代表不能用。以官方 CLI reference 為準。

CLI 子指令速查

claude update                      # 更新
claude install [version|stable|latest]
claude doctor                      # 唯讀診斷（不開 session）
claude auth login|logout|status
claude setup-token                 # CI 用的長效 token
claude mcp                         # MCP 設定
claude mcp login|logout <name>
claude plugin ...                  # plugin 管理（別名 claude plugins）
claude agents [--json] [--cwd path]  # agent view
claude attach <id>                 # 接上背景 session
claude logs <id>                   # 看背景 session 輸出
claude stop <id>                   # 停（別名 claude kill）
claude respawn <id> [--all]        # 重啟（對話保留）
claude rm <id>                     # 從清單移除
claude daemon status               # 背景 session supervisor 狀態
claude daemon stop --any [--keep-workers]
claude project purge [path] [--dry-run] [-y]   # 刪掉某專案的所有本機狀態
claude remote-control [--name "x"]
claude ultrareview [target] [--json]
claude auto-mode defaults [--label prefix]     # 印出 classifier 預設規則
claude auto-mode reset [-y]

⚠️ claude project purge 會刪掉 transcript、任務清單、debug log、檔案編輯歷史、prompt 歷史，以及 ~/.claude.json 裡該專案的條目。先用 --dry-run 看清楚。

環境變數（挑常用的）

變數	用途
`ANTHROPIC_API_KEY`	用 API key 而非訂閱登入 ⚠️ 設了會跳過登入流程
`CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`	關掉 auto memory
`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`	讓 `--add-dir` 的目錄也載入 CLAUDE.md
`CLAUDE_CODE_NEW_INIT=1`	`/init` 用互動式多階段流程
`CLAUDE_CODE_SAFE_MODE`	等同 `--safe-mode`
`CLAUDE_CODE_SIMPLE`	等同 `--bare`
`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`	print mode 等背景 agent 的上限（預設 10 分鐘，`0` = 不限）
`CLAUDE_CODE_SKIP_PROMPT_HISTORY`	不存 session
`CLAUDE_CONFIG_DIR`	換設定目錄位置
`CLAUDE_AX_SCREEN_READER`	螢幕閱讀器模式

完整清單見官方 Environment variables。

🔗 相關筆記

11-非互動模式與腳本化 — 上一步
13-實戰-套用在兩個repo — 下一步：實際該怎麼設
05-權限模式與安全 — 權限相關 key 的完整說明
14-疑難排解與速查表 — 設定壞掉時

最後更新：2026-08-04

Andrew的筆記園地

探索

目錄