---
title: "12 - 設定檔與 CLI 旗標速查"
type: note
specialty: Programming
tags: [claude-code-cli從0開始使用教學, 12-settings, cli-flags, cheatsheet]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 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](https://code.claude.com/docs/en/claude-directory)。

---

## 一份給你的起手設定

`~/.claude/settings.json`：

```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）：

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

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

```json
{
  "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](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/cli-reference) 為準。

---

## CLI 子指令速查

```bash
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](https://code.claude.com/docs/en/env-vars)。

---

## 🔗 相關筆記

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

---

*最後更新：2026-08-04*