Claude Code 企業級軟體開發教學手冊

Enterprise Claude Code AI Software Engineering Handbook 把 Claude Code 當成 企業級 AI 軟體工程平台（AI Software Engineering Platform） 導入 Web 應用開發、Legacy 逆向工程、Framework 升版、測試、Code Review、DevSecOps、CI/CD 與 AI 治理的完整實作手冊

文件資訊

可信度標示制度（請務必先讀）

Claude Code 在 2025–2026 年間的產品架構變動幅度極大：預設權限模式反轉、新機制 GA、舊機制下架，全部發生在 12 個月內。網路上（包含中文技術部落格、影片教學、AI 產生的文章）有大量內容已經過時，而且過時的部分往往正是企業最在意的權限、沙箱與治理設定。

為避免讀者把「本手冊的企業實務建議」誤讀成「Anthropic 官方規範」，本手冊在每個小節標題後標註來源等級：

凡涉及版本行為差異之處，一律以下列格式標註：

⚠️ Version Note

說明哪個版本 / 哪個時間點之前與之後的行為不同。

本手冊的提示方塊符號約定：

十個必須先知道的事實與版本差異

在讀任何舊教學、舊部落格文章、或任何 AI 產生的 Claude Code 教學之前，先記住這十件事。（📌 v1.2：Version Note 3 已依 v2.1.277 的 AGENTS.md 原生支援全面更正；另見第 2.3.2 節 的最新變更與附錄 H 的時間軸。）它們每一項都足以讓整篇教學寫錯，而其中 Version Note 1 與 2 是會在管理員未採取任何動作的情況下自動改變開發者行為的變更。

🚨 Version Note 1：Pro / Max / Team 方案的預設權限模式已是 auto（自動模式），不再是「每次都問你」

這是 2026 年最重要、也最容易在企業導入時出事的變更。

• 過去：Claude Code 啟動後預設為 Manual（設定值 default），每次編輯檔案、執行 shell 指令都會停下來問你。
• 現在：在 Pro、Max、Team 方案的終端機與 VS Code 擴充互動式 session 中，內建起始權限模式是 auto。在 auto mode 下，由另一個分類器模型（classifier）在背景審查動作並阻擋高風險行為，而不是停下來問你。

也就是說，開發者在你不知情的情況下，可能已經在一個「AI 自己決定要不要執行」的模式下工作。

	舊行為	現行行為
Pro/Max/Team 終端機起始模式	Manual（default）	auto
誰核准動作	你，逐次核准	分類器模型，只有它判定危險時才擋
Enterprise 方案 / Console API key / claude -p / Agent SDK / Bedrock / Vertex / Foundry	default	default（未改變）

需要 Claude Code v2.1.228 以上（原生 Windows 為 v2.1.233 以上）。若組織要移除這個行為，必須在 managed settings 設 permissions.disableAutoMode 為 "disable"。詳見第 22 章。

🚨 Version Note 2：.claude/settings.json 裡設 "defaultMode": "auto" 是無效的

這是最常見的「設了卻沒生效」問題。permissions.defaultMode 的值中，auto 與 bypassPermissions 這兩個值在專案層設定檔（.claude/settings.json 與 .claude/settings.local.json）中不會生效：

• 設 "auto" → 該值被忽略，且 Claude Code 會改用內建預設，而不是退回 ~/.claude/settings.json 的 defaultMode。
• 設 "bypassPermissions" → 該值被忽略，session 以 Manual 啟動。

auto 必須寫在 ~/.claude/settings.json（使用者層）或 managed settings。其餘值（default、acceptEdits、plan、dontAsk）在任何設定檔都有效。

🚨 Version Note 3（v1.2 全面更正）：Claude Code 自 v2.1.277 起會直接讀 AGENTS.md，但「有 CLAUDE.md 就不讀」

本手冊 v1.0／v1.1 記載「Claude Code 只讀 CLAUDE.md，不讀 AGENTS.md」。這在 v2.1.277（2026-09-18）之後已不正確。

repo 的狀態	Claude 預設讀什麼
有 AGENTS.md，工作目錄及其上層沒有 CLAUDE.md／.claude/CLAUDE.md／CLAUDE.local.md	AGENTS.md
AGENTS.md 與任一種 CLAUDE.md 並存	只讀 CLAUDE.md（AGENTS.md 被忽略）
CLAUDE.md 內以 @AGENTS.md 匯入	CLAUDE.md，並經匯入包含 AGENTS.md（不會重複載入）

三個最容易出事的細節：

1. 個人的 CLAUDE.local.md 也算數：開發者為了放個人指示而新增 CLAUDE.local.md，會讓 Claude 不再讀團隊共用的 AGENTS.md。
2. 可以用「Project instructions」設定改變行為：claude-md-or-agents-md（預設）、claude-md-and-agents-md、claude-md、managed-only。此值只能寫在使用者設定、--settings 或 managed settings，專案層設定檔中會被忽略。
3. 不是每個 session 都能讀：v2.1.277 之前的版本、停用內建 agents-md plugin 的 session，以及 v2.1.281 之前在 Bedrock 或關閉遙測的 session，都只讀 CLAUDE.md。

🎯 企業建議：跨工具共用 repo 時，仍以「CLAUDE.md 第一行 @AGENTS.md」為標準寫法。這種寫法在所有版本與 Provider 上行為一致，也不受 CLAUDE.local.md 影響。不要用 symlink：在 Windows 上建立 symlink 需要系統管理員權限或開發者模式，而且 Git 在未啟用 core.symlinks 時會把它 checkout 成只有一行的純文字檔。詳見第 14.8 節。

🚨 Version Note 4：Bash 沙箱不支援原生 Windows

Claude Code 內建的 sandboxed Bash tool 只在 macOS / Linux / WSL2 上運作（macOS 用 Seatbelt，Linux 與 WSL2 用 bubblewrap）。原生 Windows 沒有這一層防護，WSL1 也不支援。

這對以 Windows 為開發標配的企業影響極大：如果你的資安規範寫「所有 Claude Code session 必須啟用沙箱」，那麼在 Windows 上這條規範技術上無法成立，必須改以 WSL2、容器或 VM 落實。詳見第 23 章。

⚠️ Version Note 5：Agent Teams 是實驗性功能，且預設關閉

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 未設定時，Claude Code 不會建立任何 team、不會寫 team 目錄、也不會 spawn teammate。舊文章示範的 TeamCreate / TeamDelete 工具已經不存在。

更要注意的副作用：一旦啟用 agent teams，Claude 自行為 subagent 命名時，那個 subagent 會以 teammate 身分啟動——也就是說，你沒有要求組隊，team 也可能自己形成。詳見第 18 章。

🚨 Version Note 6：企業管控檔案路徑在 Windows 上已改變

現行的 managed-settings.json 路徑為：

• macOS：/Library/Application Support/ClaudeCode/managed-settings.json
• Linux 與 WSL：/etc/claude-code/managed-settings.json
• Windows：C:\Program Files\ClaudeCode\managed-settings.json

Claude Code 不再讀取舊的 Windows 路徑 C:\ProgramData\ClaudeCode\managed-settings.json。 若你的 MDM 腳本還在往舊路徑佈署，政策等於完全沒生效，而且不會有任何錯誤訊息。詳見第 8 章。

⚠️ Version Note 7：Skill、Subagent、Hook、MCP、Plugin、Rule、CLAUDE.md 是七種不同的機制

這七者經常被混用，但它們的檔案位置、載入時機、覆寫規則完全不同：

機制	檔案位置	載入時機
CLAUDE.md（及 v2.1.277+ 的 AGENTS.md）	./CLAUDE.md、./.claude/CLAUDE.md、~/.claude/CLAUDE.md、managed policy 路徑；無 CLAUDE.md 時為 ./AGENTS.md	每個 session 開始
Rules	.claude/rules/*.md（可加 paths: frontmatter）	每個 session，或讀到符合路徑的檔案時
Auto Memory	~/.claude/projects/<project>/memory/MEMORY.md	每個 session（前 200 行或 25KB）
Skills	.claude/skills/<name>/SKILL.md、~/.claude/skills/、plugin skills/	開始載 description，使用時載全文
Subagents	.claude/agents/*.md、~/.claude/agents/、plugin agents/	被 spawn 時（獨立 context）
Hooks	settings.json 的 hooks 區塊、plugin hooks/hooks.json	生命週期事件觸發時
MCP	.mcp.json、~/.claude.json、managed MCP	session 開始（tool 名稱）
Plugins	.claude-plugin/plugin.json	安裝並啟用後

完整比較見第 14 章 至第 21 章。

⚠️ Version Note 8：不要把 GitHub Copilot / Cursor / Codex CLI 的設定方式套到 Claude Code

這幾個工具的概念詞彙高度重疊（agent、skill、hook、MCP、sandbox），但設定檔位置與 schema 完全不同。

例外只有 Claude Code 刻意提供的相容能力：

• /init 會讀 .cursor/rules/、.cursorrules、.github/copilot-instructions.md
• /import 指令（需 v2.1.213+）可以把其他 coding agent 的設定匯入
• v2.1.277 起可直接讀 AGENTS.md（條件見 Version Note 3）；但 AGENTS.local.md、AGENTS.override.md 與 .agents/ 目錄不會被讀取

除此之外，任何「把 .cursorrules 改個名字就能用」的說法都是錯的。

🚨 Version Note 9：Code Review（GitHub 託管服務）與 /code-review（本機指令）是兩個不同的東西

• Code Review：Anthropic 託管的 GitHub PR 自動審查服務，research preview、僅 Team / Enterprise、ZDR 組織不可用，由 Owner 在 claude.ai 管理後台啟用，每次審查約 $15–25、走 usage credits 另計。
• /code-review：Claude Code 內建的 bundled skill，在本機 session 以背景 subagent 審查目前分支的 diff，所有方案可用、不需安裝 GitHub App。

兩者的成本模型、資料流、治理方式完全不同。企業規範若把兩者寫成同一件事，預算與資安評估都會出錯。詳見第 36 章。

🚨 Version Note 10：--dangerously-skip-permissions 不是「省事」選項，而是「必須搭配隔離環境」的選項

官方明確要求：使用 --dangerously-skip-permissions 的 session 必須跑在容器、VM 或 sandbox runtime 內，讓檔案工具、MCP server 與 hook 都在隔離邊界內；且在 Linux 與 macOS 上，以 root 身分執行時 Claude Code 會拒絕啟動。

內建的 Bash 沙箱只約束 Bash，不涵蓋 Read/Edit/WebFetch 等內建工具，也不涵蓋 MCP server 與 hook 行程，因此單靠 Bash 沙箱不足以支撐無人值守的 bypass 模式。詳見第 23 章。

本手冊的引用與誠實原則

1. 本手冊不是官方文件的翻譯。 所有官方事實均經查證後以繁體中文重新組織，並大量補充企業導入實務、Agent 定義、Prompt 範例、比較表、SOP 與 Checklist。
2. 不虛構。 本手冊不編造 URL、CLI 指令、設定 key、frontmatter 欄位或 API。查不到官方說明者，一律明寫「官方文件未說明」或標示【⚠️ 文件不一致】。
3. 價格與方案以官方公告為準。 本手冊引述查證當日的方案結構與成本區間，但價格與額度會變動，任何商務決策請以 Anthropic 官方目前公告為準。
4. 範例架構是示意，不是任何一家公司的真實架構。 第 47 章 的金融業案例為教學用示意架構，不得解讀為任何特定銀行的實際系統設計。
5. 本手冊的建議不取代貴司的資安、法遵與稽核規範。 凡涉及 Production、個資、金融資料者，一律以貴司內規為準。

依角色的建議入口【建議】

整本手冊 56 章不需要每個人從頭讀到尾。依角色挑你的路徑：

目錄

📌 閱讀方式：目錄分為「部 → 章 → 節」三層，每一部都可以點選標題收合或展開，所有章節都可以直接點選跳到內文。第 53–56 章為補充章節，依主題分屬第二部與第三部，但實體位置在第 52 章之後。標示「（v1.1 新增）」「（v1.2 新增）」者為改版新增的內容。

前言：文件資訊、可信度標示制度（請務必先讀）、本手冊的引用與誠實原則、依角色的建議入口

第一部　概念與架構

這一部回答四個問題：Claude Code 到底是什麼、它在 2026 年變成了什麼樣子、它內部怎麼運作、以及它跟你可能已經在用的其他 AI 工具差在哪裡。

如果你只有 30 分鐘，讀第 1 章與第 2 章就夠了。

1. Claude Code 總覽與 Agentic Coding 核心觀念

1.1 Claude Code 是什麼【Official】

官方對 Claude Code 的定義是：一個會讀你的程式碼庫、修改檔案、執行指令，並與你的開發工具整合的 agentic coding tool，可在終端機、IDE、桌面應用程式與瀏覽器中執行。

這句話裡有三個關鍵詞，每一個都跟企業導入方式直接相關：

1.2 三個常見誤解【建議】

導入前先把這三個誤解講清楚，可以省掉後面 80% 的爭議。

誤解一：「Claude Code 是聊天機器人」

不是。聊天機器人的輸出是文字；Claude Code 的輸出是檔案系統的變更、執行過的指令、以及 git commit。它會在你不介入的情況下連續執行數十個動作。

誤解二：「Claude Code 是進階版的程式碼補全」

不是。程式碼補全（如傳統的 Copilot inline suggestion）只看得到目前檔案，你按 Tab 才生效。Claude Code 看得到整個專案 + git 狀態 + 指令輸出，而且它會自己決定要讀哪些檔案。

誤解三：「AI 會寫程式，所以工程師只要下指令就好」

也不是。這是本手冊最想扭轉的觀念。正確的模型是：

人負責 What / Why       →  需求、架構決策、驗收標準、風險判斷、最終責任
Agent 負責 How / Execution →  探索、實作、執行、驗證、修正

🚨 AI Agent 可以自主執行，不代表人類可以放棄架構決策、程式碼審查、資安審查與業務責任。

這句話是整本手冊的最高原則。第 52 章 會把它變成 15 條可稽核的公司標準。

1.3 什麼是 Agentic Coding【Official / 建議】

官方把 Claude Code 的運作描述為三個階段的循環：gather context（收集脈絡）→ take action（採取行動）→ verify results（驗證結果），並且反覆進行、隨時可被使用者打斷。

把它放進企業開發流程，完整的協作鏈是這樣：

flowchart TD
    H1["人：需求 / 驗收標準"] --> CC["Claude Code"]
    CC --> C1["理解脈絡<br/>CLAUDE.md · Memory · Skills · Repo"]
    C1 --> C2["規劃<br/>Plan Mode"]
    C2 --> C3["探索 Repository<br/>Grep / Glob / Read / LSP"]
    C3 --> C4["使用工具<br/>Edit · Bash · MCP"]
    C4 --> C5["執行測試 / Build"]
    C5 --> C6{"通過？"}
    C6 -- 否 --> C7["分析失敗 → 修正"]
    C7 --> C4
    C6 -- 是 --> C8["Git Commit / Branch"]
    C8 --> H2["人：Review Diff"]
    H2 --> H3{"接受？"}
    H3 -- 否 --> CC
    H3 -- 是 --> PR["Pull Request"]
    PR --> H4["人：Code Review + 資安審查"]
    H4 --> D["Merge / Deploy"]

📌 注意這張圖的兩個人類節點：Review Diff 與 Code Review + 資安審查。這兩個節點在本手冊中不可省略。省掉它們，你得到的不是效率，是無人驗證的技術債。

1.4 Claude Code 的核心能力【Official】

以下是官方文件明列、且與企業開發直接相關的能力：

1.5 適合與不適合的工作【建議】

這張表建議直接貼進團隊的 CLAUDE.md 或內部 Wiki。

1.6 本章實務案例

案例：某製造業 IT 部門的第一週試用

情境：一個 12 人的 Java/Vue 團隊拿到 Claude Code 試用，第一週有人「覺得很神」、有人「覺得沒用」。

觀察到的差異：

🎯 結論：Claude Code 的產出品質，主要由「你給它的脈絡」與「你給它的驗證方式」決定，而不是由模型決定。 這也是為什麼本手冊把第 27、28 兩章列為所有開發者必讀。

1.7 本章注意事項

⚠️ 不要用「取代多少人力」當導入目標。 這會直接導向錯誤的 KPI（見第 50.5 節）與錯誤的使用習慣（不 review、不驗證）。

✅ 建議的第一週目標：讓每位開發者完成一次「建立 CLAUDE.md → 用 plan mode 完成一個小任務 → 執行測試 → review diff → commit」的完整循環。

2. 2026 年重大變更與版本注意事項

📌 本章是「Version Note 的展開版」。若貴司內部已有 2026 年上半年寫的 Claude Code 教學或規範，請對照本章逐條檢查。

2.1 為什麼這一章必須存在【建議】

Claude Code 的版本號在 2026 年 9 月已經來到 2.1.2xx 區段，而且原生安裝會在背景自動更新。這代表：

1. 你今天寫的規範，可能兩週後就與實際行為不符。
2. 團隊中不同人可能跑在不同版本上，行為不一致。
3. 官方文件本身大量使用「Requires Claude Code vX.Y.Z or later」的措辭——這是官方承認行為會隨版本改變。

因此企業規範必須包含版本下限（見第 8.6 節）與升級前的 changelog 檢查（見第 50.3 節）。

2.2 權限模型的反轉【Official】

這是 2026 年影響最大的變更，值得單獨拉出來講。

2.2.1 現行的六種權限模式

⚠️ Version Note

manual 這個別名與 CLI 上顯示的 Manual 標籤需要 Claude Code v2.1.200 以上。設定檔中的設定值永遠是 default，hooks 與 SDK 整合也是用 default。

2.2.2 起始模式的決定順序

Claude Code 依下列順序決定新 session 的起始權限模式：

1. --permission-mode 旗標，或 --dangerously-skip-permissions
2. settings 檔中的 permissions.defaultMode
3. 內建預設

而「內建預設」本身又取決於方案與執行方式，第一個符合的列生效：

🎯 企業意涵：

• 如果貴司走 Enterprise 方案或 Bedrock/Vertex/Foundry，開發者的起始模式仍是 Manual，行為與 2025 年一致。
• 如果貴司走 Team 方案，開發者現在就是在 auto mode 下工作，除非你主動關掉。

2.2.3 auto mode 的分類器到底擋什麼【Official】

auto mode 不是「全部放行」。它是「由另一個模型逐一審查」。官方明列分類器預設阻擋的行為，以下節錄與企業最相關的部分：

• 下載並執行程式碼，例如 curl | bash
• 把敏感資料送到外部端點
• Production 部署與 migration
• 雲端儲存的大量刪除
• 授予 IAM 或 repo 權限
• 修改共用基礎設施
• 不可逆地銷毀 session 開始前就存在的檔案
• Force push
• 會把 secret 或敏感資料送出 repo 的 commit / push，或擴大部署曝光面的設定變更
• git reset --hard、git checkout -- .、git restore .、git clean -fd、git stash drop、git stash clear
• git commit --amend 針對非本 session 建立、或已 push 的 commit
• terraform destroy、pulumi destroy、cdk destroy、terragrunt destroy，以及會摧毀資源的 apply

v2.1.195 起再增加：寫入 secret manager、修改 DNS/TLS 憑證、合併未經人審的 PR、核准 Claude 自己的 PR、停用 CI 檢查、發出會觸發自動化的留言（如 atlantis apply）、切換 production feature flag、對受保護 IaC scope 套用變更、drain 並移除叢集節點、建立會在每個節點執行或攔截叢集流量的 K8s 資源（DaemonSet、admission webhook）、對敏感遠端目標開互動 shell 或 port-forward、開啟對外 tunnel 或 reverse shell、把活體憑證印進 transcript 或檔案、存取列為敏感資料位置的地方、繞過內部套件庫改用公開 registry、使用 --insecure 之類關閉安全防護的旗標。

🚨 v2.1.260 新增 Containment Escape 規則（本手冊 v1.1 補充）

這條規則專門針對容器／VM 逃逸的兩種手法：

1. 抓取雲端 metadata 端點的憑證（例如 AWS/GCP/Azure 的 instance metadata service）
2. egress 規避（繞過出口網路管控的行為）

這條規則與 autoMode.environment 的 Host containment context slot 直接連動（需 v2.1.257+）：在該欄位指明執行主機的身分之前，分類器會阻擋所有索取主機自身憑證的請求。

✅ 企業實務：若貴司在容器或 pod 中執行 Claude Code 且有 egress 允許清單，請在 Host containment 中明確寫出「允許的主機、cloud metadata 端點是否應該可達、以及該任務使用哪個 cloud project／cluster／registry 及以何種身分」。否則正當的雲端操作會被持續阻擋，而開發者往往會誤以為是 bug。

📌 v2.1.261 起，被拒絕時的訊息更有用：Claude 會收到被觸發的規則名稱以及更安全作法的建議，而不只是一句「被拒絕」。規則名稱以方括號呈現，例如 [Data Exfiltration]、[Production Deploy]、[Containment Escape]。

⚠️ 但要注意畫面上有兩處不會顯示完整指令或 URL：輸入框附近的提示（如 bash denied by auto mode · [Data Exfiltration] · /permissions）只給工具與原因；Recently denied 分頁則以 Claude 自己寫的描述列出 shell 指令。要以程式化方式取得被拒動作的確切輸入，必須加 PermissionDenied hook，它會在 tool_input 中收到原始內容。

🚨 關鍵限制：分類器只信任「session 啟動時就存在」的工作目錄與 git remote。

Session 進行中用 git remote add 或 git remote set-url 新增/改指的 remote 不被信任。這是刻意的防護：避免惡意內容在 session 中途把 push 目標換成攻擊者的 repo。

🚨 Version Note（v1.2 新增）：分類器預設改在「伺服器端」執行

v2.1.278 起，auto mode 的分類器審查預設由伺服器端執行：它是 session 模型請求的一部分，不另外收取分類器的額外費用。適用範圍：Enterprise 方案、Claude API 帳號、Claude Platform on AWS、Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry，以及任何把 ANTHROPIC_BASE_URL 指向 LLM gateway 或 proxy 的環境。

情境	行為
伺服器能審查	由伺服器的判定決定是否放行
伺服器無法審查（最常見的原因是 gateway 或 proxy 干擾了流量，或該平台、區域、憑證尚未支援）	退回 Claude Code 自己的分類器請求；若整個 session 都維持退回狀態，會在需計費的帳號上顯示分類器費用通知
CLAUDE_CODE_AUTO_MODE_SERVER=0	一律使用本機分類器請求（此時分類器的 token 會計入用量）
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 且未設定上一個變數	同樣不會請求伺服器審查

📌 v2.1.281 起，在伺服器端審查的環境中，唯讀指令與沙箱中的 shell 指令也要等審查結果，被標記時一樣會被阻擋。可以在 /status 的 Auto mode server 一列確認本 session 的分類器在哪裡執行。

✅ 企業意義：走 gateway 的組織要特別注意——gateway 若修改或過濾請求，可能讓伺服器端審查靜默失效並退回計費的本機分類器。上線前請在 /status 確認，並觀察是否出現分類器費用通知。

2.2.4 企業該怎麼做【建議】

2.3 其他重要變更速覽【Official】

2.3.1 v2.1.247 – v2.1.268 補充速覽【Official】（v1.1 新增）

本手冊 v1.0 的查證基準為 v2.1.267，v1.1 更新至 v2.1.268（2026-09-10）。下表整理這段期間與企業相關的變更：

✅ 企業最低版本建議（v1.1，⚠️ 已由 v1.2 的 2.3.2 節 取代為 2.1.281）：綜合 2.1.247（沙箱重新導向）、2.1.251（symlink TOCTOU）與 2.1.268（symlink 權限規則）三項安全修正，高度管制環境的 requiredMinimumVersion 應設為 2.1.268 或更高。設定方式見第 8.6 節。

2.3.2 v2.1.269 – v2.1.281 補充速覽【Official】（v1.2 新增）

本手冊 v1.2 的查證基準更新為 v2.1.281（2026-09-23）。下表只列與企業治理、安全、成本相關的項目，完整清單請見官方 changelog：

✅ 企業最低版本建議（v1.2 更新）：v2.1.269–281 之間有多項權限繞過與治理失效的修正（tee 寫入、symlink 寫入、NUL 規則、rm -rf "$(pwd)"、server-managed 與 MDM 並存時 MCP 政策被忽略）。高度管制環境的 requiredMinimumVersion 應提高到 2.1.281；混用 server-managed settings 與 MDM 的組織，至少要 2.1.273。

2.4 如何確認你自己的版本行為【Official】

# 查看版本
claude --version

# 完整設定與環境健檢（會顯示 managed settings 來源、搜尋工具、沙箱相依套件…）
claude doctor

在互動式 session 中：

/status

/status 的 Setting sources 一列會顯示 Enterprise managed settings 以及實際生效的來源標記，例如 (remote)、(file)、(drop-ins)、(HKLM)。這是驗證企業政策是否真的送達的唯一可靠方式。

2.5 本章實務案例

案例：政策佈署了，但完全沒生效

情境：某銀行資安部門把 managed-settings.json 用 SCCM 佈署到全體 Windows 開發機，內容包含 permissions.deny 的一長串禁止清單。兩週後稽核發現，開發者仍可執行被禁止的指令。

診斷過程：

1. 在開發機上執行 /status，Setting sources 一列沒有出現 Enterprise managed settings。
2. 檢查佈署腳本，發現目標路徑是 C:\ProgramData\ClaudeCode\managed-settings.json。
3. 對照官方文件：Windows 的正確路徑是 C:\Program Files\ClaudeCode\managed-settings.json，舊路徑已不再讀取。

修正後的驗證流程【建議】：

佈署政策
   ↓
在樣本機執行 /status，確認出現 Enterprise managed settings (file)
   ↓
在樣本機執行 claude doctor，確認無 schema 警告
   ↓
實際嘗試一個被 deny 的動作，確認被擋
   ↓
才視為佈署完成

🎯 結論：企業政策佈署必須有「驗證步驟」，不能只有「佈署步驟」。 沒有錯誤訊息不等於生效。

2.6 本章注意事項

🚨 不要在 .claude/settings.json（會進版控的專案設定）中嘗試設定 auto 或 bypassPermissions。 這兩個值在該層無效，而且不會報錯，只會讓你以為設好了。

⚠️ 每次 Claude Code 升級後，請重新執行一次 /status 與 claude doctor。 新版可能新增了會影響行為的內建預設。

✅ 把「檢查官方 changelog」納入季度維運工作：https://code.claude.com/docs/en/changelog 與 What’s New 週報。

3. 系統架構與 Agent Loop

3.1 整體架構圖【Official / 建議】

官方把 Claude Code 自我定位為 agentic harness：圍繞 Claude 模型，提供工具、context 管理與執行環境，把一個語言模型變成一個有能力的 coding agent。

下圖是本手冊整理的完整架構（結構依官方文件描述繪製）：

flowchart TD
    DEV["開發者<br/>Terminal · IDE · Desktop · Web · Slack"]
    DEV --> HARNESS

    subgraph HARNESS["Claude Code Harness（本機或雲端）"]
        LOOP["Agent Loop<br/>gather context → take action → verify results"]
        CTX["Context 組裝<br/>CLAUDE.md · Rules · Memory · Skills 描述 · MCP 工具名 · 對話歷史"]
        PERM["權限層<br/>Permission Rules → Permission Mode → Hooks"]
        TOOLS["工具層"]
        LOOP --- CTX
        LOOP --- PERM
        PERM --> TOOLS
    end

    HARNESS --> MODEL["Claude 模型<br/>Opus 5.5 / Sonnet 5 / Haiku 4.5 / Fable 5.1"]
    MODEL --> HARNESS

    TOOLS --> FS["檔案系統<br/>Read · Edit · Write · Glob · Grep"]
    TOOLS --> SH["Shell<br/>Bash / PowerShell（可經沙箱）"]
    TOOLS --> GIT["Git / GitHub / GitLab"]
    TOOLS --> WEB["Web<br/>WebSearch · WebFetch"]
    TOOLS --> LSP["Code Intelligence<br/>LSP（需 plugin）"]
    TOOLS --> MCP["MCP Servers<br/>Jira · DB · Slack · 內部 API"]
    TOOLS --> SUB["Subagents / Workflows"]

    HOOK["Hooks<br/>PreToolUse · PostToolUse · Stop …"] -.攔截.-> PERM
    SKILL["Skills<br/>.claude/skills/"] -.按需載入.-> CTX
    MEM["Auto Memory<br/>~/.claude/projects/.../memory/"] -.每次載入.-> CTX

3.2 Agent Loop 的三個階段【Official】

這三個階段會互相交錯，不是嚴格的三段式。官方舉的例子是「修好失敗的測試」：

1. 跑測試套件，看哪些失敗
2. 讀錯誤輸出
3. 搜尋相關原始碼
4. 讀那些檔案，理解程式碼
5. 編輯檔案修正問題
6. 再跑一次測試驗證

🎯 企業意涵：Loop 會不會收斂，取決於第 6 步有沒有一個「機器可讀的成功訊號」。 沒有測試、沒有 build exit code、沒有 lint，Claude 唯一能用的訊號就是「看起來做完了」，而你就變成了驗證迴圈的一部分。這是官方 best practices 的第一條，也是本手冊反覆強調的原則。

3.3 內建工具總覽【Official】

以下是官方 Tools reference 列出的工具（節錄企業最常遇到的）。「需要權限」欄位指的是在 Manual 模式下是否會跳出核准提示。

📌 Read、Grep、Glob 在 Manual 模式下不需核准，但僅限工作目錄與 additional directories 內。 工作目錄外的讀取仍會提示。這是官方所稱的「working directory boundary」。

3.4 Context 是怎麼組起來的【Official】

Claude 的 context window 裡有：對話歷史、檔案內容、指令輸出、CLAUDE.md、Auto Memory、已載入的 skills、系統指令。

各機制的載入時機與成本：

用 /context 指令可以看到目前 context 的組成；/context all 會顯示每個已載入的 MCP 工具佔多少 token。

3.5 Context 滿了會發生什麼【Official】

Claude Code 會自動管理：先清掉較舊的工具輸出，必要時再摘要對話。你的請求與關鍵程式碼片段會被保留，但對話早期的詳細指令可能遺失。

因此官方的建議非常明確：

把持續性規則寫進 CLAUDE.md，不要依賴對話歷史。

可控制的手段：

⚠️ Version Note

若單一檔案或工具輸出大到「每次摘要完 context 立刻又滿」，Claude Code 會在數次嘗試後停止自動壓縮並顯示 thrashing 錯誤，而不是無限迴圈。復原方式見第 49 章。

3.6 Session 是怎麼存的【Official】

• 對話以純文字 JSONL 存在 ~/.claude/projects/ 底下。
• Claude 修改檔案前會先快照該檔案，因此可以 Esc Esc 或 /rewind 回溯。
• Session 之間互相獨立，新 session 不會帶入舊對話；跨 session 的知識只能靠 CLAUDE.md 與 Auto Memory。
• claude --continue / claude --resume 沿用同一個 session ID 續寫；--fork-session 或 /branch 則複製歷史到新的 session ID。

3.7 權限層的位置【Official】

理解這張順序圖，是理解整個安全模型的關鍵：

flowchart LR
    A["Claude 想呼叫某個工具"] --> B{"permissions.deny<br/>命中？"}
    B -- 是 --> X["阻擋（任何模式都擋，含 bypassPermissions）"]
    B -- 否 --> C{"permissions.ask<br/>命中？"}
    C -- 是 --> P["一定跳出提示"]
    C -- 否 --> D{"PreToolUse hook"}
    D -- exit 2 / deny --> X
    D -- allow --> E["執行"]
    D -- 無意見 --> F{"權限模式"}
    F -- Manual --> P
    F -- auto --> G["分類器審查"]
    F -- acceptEdits --> H{"是編輯或常見 fs 指令？"}
    F -- dontAsk --> I{"在 allow 清單？"}
    F -- bypassPermissions --> E
    G -- 通過 --> E
    G -- 阻擋 --> X
    H -- 是 --> E
    H -- 否 --> P
    I -- 是 --> E
    I -- 否 --> X
    E --> S{"沙箱啟用？"}
    S -- 是 --> T["OS 層檔案/網路邊界"]
    S -- 否 --> U["直接以你的身分執行"]

三個必須記住的規則：

1. deny 規則在所有模式都有效，包含 bypassPermissions。 這是唯一的絕對邊界。
2. allow 規則在 bypassPermissions 模式下無效（因為全部都放行了）。
3. 權限模式決定「要不要問」，沙箱決定「跑起來能碰到什麼」。 兩者互補，缺一不可。

3.8 本章實務案例

案例：為什麼 Agent 一直重複讀同一批檔案？

情境：某團隊反映 Claude Code 在大型 monorepo 中「一直讀檔、很慢、又貴」。

診斷：

1. 執行 /context，發現 CLAUDE.md 佔了 12,000 token（超過 800 行，涵蓋了所有 8 個 package 的規範）。
2. 沒有安裝 code intelligence plugin，Claude 只能用 Grep 逐檔尋找符號定義。
3. 沒有 Read deny 規則，dist/、build/、vendored SDK 全部可讀。

處置（對應第 13 章與 monorepo 章節）：

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

加上：把 800 行 CLAUDE.md 拆成「根目錄 60 行通則」＋「每個 package 各自的 CLAUDE.md」，並安裝 TypeScript 的 code intelligence plugin。

結果：起始 context 佔用下降、符號查找從「grep + 讀多個候選檔」變成一次 LSP 呼叫。

3.9 本章注意事項

📌 /context 是排查效能與成本問題的第一個指令，不是最後一個。 遇到「慢、貴、答非所問」，先看 context 組成。

⚠️ Checkpoint 只涵蓋 Claude 用檔案編輯工具做的變更。 透過 Bash 指令（rm、mv、cp）造成的變更無法用 /rewind 還原，subagent 的編輯多數情況下也不會被還原。checkpoint 不是 git 的替代品。

4. 與其他 AI Coding Agent 的能力比較

⚠️ 本章的 Claude Code 欄位為【Official】（2026-09-10 查證）；GitHub Copilot 欄位依本文件庫中同日查證的《GitHub Copilot 企業級軟體開發教學手冊》整理；OpenAI Codex CLI 與 Cursor 欄位標示為【Community】，因為本手冊未對其官方文件做同等強度的查證。做採購決策時請自行向各廠商官方文件覆核。

4.1 定位差異：一句話版本【建議】

4.2 Claude Code 與 Claude Chat 的差異【Official】

這是新手最常混淆的一組，先講清楚：

🎯 結論：兩者的資安評估必須分開做。 把 Claude Chat 的評估結論直接套到 Claude Code 是嚴重的治理錯誤。

4.3 能力矩陣

4.4 選型決策矩陣【建議】

不要問「哪個最好」，要問「哪個符合你的約束」。

4.5 一個常被忽略的落差：Provider 會影響功能可用性【Official】

這是 Claude Code 特有、且對企業採購影響很大的一點：你選的 Provider 會決定哪些功能可用。

🎯 企業意涵：如果你為了資料落地而選擇 Bedrock/Vertex/Foundry，就必須接受雲端 session、排程 routines、託管 PR 審查、Remote Control 等功能不可用。若團隊同時需要這些功能，官方的建議是「規劃開發者是否也需要 Claude for Teams / Enterprise 座位」。這是雙軌成本，必須在採購階段就算進去。

4.6 本章實務案例

案例：一場沒有結論的選型會議

情境：某企業架構委員會花了三次會議比較 Claude Code 與 Copilot，始終沒有結論，因為雙方各自舉出對方沒有的功能。

轉折：改變提問方式，從「哪個功能多」改為回答四個約束問題：

1. 我們的程式碼可以離開自有網路嗎？（答：可以，但需 SOC 2 與 30 天保留上限）
2. 我們的 CI 在哪裡？（答：GitLab 自建，不是 GitHub）
3. 我們的主力 IDE 是什麼？（答：IntelliJ IDEA）
4. 我們最痛的是什麼？（答：20 年的 Legacy Java 系統沒有文件）

結論：因為 CI 在 GitLab、主力是 JetBrains、最痛的是 Legacy 逆向工程（需要長時間、大量讀檔、可平行化的 agent），最後採用 Claude Code 作為主力，並保留少數 Copilot 座位給有 GitHub 需求的專案。

🎯 結論：選型應該從「約束」出發，不是從「功能表」出發。

4.7 本章注意事項

⚠️ 本章的比較表有保鮮期。 四個產品都在高速迭代，任何超過三個月的比較表都應視為過期。做正式採購決策時，請以各家官方文件的當日狀態重新覆核。

📌 不要為了「功能齊全」而同時導入多套 agent。 每一套都需要獨立的權限治理、稽核、教育訓練與 MCP 審核流程。治理成本是線性疊加的，效益不是。

第二部　授權、部署與企業治理

這一部是給管理員、架構師與資安看的。開發者可以先跳到第三部，但 Tech Lead 至少要讀第 8 章。

5. 方案、模型選擇與成本模型

5.1 方案總覽【Official】

Claude Code 可透過以下任一途徑取得存取：

個人方案為 Free / Pro / Max；組織方案為 Team / Enterprise。

🚨 採購前必讀：部分 Claude Code 功能需要 claude.ai 帳號，無法只靠 Console API key 或雲端供應商憑證使用，包含 Claude Code on the web、Routines、Code Review、Remote Control、Chrome 擴充。若貴司決定走 Bedrock / Vertex / Foundry，必須另外規劃開發者是否也需要 Teams / Enterprise 座位。詳見第 4.5 節。

5.2 模型與別名【Official】

/model 或 --model 接受下列別名：

各 Provider 上 opus / sonnet 實際解析到的版本不同：

default 依帳號類型解析的結果（v2.1.280 起）：

🚨 Version Note（v1.2 新增）：Pro 與 Team Standard 的預設模型已由 Sonnet 改為 Opus

• v2.1.280 之前：Pro 與 Team Standard 預設 Sonnet 5；Max、Team Premium、Enterprise 與 API 預設 Opus 5。
• v2.1.280（2026-09-22）起：所有訂閱方案與 API 一律預設 Opus 5.5（claude-opus-5-5，1M context，每百萬 token 輸入 $4、輸出 $20，cache 讀取 $0.20）。

對企業的影響：在管理員沒有任何動作的情況下，Team Standard 座位的每 token 成本與額度消耗輪廓會改變。若預算以 Sonnet 估算，請改用 managed settings 的 model 或組織預設模型（Enterprise）明確指定。Opus 5.5 需要 Claude Code v2.1.280 以上；Opus 5 需要 v2.1.219 以上；Sonnet 5 需要 v2.1.197 以上。

⚠️ 這張表是很多「同一個 prompt 在不同環境結果不同」問題的根因。 企業若同時有多個 Provider，請在 CLAUDE.md 或內部規範中明確指定完整 model ID（例如 claude-opus-5-5），或設定 ANTHROPIC_DEFAULT_OPUS_MODEL／ANTHROPIC_DEFAULT_SONNET_MODEL 釘選版本，不要只寫別名。📌 ANTHROPIC_BASE_URL 只改變請求送往哪裡，不改變由哪個模型回答。

5.3 模型設定的優先順序【Official】

1. /model <alias|name>        （session 中切換）
2. claude --model <alias|name>（啟動時）
3. ANTHROPIC_MODEL 環境變數
4. settings 檔的 "model"
5. ANTHROPIC_DEFAULT_MODEL   （新 session 的預設，v2.1.236+）

補充規則：

• /model 在 picker 按 Enter 會寫入 ~/.claude/settings.json 的 model 成為預設；按 s 只套用本 session。
• -p 模式中的 /model 只影響當次 session，不會存成預設。
• 組織預設模型（Enterprise，claude.ai 管理後台設定，可依自訂角色）只是起點，會被 --model、ANTHROPIC_MODEL、managed settings 與使用者的 model 蓋過；管理員若開啟「覆寫使用者選擇」，則使用者層的 model 只在當次 session 有效。組織預設模型只作用於 Anthropic API 認證的 session，走 LLM Gateway 或第三方 Provider 時請改用 managed settings 的 model。
• 新 session「換回別的模型」的常見原因：只選了本 session（s）、被更高優先權覆寫（啟動畫面會列出是哪個設定檔）、~/.claude/settings.json 無法寫入、或使用 --resume 沿用了舊 session 的模型。

5.4 Effort Level（推理投入程度）【Official】

各模型支援的等級不同：

設定方式：/effort、--effort <level>、CLAUDE_CODE_EFFORT_LEVEL、settings 的 effortLevel，以及依模型分開儲存的 modelSettings。

解析順序（ultracode 關閉時，取第一個成立者）：

1. 明確選擇：CLAUDE_CODE_EFFORT_LEVEL、--effort、session 中的 /effort
2. 設定：modelSettings 中該模型的等級，或 effortLevel 鍵
3. 模型自身的預設（見上表）；Enterprise 若為組織預設模型設了預設 effort，則以其為準

⚠️ Version Note（v1.2 新增）：舊的 effortLevel 對 Opus 5.5 不生效

/effort 自 v2.1.280 起依模型分開儲存（寫在使用者設定的 modelSettings）。使用者設定檔中頂層的 effortLevel（舊格式）仍套用在 Opus 5、Fable 5.1 等舊模型上，但對 Opus 5.5 與之後的新模型不生效——它們會從自己的預設（Opus 5.5 為 medium）開始。

反之，project、local、managed settings 或 --settings 中的頂層 effortLevel 仍然套用到所有模型。企業若想讓 Opus 5.5 以 high 運行，請寫在 managed settings，而不是要求開發者個人設定。

另外，Opus 5.5 與 Fable 無法關閉 thinking：session 開關、alwaysThinkingEnabled 與 MAX_THINKING_TOKENS=0 對它們都沒有作用，由模型依 effort 自行決定每一步的思考量。

企業上限有兩種，同時存在時取較低者：

5.5 企業模型治理【Official】

在 managed settings 中：

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true,
  "maxEffortLevel": "high"
}

• availableModels 可比對模型家族（sonnet）、版本前綴（claude-sonnet-4-5）或完整 ID。
• 它會套用在 /model、--model、ANTHROPIC_MODEL、settings 的 model 以及各種別名上。
• 加上 enforceAvailableModels: true 後，連「Default」選項也會被限制在白名單內。
• modelOverrides 可把模型 ID 映射到你的 Provider ID（例如 Bedrock 的 ARN）。

若貴司走 claude.ai 或 Anthropic API 且為 Enterprise 方案，另有伺服器端的組織層控制（不需佈署任何檔案）：組織模型限制、組織預設模型、組織 effort 上限。但這些控制不會套用到 Bedrock / Vertex / Foundry / Claude Platform on AWS——在那些 Provider 上一律改用 managed settings。

5.6 成本模型與實測區間【Official】

官方公布的企業部署平均值：

• 每位開發者、每個活躍日約 $13 美元
• 每位開發者每月約 $150–250 美元
• 90% 的使用者維持在每活躍日 $30 美元以下

📌 這是 API token 計價下的觀察值。訂閱制方案（Pro / Max / Team / Enterprise）的用量包含在座位費中，超出後才走 usage credits。

5.7 查看與控管成本【Official】

✅ 建議：企業導入時先開 OpenTelemetry，再談 KPI。沒有資料就談成效是空談。設定方式見第 41 章。

5.8 Console（API）組織的速率限制建議值【Official】

若走 Claude Console，官方給出的每人 TPM / RPM 建議：

📌 人數越多每人 TPM 越低，是因為大型組織同時使用的比例較低。這些限制作用在組織層，不是每人硬性上限。

5.9 降低 Token 用量的十個做法【Official / 建議】

1. 任務之間 /clear——最高投報率的一招。
2. 選對模型：Sonnet 應付多數 coding 任務；Opus 留給複雜架構決策。簡單的 subagent 任務指定 model: haiku。
3. 降低 effort：不需要深度推理的任務用 /effort low 或 medium。
4. CLAUDE.md 控制在 200 行以內，把專門知識移到 skills（按需載入）。
5. 優先用 CLI 工具而非 MCP（gh、aws、gcloud），因為不會有 per-tool listing 成本。
6. 關掉沒在用的 MCP server（/mcp）。
7. 安裝 code intelligence plugin：一次「跳到定義」取代 grep + 讀多個候選檔。
8. 用 hook 預處理大量輸出：例如 PreToolUse hook 把測試輸出過濾成只剩失敗行，可把數萬 token 降到數百。
9. 把冗長操作丟給 subagent：詳細輸出留在 subagent 的 context，只有摘要回到主對話。
10. 寫具體的 prompt：「improve this codebase」會觸發全面掃描；「add input validation to the login function in auth.ts」只讀必要的檔案。

5.10 長 session 用量爆增的原因【Official】

這是企業最常被問的成本問題。官方明列的原因：

🚨 Agent Teams 在 teammate 都跑 plan mode 時，token 用量約為單一 session 的 7 倍。 這個數字請直接寫進團隊規範。

5.11 Fast Mode（高速模式）【Preview】

⚠️ 官方標示為 research preview。 功能、定價與可用性都可能依回饋變更。不要把它寫進生產流程的關鍵路徑，也不要把本節的價格數字寫死進預算模型。

5.11.1 Fast Mode 是什麼（以及不是什麼）【Official】

Fast Mode 不是另一個模型。它是 Claude Opus 的另一組 API 配置，以成本換延遲：同樣的模型品質與能力，回應速度最高快 2.5 倍，但每 token 單價更高。

⚠️ Version Note：Opus 4.7 的 Fast Mode 已被移除

Opus 4.7 的 fast mode 於 2026-06-25 棄用、2026-07-24 移除。現在切換到 Opus 4.7 會直接關閉 fast mode（v2.1.221 之前的版本不會關，導致 API 直接拒絕請求）。

Fast mode 的預設模型換過三次：v2.1.142–2.1.153 為 Opus 4.7、v2.1.154–2.1.218 為 Opus 4.8、v2.1.219–2.1.279 為 Opus 5、v2.1.280 起為 Opus 5.5（v1.2 更新）。

💰 v1.2 成本提醒：Opus 5.5 的 fast mode 單價（$8／$40）低於 Opus 5（$10／$50）。若貴司預算模型以 v1.1 的 $10／$50 估算，升級到 v2.1.280 之後，同樣用量的 fast mode 花費約會下降 20%；但請記得「開啟時點決定一次性成本」的陷阱（5.11.3）不變。

5.11.2 🚨 企業最該先知道的三件事【Official】

🚨 第一：Fast Mode 只從 usage credits 扣款，不計入訂閱方案的額度。

在 Pro / Max / Team / Enterprise 訂閱方案上，即使你的方案額度還沒用完，fast mode 仍直接從 usage credits 扣。帳戶必須先開啟 usage credits（允許超出方案額度計費），否則 /fast 只會顯示 Fast mode requires usage credits · /usage-credits to turn them on。

這代表 fast mode 是一條繞過訂閱額度的獨立支出路徑。若貴司的 AI 成本控管只盯訂閱方案額度，這筆錢不會出現在你監看的地方。

🚨 第二：Team / Enterprise 預設關閉，必須由 Owner 主動開啟。

這其實是好消息——預設是安全的。開啟位置依產品而異：

組織型態	開啟位置
Claude AI（Team / Enterprise）	Owner 於 Admin Settings → Claude Code 開啟
Claude Console（API 客戶）	管理員於 Claude Code preferences 開啟；且因仍為 research preview，組織還必須另外被佈建 fast mode 存取權

Console 組織若未取得佈建，API 會以 429 拒絕每一個 fast mode 請求，而 Claude Code 會把它當成 fast mode 速率限制處理——但與真正的速率限制不同，這種拒絕不會有冷卻後自動恢復，會一直持續到存取權被佈建為止。

🚨 第三：四大雲端 Provider 完全不支援。

Fast mode 不適用於 Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry、Claude Platform on AWS。僅 Anthropic Console API 與 Claude 訂閱方案可用。

若貴司走 Bedrock / Vertex / Foundry 部署，本節對你完全不適用，也不需要納入成本模型。詳見第 54 章。

5.11.3 成本陷阱：什麼時候開啟決定你付多少【Official】

這是 fast mode 最容易讓帳單失控、也最少人知道的機制：

🚨 第一次在一段對話中啟用 fast mode 時，你要為「整段既有對話 context」付 fast mode 的完整未快取輸入價。

也就是說：對話進行得越深，開 fast mode 的一次性成本越高。

• ✅ 正確做法：需要 fast mode 就在 session 一開始就開。
• ❌ 錯誤做法：跟 Claude 來回了 50 輪、context 累積到 300K token 之後才想「這段來加速一下」——這一下就是 300K token 以 fast mode 未快取價（Opus 5.5 為 $8/MTok、Opus 5 為 $10/MTok）重算。

📌 這筆費用每段對話只收一次。開了之後再關掉、稍後又開，不會重複收取。

5.11.4 Fast Mode 與 Effort Level 的差異【Official】

兩者都影響速度，但機制完全不同，可以疊加使用：

✅ 單純任務要最快：fast mode + 較低 effort level。

5.11.5 何時該用、何時不該用【Official / 建議】

🎯 判準一句話：有人正盯著螢幕等才值得開 fast mode；無人值守的自動化一律不要開。

5.11.6 企業成本管控：fastModePerSessionOptIn【Official】

預設行為是：使用者在互動式 session 開啟的 fast mode 會跨 session 持續生效。對於習慣同時開多個 session 的工程師，這會讓成本悄悄放大。

企業可強制「每個 session 都必須重新手動開啟」：

{
  "fastModePerSessionOptIn": true
}

• 可放在任何設定檔；Team / Enterprise 的 Owner 可透過 server-managed settings 推送至全組織。
• 設定後每個 session 都以 fast mode 關閉啟動，使用者需明確執行 /fast。
• 使用者的偏好仍會被保存，移除此設定即恢復原本的持續行為。
• 📌 設定此項後，切換模型回到支援 fast mode 的 Opus 也不會自動重新開啟 fast mode。

另一個「完全停用」的選項是環境變數 CLAUDE_CODE_DISABLE_FAST_MODE=1。

5.11.7 各方案的花費檢視位置【Official】

先執行 /status 確認登入方式：顯示 Login method（如 Claude Max account）代表訂閱制；顯示 API key 代表計費到 Console 組織。

5.11.8 🚨 Gateway / Proxy 環境下的可用性檢查陷阱【Official】

這是企業網路環境最容易誤判的一節。

Claude Code 在提供 fast mode 之前，會先發一個請求直接到 api.anthropic.com 檢查組織的 fast mode 可用性。這個檢查不走 ANTHROPIC_BASE_URL。

🚨 後果：一個把所有 Claude 流量導向 LLM Gateway、並封鎖對 api.anthropic.com 直接 egress 的企業網路，推論請求正常運作，但 fast mode 可用性檢查會失敗——即使組織確實已啟用 fast mode，/fast 仍會回報 Fast mode unavailable due to network connectivity issues，請求以標準速度執行。

📌 這個檢查會使用已設定的 HTTP proxy，所以只有在「連 proxy 都到不了 api.anthropic.com」時才會失敗。且成功過的檢查會被快取並持續生效，因此這個問題主要衝擊新安裝的機器。

故障樣態與對應解法：

⚠️ 這兩個變數只影響用戶端檢查。若組織確實停用了 fast mode，API 端仍會拒絕請求，設不設都一樣。

5.11.9 速率限制與額度耗盡的行為【Official】

Fast mode 有獨立於標準 Opus 的速率限制，且所有支援的 Opus 模型共用同一個 fast mode 限制池。

觸及速率限制時：自動退回標準速度 → ↯ 圖示轉灰表示冷卻中 → 以標準速度與價格繼續工作 → 冷卻結束後自動恢復 fast mode。

usage credits 中途用盡時行為不同（無冷卻，每個被拒請求改以標準速度與價格重試，工作不中斷）：

5.11.10 非互動模式的限制【Official】

在 -p 非互動模式下，/fast 只在 session 啟動時就以 --settings 帶入 fast mode 的情況下有效：

claude -p --settings '{"fastMode": true}' "..."

此時切換僅套用於該 session，不會存成預設值。在其他任何非互動 session 中，/fast 會回報 fast mode 不可用。

5.12 Advisor Tool（顧問模型）【Preview】

⚠️ 官方標示為 experimental，且僅限 Anthropic API。 行為、定價與可用性均可能變更。

5.12.1 Advisor 是什麼【Official】

Advisor 讓 Claude 在任務的關鍵決策點去諮詢第二個、通常更強的模型：例如確定作法之前、反覆卡在同一個錯誤時、以及宣告任務完成之前。

顧問模型會收到完整對話（包含每一次工具呼叫與結果），回傳指引後由 Claude 套用再繼續。

5.12.2 三種啟用方式【Official】

/advisor 在無終端機選單的環境同樣可用（-p 非互動模式、Agent SDK、桌面 App、Remote Control），需 v2.1.260+：無參數印出目前顧問模型與可接受的別名、帶模型即設定、/advisor off 關閉。

5.12.3 🚨 主模型與顧問模型的配對矩陣【Official】

顧問模型的能力必須不低於主模型，否則不會被掛上。這張表是本節最容易踩雷的地方：

• 別名 fable / opus / sonnet 解析為 Claude Code 內建的各家族預設版本，會隨 Claude Code 改版而前進；也可直接給完整 model ID（如 claude-opus-5-5）。
• 📌 v2.1.276 修正：ANTHROPIC_BASE_URL 指向 proxy／gateway 時，所有請求因 Input tag 'advisor_20260301' 而 400 失敗的迴歸問題；v2.1.280 起，不支援 advisor 的 gateway 會自動改以不帶 advisor 的請求重試。
• Subagent 會繼承所設定的顧問，並以自己的模型再跑一次配對檢查。
• 配對不合時：顧問不會掛到主模型請求上（/advisor 輸出與通知會顯示），但自身模型符合配對的 subagent 仍可能使用顧問。
• Fable 5.1 需 v2.1.257+，且兩個 Fable 模型都需要 Fable 存取權。

5.12.4 企業治理的四個交互作用【Official】

🚨 與 availableModels 允許清單的交互作用

Claude Code 不會呼叫被組織 availableModels 允許清單排除的已存顧問模型。但它仍會把該顧問存起來——一旦使用者之後切換到相容的主模型，它就會生效。企業稽核時請注意：設定檔裡存在的 advisorModel 不等於它現在正在運作。

🚨 與 DISABLE_TELEMETRY 的衝突

Advisor 是透過 Claude Code 向 Anthropic 抓取 feature flag 來開啟的。在有設定會關閉 flag 抓取的變數（例如 DISABLE_TELEMETRY）的 session 中，advisor 會保持關閉。

這對「以停用遙測作為資安基線」的企業而言，等於 advisor 技術上無法使用——這不是 bug，請不要花時間排查。

🚨 Provider 限制

Advisor 是 server-executed tool，不適用於 Amazon Bedrock、Claude Platform on AWS、Google Cloud’s Agent Platform、Microsoft Foundry。透過設了 ANTHROPIC_BASE_URL 的 LLM Gateway 時，能否使用取決於該 gateway 是否原封不動地把請求轉發到 Anthropic API。詳見第 53 章。

⚠️ 完全停用

設 CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1：/advisor 指令變為不可用、任何已設定的 advisorModel 被忽略、--advisor 旗標雖被接受但無作用。

5.12.5 成本模型【Official】

每次呼叫顧問，顧問模型都要讀完整段對話，因此會以顧問模型的費率額外消耗 token。

✅ 由於 Claude 只在決策點呼叫顧問而非每一輪，「較快的主模型 + 較強的顧問」通常比全程使用較強模型更便宜。顧問用量會計入 /usage 顯示的 session 總計。

對 prompt cache 的影響（與切換模型不同）：

• ✅ session 中途開關 advisor 不會使主模型的 prompt cache 失效——這點與切換模型不同。顧問回傳的指引會在後續輪次中作為 transcript 的一部分被快取。
• ⚠️ 但顧問自己讀取對話的部分不被快取：每次顧問呼叫都重新處理完整 transcript，呼叫之間無法重用。

5.12.6 常見配對與取捨【Official / 建議】

5.12.7 session 中看得到什麼【Official】

呼叫顧問時 transcript 顯示 Advising 與顧問模型名稱；回傳後：

📌 Claude 通常會遵循顧問指引，但當自身證據與之矛盾時會調整（例如建議的步驟實測失敗、或檔案內容與建議相牴觸），此時 Claude 會把衝突點呈現出來，而非無條件照做。

5.12.8 與相近機制的選擇【Official】

🎯 Advisor 適合：多步驟長任務中，多數輪次是例行工作、但計畫品質決定成敗者（大型重構、反覆出現同一錯誤的除錯、需要被獨立檢查才敢宣告完成的任務）。不適合：短任務（沒什麼好規劃），或每一輪都需要最強模型的工作——後者請直接換主模型。

5.13 🚨 Automatic Model Fallback（內容觸發的自動換模型）【Official】（v1.1 新增）

🚨 這一節對資安團隊（滲透測試、CTF、紅隊）與生技領域的讀者是必讀項，而且很可能是整章最會讓你意外的機制。

5.13.1 機制：不是拒絕，而是換一個模型重跑【Official】

Automatic model fallback 是一種基於內容的安全機制：當安全分類器標記某個請求時，Fable 模型、Opus 5.5 與 Opus 5 會改用備援模型重跑該請求，而不是直接拒絕。

📌 這與「模型過載或不可用時的可用性 fallback」是完全不同的兩件事，不要混淆。

會觸發分類器的模型：Fable 5.1、Fable 5、Opus 5.5（v1.2 新增）、Opus 5（其他模型不帶此分類器）。

🚨 v1.2 重要影響：v2.1.280 起 Opus 5.5 是所有訂閱方案的預設模型，而它也帶有這組分類器。這代表過去只在少數人選用 Fable 時才會遇到的 fallback，現在會出現在每個使用預設模型的開發者身上，資安團隊尤其明顯。

最常觸發的內容類別：資安（cybersecurity）與生物（biology）。

預設行為是自動且可見：Claude Code 重跑請求並在 transcript 中顯示提示。fallback 之後 session 會繼續留在備援模型上，要換回原本的模型需執行 /model。

5.13.2 🚨 為什麼資安工作會「第一個請求就被換掉」【Official】

🚨 官方明言：攻擊性資安或生物領域的工作負載——包含滲透測試、CTF 演練、與生物相鄰的程式碼庫——會頻繁觸發 fallback，且往往在第一個請求就發生。

原因是：第一個請求就帶著工作區脈絡（CLAUDE.md、git status）。 一個內含資安或生物素材的 repository 光是被開啟就足以觸發分類器——使用者根本還沒送出任何不尋常的內容。

🎯 對企業的三個實際後果：

1. 貴司的資安工具 repo，開啟即可能自動降級模型。 若團隊規範寫「一律使用 Opus 5.5（預設）」，實際執行的可能是 Opus 4.8，而多數人不會注意到 transcript 裡的那行提示。
2. Fable 或 Opus 5.5 做生物相關工作只有一次機會：第一次被標記後 session 移到 Opus 5，之後再被標記的生物請求會在那裡以拒絕收場。
3. 需要 Fable 級能力做這類工作的組織，官方建議的路徑是向 Anthropic 客戶團隊詢問 trusted access 方案，而不是嘗試繞過分類器。

診斷方法：要確認是否為自家客製化內容（CLAUDE.md、skill、MCP、hook）造成觸發：

claude --safe-mode      # 停用客製化內容

⚠️ 但要注意：git status 與目錄名稱不算客製化，仍會被納入。因此一個叫 pentest-tools 的目錄，即使 --safe-mode 也可能觸發。

5.13.3 🚨 非互動模式與 SDK：直接拒絕，不是切換【Official】

🚨 在 -p 非互動模式與 Agent SDK 中，Claude Code 從不顯示同意提示，被標記的請求會直接以拒絕結束該輪。

這對 CI/CD 的影響是決定性的：一條在互動式終端機測試正常（自動切到 Opus 4.8 後完成）的資安掃描流程，搬到 CI 以 -p 執行時會直接失敗，而失敗原因不會是任何明顯的錯誤碼。

✅ 對策：CI 中處理資安相關程式碼時，直接指定一個不帶此分類器的模型（例如明確使用 Opus 4.8 或 Sonnet），不要依賴 fallback。

5.13.4 關掉自動切換，改為每次詢問【Official】

{
  "switchModelsOnFlag": false
}

或執行 /config 關閉 Switch models when a message is flagged。

停用後，被標記的請求會暫停 session 並給你兩個選項：切換到備援模型，或編輯 prompt 後在目前模型上重試。

✅ 企業建議：對於「模型一致性會影響稽核結果」的場景（例如以 AI 產出物作為交付憑證），應設為 false，讓模型切換成為一個明確的人為決定，而非靜默發生。

不會顯示提示的三種情況（一律直接以拒絕結束）：

📌 行動版 Claude Code on the web 不支援「編輯後重試」，只能切換模型或改用桌面瀏覽器／桌面 App。

5.13.5 第三方 Provider 上需要額外設定【Official】

在 Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry 上，自動 fallback 需要能同時辨識出兩個模型才會運作：

• Fable 5.1 / Fable 5 的辨識條件：model ID 含 claude-fable-5、符合 ANTHROPIC_DEFAULT_FABLE_MODEL 的值，或以 modelOverrides 對應。
• Opus 5 以其 provider model ID 或 modelOverrides 對應辨識。

要讓 fallback 生效，需設定備援目標：

export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'

⚠️ 未設定時，這些 provider 上的 fallback 不會發生——被標記的請求直接失敗。這是 Bedrock／Vertex／Foundry 部署的企業必須納入部署檢核表的一項。

5.13.6 Fable 的存取與 usage credits 同意流程【Official】

Fable 在任何方案或 provider 上都不是帳戶預設模型，必須明確選擇：

/model fable                      # Fable 5.1
claude --model fable
/model claude-fable-5             # Fable 5（Anthropic API）

📌 在 Anthropic API 上，/model 選單只在伺服器回報該模型對你的組織可用之後才會列出 Fable；但直接輸入 /model fable 或完整 model ID 時，Claude Code 會直接向伺服器查詢可用性，因此選單沒列出時，手動輸入仍可能成功。

usage credits 同意：當 Fable 用量計費到 usage credits 時，/model 選單的 Fable 列會顯示 Requires usage credits。

🚨 企業成本治理重點：最後一列意味著自動化流程可以在無人同意的情況下持續消耗 usage credits。若貴司有排程的 headless 任務且模型可能解析到 Fable，請在 managed settings 以 availableModels 明確約束，不要依賴同意提示作為成本閘門。

5.14 本章實務案例

案例：一張看不懂的帳單

情境：某新創導入 Claude Code 一個月後，帳單比預估高 3 倍。

診斷（用 /usage 的 breakdown + OpenTelemetry）：

處置：

// ~/.claude/settings.json（團隊建議值）
{
  "model": "sonnet",
  "effortLevel": "high",
  "autoCompactWindow": "500k"
}

加上團隊規範：任務切換必 /clear、/loop 間隔不得低於 20 分鐘且必須有終止條件、每季檢視 MCP server 清單。

結果：次月成本回到預估值的 1.1 倍。

5.15 本章注意事項

⚠️ 不要用「產生的程式碼行數」當成本效益指標。 它會鼓勵冗長的程式碼。正確的 KPI 見第 50.5 節。

📌 /usage 的金額是本機以列表價估算的，不是帳單。 若貴司有合約折扣，請由管理員在 managed settings 設定 modelPricing，讓開發者看到的數字與帳單一致。

✅ 先做小規模試點（5–10 人、2 週）建立基準線，再擴大。 官方也是這樣建議的。

6. 執行環境（Surface）全比較

6.1 六個 Surface 一覽【Official】

同一個引擎跑在不同介面上，你的 CLAUDE.md、settings 與 MCP server 在各介面之間共用（本機類介面）。

📌 Agent SDK 與腳本化是 CLI 專屬。 這是選擇主力介面時最實際的差異。

6.2 決策矩陣【建議】

6.3 VS Code 擴充【Official】

• 需求：VS Code 1.94.0 以上；任一付費 Claude 訂閱或 Claude Console 帳號（不需 API key）。
• 安裝：Extensions 搜尋 “Claude Code”，或 vscode:extension/anthropic.claude-code；Cursor 用 cursor:extension/anthropic.claude-code。
• 安裝後：Command Palette → 輸入 “Claude Code” → 選 Open in New Tab。
• 特色：可在接受前審查與編輯 Claude 的計畫、自動接受編輯、以 @ 帶入含行號範圍的選取內容、對話歷史、多分頁／多視窗。

⚠️ VS Code 擴充的起始權限模式判定規則與終端機不同。 擴充不讀專案設定來決定起始權限模式；且在 feature flag 抓取關閉時，擴充會忽略所有 settings 檔。企業若要控制 IDE 內的起始模式，請以 managed settings 為準並實測。

6.4 JetBrains Plugin【Official】

• 支援：IntelliJ IDEA、PyCharm、Android Studio、WebStorm、PhpStorm、GoLand。
• plugin 不內含 CLI：它是在 IDE 的整合終端機執行 claude 指令再連上去。所以必須先安裝 CLI。
• 快捷鍵：Cmd+Esc（Mac）/ Ctrl+Esc（Win/Linux）啟動；Cmd+Option+K / Alt+Ctrl+K 插入檔案引用（如 @src/auth.ts#L1-99）。
• 從外部終端機連線：在 session 中執行 /ide。
• 設定路徑：Settings → Tools → Claude Code [Beta]，可指定 Claude 指令路徑。

WSL 使用者的建議設定值：

wsl -d Ubuntu -- bash -lic "claude"

🚨 JetBrains 的資安提醒（官方明列）：在 acceptEdits 模式下，Claude Code 可能修改會被 IDE 自動執行的 IDE 設定檔，這會提高風險並可能繞過 bash 執行的權限提示。官方建議在 JetBrains 中使用 Manual 模式。

⚠️ JetBrains 內建的 IDE MCP server 使用未加密的 ws://。 在 loopback 上不是問題，但若開啟「Accept connections from all network interfaces」，session 流量與認證 token 會以明文跨網路傳輸。只有在 loopback 真的不可用時才開啟（例如 WSL2 NAT 網路），且優先改用 WSL2 mirrored networking。

6.5 Desktop App【Official】

• 平台：macOS（Intel + Apple Silicon）、Windows（x64 與 ARM64）、Linux（Ubuntu/Debian，beta）。
• 內含 Claude Code，不需另裝 CLI；需付費訂閱。
• 四種環境：Local（本機）、Cloud（Anthropic 管理的 VM）、SSH（遠端機器）、WSL。
• 核心特色：
  • 每個新 session 自動獲得自己的 git worktree，平行工作不互相干擾。
  • 逐行 diff 檢視器，可對特定行留言（Cmd+Enter / Ctrl+Enter 送出）。
  • 可拖曳的窗格：chat、diff、browser、terminal、file editor、plan、tasks、iOS Simulator。
  • Scheduled tasks（本機排程，與雲端 Routines 不同）。
  • Connectors（GitHub、Slack、Linear、Google Calendar、Notion；限 local/SSH session）。
• 已知限制：沒有 agent teams（改用 dynamic workflows 或 cross-session messaging）、不能腳本化（自動化請用 CLI）、@mention 檔案僅限 local/SSH。

⚠️ Windows 上的 Desktop WSL session 預設被關閉，當 Claude Desktop 偵測到裝置是組織管理的（例如存在 C:\Program Files\ClaudeCode\managed-settings.json）時。要開啟需佈署 HKLM 登錄機碼 HKLM\SOFTWARE\Policies\Claude 下的 disableWslSessions 設為 false 或 0（需 Claude Desktop v1.19367.0 以上）。

6.5.1 三種排程機制的完整比較【Official】

Claude Code 有三種排程機制，企業最常見的錯誤是把它們當成同一件事來規範。三者的隔離邊界、資料存取範圍與權限模型完全不同：

🚨 企業治理重點：Routines 在雲端自主執行、完全沒有權限提示；Desktop 排程任務則握有本機檔案的完整存取權。這兩者是不同的風險輪廓，資安規範必須分開撰寫。

Desktop 排程任務的關鍵行為（企業規範需涵蓋）：

⚠️ 撰寫 prompt 時務必考慮補跑：排在早上 9 點的任務，若電腦睡了一整天，可能在晚上 11 點才跑。時間敏感的任務必須把護欄寫進 prompt 本身，例如「只檢視今天的 commit；若已過下午 5 點，跳過檢視並改為摘要遺漏項目」。

📌 Desktop 排程任務需 Claude Desktop 1.1.5368 以上；建立位置為 Code 分頁 → 側邊欄 Routines → New routine → Local。刪除任務時，確認對話框的 Also delete files on disk 才會一併移除 SKILL.md 與相關資料。

6.6 Claude Code on the web（雲端 session）【Preview】

• Research preview：Pro、Max、Team 可用；Enterprise 需 premium 座位或 Chat + Claude Code 座位。
• 執行位置：Anthropic 管理的 VM，或組織的 self-hosted environment。
• 從終端機啟動：

claude --cloud "Fix the authentication bug in src/auth/login.ts"

🚨 雲端 VM clone 的是你目前目錄的 GitHub remote 與目前分支，不是你的本機 checkout。 有本機 commit 請先 push。

• 從雲端拉回終端機：

claude --teleport            # 互動式 session 選擇器
claude --teleport <session-id>

--teleport 的前置條件：工作目錄乾淨、在同一個 repo（不能是 fork）、分支已 push、同一個 claude.ai 帳號。

• 沒有 GitHub 也能用：Claude Code 會把本機 repo 打包上傳（bundle）。macOS / Linux / WSL 上會自動排除未 commit 的憑證類檔案（.env、Terraform *.tfvars、id_rsa、*.pem），並列出被排除的檔案。上限 100MB。
• 安全隔離：每個 session 獨立 VM、預設限制網路、git 憑證留在沙箱外由 proxy 以 scoped credential 代理、git push 限制在當前分支、全操作稽核記錄、閒置後 VM 回收。

⚠️ 組織 IP allowlist 會讓 Anthropic 託管的雲端 session 全部認證失敗，因為它們是從 Anthropic 的基礎設施呼叫 API，不是從你的網路。Code Review 與 Anthropic 託管的 routines 也一樣。需聯繫 Anthropic 支援將這些服務排除在 IP allowlist 之外。

6.6.1 GitHub 連線的兩條路徑與企業控管【Official】（v1.2 新增）

依官方新增的 web-quickstart 頁，雲端 session 一定要連結 GitHub（不想連 GitHub 的組織，官方建議改用 Remote Control）。連結方式有兩種，治理意義差很多：

🚨 /web-setup 的資安意義：它會把開發者本機的 gh token 傳送給 Anthropic，以加密方式存在 claude.ai 帳號中，之後雲端 session 就以這個 token 存取 GitHub。這個 token 的權限通常遠大於「只安裝在特定 repo 的 GitHub App」。建議：

• 高度管制組織不要開啟 Quick web setup，一律走 GitHub App（權限以 repo 為單位）。
• 若要開啟，請要求開發者使用權限最小化的 fine-grained token。
• 移除方式：在 claude.ai/customize/connectors 中斷 GitHub 連線（會同時刪除雲端 session 使用的 GitHub 憑證）；要讓 token 本身失效，必須到 GitHub 撤銷。

📌 ZDR 組織無法使用 /web-setup 與任何雲端 session 功能。

其他 v1.2 相關變更：v2.1.272 起，組織環境可以在 Admin settings → Cloud environments 編輯；v2.1.278 修正了「Custom 網路存取但未填任何網域的環境，會靜默退回 Trusted」的問題（詳見第 7.8 節）；v2.1.274 起，介面中的「Claude Code on the web」字樣統一改稱 cloud session。

6.7 Remote Control【Official】

• 所有方案可用；Team / Enterprise 預設關閉，需 Owner 在 Claude Code 管理設定開啟。
• 用途：讓 claude.ai/code 或 Claude 手機 App 連上你機器上正在跑的 session。
• 程式碼執行與檔案存取全部留在你的機器上。
• 連線期間，session transcript 會存在 Anthropic 伺服器以便跨裝置同步。
• 使用多個短期、窄範圍的憑證，各自獨立到期，以縮小單一憑證外洩的影響範圍。

claude remote-control          # 啟動 Remote Control 伺服器
claude --remote-control        # 啟動互動式 session 並開啟 Remote Control

📌 --cloud 與 --remote-control 完全不同：前者建立雲端 session（在 Anthropic 的 VM 執行），後者把本機 session 曝露給網頁監看（在你的機器執行）。

6.8 離開座位時的工作方式比較【Official】

6.8.1 Claude in Slack：Team／Enterprise 的退場路徑【Official】

🚨 這一項會直接影響企業導入決策，導入前必讀。

Anthropic 正在為 Team 與 Enterprise 工作區淘汰現行版本的 Claude Code in Slack，改由 Claude Tag 取代。現行版本的每個 session 都跑在個別使用者自己的帳號下；Claude Tag 則以組織的共用身分執行 @Claude，並由管理者統一設定存取權。既有的 Slack app 與 @Claude handle 會保留，切換日期需向你的 Anthropic 客戶團隊確認。

Pro 與 Max 方案不適用 Claude Tag，因此現行版本仍是這兩個方案的設定路徑。

若你的組織是 Team／Enterprise 且尚未導入：直接評估 Claude Tag，不要在現行版本上建立流程與規範。若已在使用：官方提供從現行版本遷移的路徑，需由管理者執行。

現行版本的存取模型（供既有使用者理解風險）：

🚨 Prompt Injection 風險（官方明列）：在 Slack 中叫用 @Claude 時，Claude 會取得該對話的脈絡以理解你的請求，因此可能會遵循脈絡中其他人訊息裡的指示。只在可信的 Slack 對話中使用。這與第 24 章的威脅模型一致：任何進入 context 的外部內容都是不可信輸入。

現行版本的限制：只支援 GitHub 上的 repository；每個 session 只能開一個 PR；只在頻道（公開或私人）中運作，不支援 DM；使用者必須具備 Claude Code on the web 的存取權，否則 @Claude 只會給出一般聊天回應。

📌 v1.1 更正：Claude Tag 的說明頁 claude-tag 已納入 code.claude.com 的官方文件索引（v1.0 記載其「不在母體索引中」已不正確）。完整設定細節仍以 claude.com/docs/claude-tag/* 系列為準，且切換日期仍未公開。

6.9 Computer Use（螢幕控制）【Preview】

6.9.1 🚨 企業必須先知道的可用性限制【Official】

🚨 Computer use 在 Team 與 Enterprise 方案上不可用。

限制	內容
方案	僅 Pro 與 Max。Team 與 Enterprise 不可用
平台（CLI）	僅 macOS。Linux 與 Windows 的 CLI 不支援
Session 型態	需互動式 session，-p 非互動模式不可用
Provider	不支援 Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry。若貴司僅透過第三方 provider 存取 Claude，需要另一個 claude.ai 帳號才能使用

🎯 對多數企業讀者的結論：若貴司是 Team／Enterprise 方案，本節屬於背景知識——你的使用者無法啟用它。但個人 Pro／Max 帳號在公司機器上仍可能啟用，這才是真正需要納管的情境。

6.9.2 它做什麼、何時才會被用到【Official】

Computer use 讓 Claude 開啟應用程式、控制螢幕、像你一樣操作機器：編譯 Swift App、啟動它、點過每個按鈕、擷取畫面，全都在寫程式的同一段對話中完成。

Claude 有多種與應用程式互動的方式，computer use 是最廣泛也最慢的一種，因此 Claude 會先嘗試最精確的工具：

有該服務的 MCP server  →  用 MCP
是 shell 指令          →  用 Bash
是瀏覽器工作且已設定    →  用 Claude in Chrome
以上皆非              →  才用 computer use

螢幕控制保留給其他方式都構不到的東西：原生 App、模擬器（如 iOS Simulator）、沒有 API 的工具。

6.9.3 啟用方式【Official】

Computer use 是一個名為 computer-use 的內建 MCP server，預設關閉：

/mcp          # 在伺服器清單中找到 computer-use（顯示為 disabled）→ 選擇 Enable

📌 此設定依專案保存，每個要用的專案只需啟用一次。

首次使用時需授予兩項 macOS 權限：Accessibility（點擊、輸入、捲動）與 Screen Recording（看見螢幕內容）。授予 Screen Recording 後 macOS 可能要求重啟 Claude Code。

6.9.4 信任邊界與內建防護【Official】

🚨 與沙箱化的 Bash 工具不同，computer use 跑在你真實的桌面上，能存取你核准的應用程式。Claude 會檢查每個動作並標記來自螢幕內容的潛在 prompt injection，但信任邊界完全不同。

內建護欄（不需設定即生效）：

核准對話框中的三類高風險警告：

📌 這些 App 不會被封鎖，警告只是讓你判斷該任務是否值得授予該層級的存取權。Claude 的控制層級也依 App 類別而異：瀏覽器與交易平台為唯讀、終端機與 IDE 為僅點擊、其餘為完整控制。

6.9.5 執行期行為【Official】

• 一次一個 session：session 在第一次 computer use 動作時取得機器層級的鎖，並在 session 結束時（而非任務完成時）釋放。第二個 session 會失敗並指名持鎖的 session。
• 工作時隱藏其他 App：Claude 開始控制螢幕時，其他可見 App 會被隱藏，只與已核准的 App 互動；你的終端機視窗保持可見且被排除在截圖外。該輪結束後自動復原。
• 截圖自動降採樣：送給模型前自動降採樣（16 吋 MacBook Pro 原生 Retina 的 3456×2234 會降到約 1372×887）。沒有設定可以改變目標尺寸；若文字太小無法辨識，請在 App 內放大，而不是改螢幕解析度。
• 隨時中止：取得鎖時會出現 macOS 通知 Claude is using your computer · press Esc to stop。按 Esc 或終端機的 Ctrl+C 立即中止，Claude 會取消隱藏並交還控制權（但鎖要到 session 結束才釋放）。

6.9.6 CLI 與 Desktop 的差異【Official】

6.10 本章實務案例

案例：三種介面、三套規範，結果全亂

情境：某企業允許開發者自由選擇 CLI、VS Code 或 Desktop。半年後稽核發現，同一個專案在不同介面下的行為完全不同。

根因：

1. 權限規則寫在 .claude/settings.json，但起始權限模式在 VS Code 擴充上不讀專案設定。
2. Desktop 的 WSL session 在部分機器上被 managed-settings 的存在自動停用，開發者改用 Local session 繞過。
3. 有人用 Desktop 的 Cloud 環境，那裡讀不到本機的 MDM 政策。

處置【建議】：

1. 企業政策一律走 managed settings（server-managed 優先），不依賴專案設定
2. 明文規定「哪些工作可以用哪些 Surface」
3. 雲端 session 的政策必須另外用 server-managed settings 佈署
4. 每季用 /status 抽查各介面的 Setting sources

6.11 本章注意事項

🚨 雲端 session 讀不到裝置上的 MDM 或 managed-settings 檔案。 若貴司同時允許本機與雲端 session，政策必須同時佈署到 server-managed settings，否則雲端 session 等於無政策。

⚠️ Desktop 沒有 agent teams、不能腳本化。 若你的規範假設所有人都能跑同一套自動化腳本，Desktop 使用者會被卡住。

✅ 建議企業標準：以 CLI 或 VS Code 擴充為主力，Desktop 作為 review 與平行工作輔助，Web 僅用於明確授權的長時間任務。

7. 企業部署架構：Provider、Gateway 與 Self-hosted

7.1 部署決策的五個問題【Official / 建議】

官方 admin-setup 把企業部署整理成五個決策。本手冊把它轉成五個問題：

flowchart TD
    Q1["Q1 我們要用哪個 API Provider？"] --> Q2["Q2 政策怎麼送到開發者機器？"]
    Q2 --> Q3["Q3 要強制什麼？"]
    Q3 --> Q4["Q4 用量與成本怎麼看？"]
    Q4 --> Q5["Q5 資料保留與法遵怎麼處理？"]
    Q5 --> DONE["佈署 → /status 驗證 → 教育訓練"]

7.2 Q1：選擇 API Provider【Official】

加密機制（官方明列）：

7.3 Q2：政策交付機制【Official】

Claude Code 依下列優先順序檢查四種來源：

關鍵事實：

• Server-managed settings 在啟動時抓取，並在 session 中每小時輪詢刷新，不需自建端點基礎設施。透過 claude.ai 管理後台交付需要 Teams 或 Enterprise 方案。
• Bedrock / Vertex / Foundry 的部署若也想要遠端交付，可以自架 Claude apps gateway，否則就用檔案或 OS 層機制。
• plist 與 HKLM 需要管理員權限才能寫入，具備抗竄改性；HKCU 則不需提權，應視為便利預設值而非強制通道。
• WSL 預設只讀 Linux 路徑 /etc/claude-code。要把 Windows 政策延伸到同一台機器的 WSL，需在 HKLM 或 C:\Program Files\ClaudeCode 設 wslInheritsWindowsSettings: true。
• 陣列型設定（如 permissions.allow、permissions.deny）會跨來源合併，所以開發者可以擴充但不能移除管理員設定的項目。但 fallbackModel、availableModels、modelPicker 是取代而非合併。

7.3.1 Managed 層內部的優先順序【Official】

當同時存在多個 managed 來源時：

1. Remote（server-managed / gateway）
2. MDM / OS 層 policy
3. managed-settings.d/*.json 與 managed-settings.json 合併後的檔案

預設只採用最高順位的來源。 若要合併所有來源，需在你佈署的最高順位來源中設 managedSourcesBehavior: "merge"（需 v2.1.242+）。

「鎖定型」的鍵是例外，一律取最嚴格值：allowManagedHooksOnly、permissions.disableBypassPermissionsMode、crossSessionInbound。

7.3.2 多團隊分權管理【建議】

若政策由多個團隊共同擁有（資安管 deny、平台團隊管 telemetry），不要共用一個檔案：

/etc/claude-code/
├── managed-settings.json          # 基礎政策
└── managed-settings.d/
    ├── 10-telemetry.json          # 平台團隊維護
    ├── 20-security.json           # 資安團隊維護
    └── 30-model-policy.json       # 架構團隊維護

Claude Code 先合併 managed-settings.json，再依檔名字母序合併目錄中的每個 *.json。用數字前綴控制順序。隱藏檔與非 .json 結尾的檔案會被忽略。

7.4 Q3：企業該強制什麼【Official / 建議】

這是本手冊最重要的表格之一。左欄是控制目標，右欄是官方對應的設定鍵。

🎯 權限規則與沙箱涵蓋不同層次。 官方講得很直白：拒絕 WebFetch 只擋掉 Claude 的抓取工具，但只要 Bash 被允許，curl 和 wget 仍可連到任何 URL。沙箱的網域白名單才是在 OS 層補上這個缺口。

7.5 企業基準政策範本【建議】

以下是本手冊建議的起手式，適用於一般企業的開發環境。請依貴司資安規範調整後再佈署。

{
  "permissions": {
    "defaultMode": "default",
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/*.pem)",
      "Read(./**/id_rsa*)",
      "Read(./**/credentials)",
      "Read(~/.aws/**)",
      "Read(~/.ssh/**)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(sudo:*)",
      "Bash(rm -rf /*)",
      "WebFetch"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(gh pr create *)",
      "Bash(gh pr merge *)",
      "Bash(docker *)",
      "Bash(kubectl *)",
      "Bash(terraform *)"
    ],
    "disableBypassPermissionsMode": "disable",
    "blockReadsOutsideWorkingDirectories": true
  },
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": false,
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "repo.maven.apache.org",
        "*.corp.example.com"
      ]
    },
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ]
    }
  },
  "availableModels": ["opus", "sonnet", "haiku"],
  "enforceAvailableModels": true,
  "maxEffortLevel": "high",
  "minimumVersion": "2.1.281",
  "syncClaudeAiSkills": false,
  "syncClaudeAiPlugins": false,
  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": "<your-org-uuid>",
  "env": {
    "HTTPS_PROXY": "http://proxy.corp.example.com:8080",
    "NO_PROXY": "localhost,127.0.0.1,.corp.example.com",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://otel-collector.corp.example.com:4317",
    "OTEL_LOG_MANAGED_SETTINGS": "1",
    "OTEL_METRICS_INCLUDE_REPOSITORY": "true"
  },
  "claudeMd": "所有變更必須先在分支上進行，禁止直接推 main。\n完成任務前必須執行 `mvn verify`。\n禁止把任何憑證、token、連線字串寫進程式碼或設定檔。"
}

📌 v1.2 對本範本的變更：

變更	理由
新增 permissions.blockReadsOutsideWorkingDirectories: true	在所有權限模式下禁止讀取工作目錄以外的檔案，搭配 v2.1.273 的繞過修正後才完整（第 15.7 節）
minimumVersion 由 2.1.228 提高為 2.1.281	涵蓋 v2.1.269–281 的權限繞過修正（第 2.3.2 節）。要「拒絕啟動」而不只是提示升級，請改用 requiredMinimumVersion（第 8.6 節）
新增 syncClaudeAiSkills / syncClaudeAiPlugins: false	關閉從 claude.ai 帳號同步 skills／plugins 這條繞過私有 marketplace 的來源
新增 OTEL_LOG_MANAGED_SETTINGS、OTEL_METRICS_INCLUDE_REPOSITORY	以遙測驗證政策是否生效，並依 repo 歸因成本（第 41.6 節）
availableModels 保留 opus	v2.1.280 起 opus 解析為 Opus 5.5（預設 effort 為 medium）；要以 high 執行，請在此檔加上頂層的 "effortLevel": "high"（第 5.4 節）

⚠️ blockReadsOutsideWorkingDirectories 會讓工具讀不到 ~/.gitconfig、~/.npmrc 之類的家目錄設定檔，請在 PoC 期間確認開發流程不受影響，必要時以 sandbox.filesystem.allowRead 逐一開放。

⚠️ sandbox.failIfUnavailable：設為 true 時，沙箱無法啟動就直接讓 Claude Code 失敗。這是給「把沙箱當安全閘門」的部署用的。但在原生 Windows 上沙箱本來就不可用，設 true 會讓 Windows 開發者完全無法啟動。若貴司是 Windows 為主，請維持 false 並改用容器策略。

7.6 網路設定【Official】

7.6.1 Proxy

# HTTPS proxy（建議）
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080

# 略過 proxy（空白或逗號分隔皆可）
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com"

• 小寫變體同樣有效；讀取順序為 https_proxy → HTTPS_PROXY → http_proxy → HTTP_PROXY。
• 不支援 SOCKS proxy。
• WebSocket 連到 localhost、::1、127.0.0.0/8 時永遠不走 proxy，不需在 NO_PROXY 加 loopback 條目。
• 需要 NTLM / Kerberos 之類進階認證時，官方建議改用支援該認證方式的 LLM Gateway。

🚨 背景 agent 讀不到你 shell 裡的 export。 background agent supervisor 是一個所有終端機共用的行程，它繼承的是最先啟動它的那個 shell 的環境；由 OS 安裝為服務的 supervisor 甚至完全沒有 shell 環境。因此 proxy、CA、mTLS 變數必須寫在 ~/.claude/settings.json 或 managed settings 的 env 區塊，不能只 export。

7.6.2 憑證

# 只信任內建的 Mozilla CA 集
export CLAUDE_CODE_CERT_STORE=bundled
# 只信任 OS 憑證存放區
export CLAUDE_CODE_CERT_STORE=system
# 預設值為 bundled,system

# 額外的企業 CA
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

• 預設同時信任內建 Mozilla CA 與 OS 憑證存放區。讀取 OS 存放區需要具備 tls.getCACertificates 的 runtime：原生安裝器一定有；npm 安裝則需要 Node 22.15 以上。
• 企業 TLS 檢查 proxy 只要根憑證裝進 OS 信任存放區，且 runtime 讀得到，就不需額外設定。
• CLAUDE_CODE_CERT_STORE 沒有專屬的 settings.json schema 鍵，只能透過 env 區塊或行程環境設定。

7.6.3 mTLS

export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

憑證輪替：直接替換同路徑的檔案即可，執行中的 session 會在下次連線層錯誤（連線重設、TLS handshake 失敗）重試時重新讀取。可用 CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION=1 關閉這個行為。

⚠️ OTLP telemetry exporter 會保留首次使用時載入的憑證，輪替後必須重啟 Claude Code 才會生效。

7.6.4 必須放行的網域【Official】

企業防火牆與 proxy 白名單至少需要：

🚨 api.anthropic.com 即使在 Bedrock / Vertex / Foundry 上也會被呼叫：WebFetch 的網域安全檢查（只送 hostname，不送完整 URL 或內容）預設一律執行。若網路封鎖此 host，WebFetch 會全部失敗，除非設 skipWebFetchPreflight: true。

7.7 Self-hosted Environments【Preview】

公開 beta，僅 Team 與 Enterprise，預設關閉。

適用情境：貴司要用雲端 session（claude --cloud、Routines、Web、行動 App），但執行必須在自己的網路內。

架構三要素：

flowchart LR
    subgraph NET["你的網路邊界"]
        R["Runner"]
        S1["Claude Code Session 1"]
        S2["Claude Code Session 2"]
        GIT["內部 Git Host"]
        SVC["內部服務 / DB / Registry"]
        R --> S1
        R --> S2
        R -->|clone| GIT
        S1 --> SVC
    end
    R -->|outbound HTTPS 輪詢佇列| API["api.anthropic.com"]
    S1 -->|event stream + 模型推論| API
    S2 --> API

關鍵事實：

• 所有連線都是從你的網路往外（outbound HTTPS）；Anthropic 從不主動連進你的網路。
• 留在你的基礎設施上：repository checkout、build 產物、secrets、session 建立或修改的任何檔案。
• 仍會送到 Anthropic：對話本身（prompt、回應、工具結果）走 api.anthropic.com 做模型推論，且 Anthropic 會儲存 session transcript 以便從其他介面續接。
• 限制：ZDR 組織不可用；模型推論只能走 Anthropic API，不能路由到 Bedrock / Vertex / Foundry 或 LLM gateway；repository 只支援 GitHub；Claude Security 與 Code Review session 目前不會路由到 self-hosted 環境。
• 一個 runner 同一時間只服務一個 owner：第一個接下的 session 會把 runner 鎖定到該 owner，確保不同人的程式碼不會混在同一台。因此最小 fleet 規模等於你預期同時活躍的 owner 數量。

7.8 Cloud Environments（雲端環境設定）【Preview】

⚠️ Cloud environments 需要 Claude Code on the web，官方標示為 research preview，適用 Pro、Max、Team，以及具備 premium seat 或 Chat + Claude Code seat 的 Enterprise 使用者。

每一個雲端 session 都跑在一個雲端環境中。環境決定了 session 的對外網路存取層級、環境變數、setup script，以及（僅 Pro/Max）API 憑證。

📌 同一組環境適用於所有啟動雲端 session 的介面：Claude Code on the web、終端機的 claude --cloud、Claude Tag、routines、Claude 行動 App、Desktop App。每一個介面也都能改為路由到 self-hosted 環境。

7.8.1 Default 環境與選擇規則【Official】

尚無環境時，onboarding 會建立 Default 環境。Default 本身不帶任何設定：網路層級為 Trusted（可達套件註冊庫與預設允許清單，其餘皆不可）、不定義任何環境變數或 setup script。

有多個環境時，各介面的選擇方式不同：

/remote-env      # 開啟選擇器，寫入使用者設定的 remote.defaultEnvironmentId

📌 /remote-env 只設定預設值：它不啟動 session，也不能新增或編輯環境。

派送 session 時可用 --environment <environment-id> 覆寫該次呼叫（需 v2.1.224+）。⚠️ 此旗標只接受 self-hosted 的 ccpool_ ID；傳入 Anthropic 託管的 env_ ID 會被拒絕，後者請用 /remote-env 指定。

7.8.2 🚨 網路存取層級（企業管控核心）【Official】

每個環境設定一個網路存取層級，控制其 session 可建立的對外連線：

🚨 無論選哪個層級，以下四條路徑仍然可達——因為它們走的路線不經過 session 的網路允許清單。企業做網路隔離評估時，這是最容易被誤判的地方：

1. GitHub（透過其專屬 proxy）
2. 你啟用的 MCP connector（流量走 Anthropic 伺服器而非 session 網路）
3. 環境 API 憑證上所列的主機（少數例外除外）
4. Anthropic API（Claude Code 自身的請求，即使在 None 層級也可達）

Custom 允許清單寫法（每行一個網域，開頭 *. 匹配所有子網域）：

api.example.com
*.internal.example.com
registry.example.com

勾選 Also include default list of common package managers 可保留 Trusted 清單；不勾則只允許你列出的項目。

🚨 沒有組織層級的網域允許清單。

每個環境各有自己的允許清單，管理員無法推送一份清單到每位成員的環境。Server-managed settings 在雲端 session 內仍然生效，但其中沒有任何一項能為環境的網路允許清單增加網域。

企業若需要統一的網路政策，唯一可行路徑是由 Owner 建立組織共享環境並要求成員使用它，或改用 self-hosted 環境。

7.8.3 環境變數與 API 憑證（兩者的安全性差異）【Official】

環境變數採 .env 格式，一行一組 KEY=value：

NODE_ENV=development
LOG_LEVEL=debug
DATABASE_URL=postgres://localhost:5432/myapp

• 每個 session 在啟動時複製一次環境的值。執行中的 session 不會重讀設定，因此編輯或新增變數只影響之後啟動的 session。
• ⚠️ 未加引號的值中，# 會開始註解並丟棄該行其餘部分；跨多行或含 # 的值必須加引號。
• 🚨 使用該環境的任何人都能讀到這些值。 因此環境變數不是放 secret 的地方。

API 憑證則解決了這個問題——但僅限 Pro 與 Max：

永遠不會被附加憑證的請求：GitHub（改由 GitHub proxy 認證）、Anthropic API 與公開套件註冊庫（api.anthropic.com、registry.npmjs.org、jsr.io、npm.jsr.io、pypi.org、files.pythonhosted.org、index.crates.io、proxy.golang.org）、以及 setup script 的請求（Claude Code 是在 setup script 跑完之後才連上 agent proxy）。

📌 兩個憑證的主機重疊但不完全相同時，不會有任何標記，且 agent proxy 只會送出其中一個——這是個容易產生非預期行為的組態，設定時請避免。

7.8.4 組織共享環境與 Claude Tag 頻道【Official】

Team 與 Enterprise 方案的 Owner 可建立與全組織成員共享的雲端環境：

• 管理位置：admin settings 的 Cloud environments 頁（同一頁也管理 self-hosted 環境）。🚨 Admin 角色無法開啟此頁；可開啟的角色清單與管理 server-managed settings 者相同。
• 共享環境會與個人環境一起出現在每位成員的選擇器中；Owner 可在該處編輯，其他成員為唯讀。
• 組織的預設環境在 claude.ai/admin-settings/claude-code 另外設定。
• 🚨 每位成員在共享環境中的 session 都會讀到它的變數，因此絕不可在其中放入 secret；而能避開此問題的 API 憑證在 Team/Enterprise 尚不可用。

Claude Tag 頻道中，Claude 以組織的共享身分運作而非任何成員身分，因此頻道 session 只能使用組織層級環境（共享環境或 self-hosted 環境）。要給頻道一套未預裝的工具鏈（例如 .NET），Owner 需建立帶 setup script 的共享環境，再把頻道指向它（設為組織預設環境，或在 Claude Tag 管理設定中釘選到該頻道）。

7.8.5 Setup Script 與環境快取【Official】

Setup script 是一段 Bash 腳本，在新 session 啟動時、Claude Code 啟動之前執行，用來安裝相依套件或準備環境。

✅ 與 SessionStart hook 的差異：setup script 在 Claude Code 啟動前執行，因此適合安裝工具鏈；SessionStart hook 在 session 內執行，適合需要 session 脈絡的準備工作。兩者可並用。

7.8.6 封存（沒有刪除）【Official】

⚠️ 環境無法刪除，只能封存（Archive）。 封存只影響新 session：

• 已在該環境執行中的 session 繼續運作。
• 環境從選擇器與 /remote-env 中消失，無法再被選取。
• 🚨 環境上的 API 憑證在其執行中的 session 內仍然附著。封存前請先刪除不再需要的憑證。
• 任何明確指定該環境的設定（例如 routine）都無法再啟動新 session，必須改指向其他環境。

7.8.7 GitHub Proxy 與安全 Proxy【Official】

Anthropic 託管環境中，所有 GitHub 操作都走專屬 proxy，讓你真實的 GitHub 憑證留在 session VM 之外（與環境的存取層級無關）。這個 proxy 提供的管控，企業應直接視為既有的安全邊界：

此外，Anthropic 託管環境的所有對外網際網路流量都會通過一個 HTTP/HTTPS 安全 proxy，提供惡意請求防護、速率限制與濫用防範、內容過濾，以及所請求主機名稱的 DNS 層級稽核軌跡。📌 在 self-hosted 環境中，對外流量改為從你自己的網路邊界離開。

7.9 Dev Container 與其他隔離方式【Official】

若不需要雲端 session，只是要隔離，選項見第 23 章 的完整比較。快速版：

7.10 本章實務案例

案例：Proxy 設好了，但背景 agent 一直連不上

情境：某企業所有開發者都在 .bashrc export 了 HTTPS_PROXY，一般 session 正常，但 claude agents 啟動的背景 session 一律連線失敗。

根因：background agent supervisor 是跨終端機共用的單一行程，它繼承的是最先冷啟動它的那個 shell 的環境。有些機器上是由 OS 服務啟動的，根本沒有 shell 環境。

處置：把所有網路變數搬到 ~/.claude/settings.json 的 env 區塊（或 managed settings）：

{
  "env": {
    "HTTPS_PROXY": "http://proxy.corp.example.com:8080",
    "NO_PROXY": "localhost,127.0.0.1,.corp.example.com",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-ca.pem"
  }
}

然後停掉舊的 supervisor 讓它以新設定重啟：

claude daemon stop --any

7.11 本章注意事項

🚨 選 Bedrock / Vertex / Foundry 之前，先確認團隊不需要雲端 session、Routines、Code Review、Remote Control、Chrome。 這是採購階段就要釐清的，不是上線後才發現。

⚠️ C:\ProgramData\ClaudeCode\managed-settings.json 已不再被讀取。 若你的佈署腳本還在用舊路徑，政策等於沒生效且不會報錯。

✅ 佈署完一定要在樣本機執行 /status 與 claude doctor 驗證。

8. Enterprise Governance（企業治理）

8.1 治理模型全景【建議】

flowchart TD
    GOV["Claude Code 企業治理"]
    GOV --> ID["身分與存取<br/>forceLoginMethod · forceLoginOrgUUID · SSO/SCIM"]
    GOV --> POL["政策交付<br/>server-managed · MDM · managed-settings.json"]
    GOV --> PERM["權限治理<br/>allow/ask/deny · defaultMode · disableAutoMode"]
    GOV --> ISO["隔離治理<br/>sandbox.* · 容器 / VM"]
    GOV --> EXT["擴充治理<br/>MCP allowlist · Plugin marketplace · strictPluginOnlyCustomization · allowManagedHooksOnly"]
    GOV --> MODEL["模型治理<br/>availableModels · maxEffortLevel · modelOverrides"]
    GOV --> DATA["資料治理<br/>data retention · ZDR · 遙測開關"]
    GOV --> OBS["可觀測性與稽核<br/>OpenTelemetry · Analytics · ConfigChange hook"]
    GOV --> VER["版本治理<br/>minimumVersion · requiredMinimumVersion"]

8.2 身分與登入強制【Official】

{
  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": "<org-uuid>"
}

• forceLoginMethod 可限制登入方式為 claude.ai、Claude Console 或雲端 gateway。這個限制會套用到 VS Code 擴充、Agent SDK、claude setup-token 與 /install-github-app；終端機的互動式登入畫面會預選該方式但不強制。
• Claude Code 會針對 claude.ai 帳號登入驗證組織（終端機、VS Code 擴充、Agent SDK 皆會驗）；Console 登入與 gateway 登入不驗證組織。
• 設定後，用 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 認證的 session 會在啟動時被阻擋；雲端供應商 session 不受影響。

⚠️ Version Note：v2.1.212 之前，這兩個鍵只作用於終端機登入。

• SSO、SCIM 佈建、座位指派是在 Claude 帳號層設定的，不在 Claude Code 內設定。

8.3 擴充機制治理：最容易被忽略的攻擊面【Official】

這是本手冊認為企業最該優先處理的一組設定。原因：skills、agents、hooks、MCP server 都是「會被執行的內容」，而它們可以來自 repository。

8.3.1 最嚴格的做法

{
  "strictPluginOnlyCustomization": true,
  "allowManagedHooksOnly": true,
  "allowManagedMcpServersOnly": true,
  "strictKnownMarketplaces": true,
  "disableSideloadFlags": true,
  "disableCommandPluginSources": true,
  "allowManagedPermissionRulesOnly": true
}

這組設定的效果：

🎯 這組設定適合金融、醫療、公部門等高度管制環境。 代價是開發者失去自訂彈性，所有擴充都要走「平台團隊打包成 plugin → 內部 marketplace 發佈」的流程。這是刻意的權衡：把攻擊面從 N 個 repository 收斂到 1 個內部 marketplace。

8.3.2 為什麼專案層的擴充是風險【Official】

官方在多處明確提醒：

• 專案的 .mcp.json 首次使用需要核准，但 claude -p 不顯示 workspace trust 對話框、也不顯示 per-server 核准提示。
• 在沒有 --bare 的情況下，claude -p 會在一個你從未信任過的資料夾中，執行該專案 .claude/settings.json 的 hooks，並連上其 .mcp.json 的 server。
• headersHelper（MCP 動態標頭腳本）只在受信任目錄執行；來源不受信任時會從其環境移除憑證變數。
• auto mode 的分類器不讀 .claude/settings.json 與 .claude/settings.local.json 的 autoMode 區塊，正是為了避免被 checked-in 的 repo 或 build step 注入自己的 allow 規則。

🚨 企業結論：在 CI 中執行 claude -p 時，一律加上 --bare。

claude --bare -p "Summarize the changes" --allowedTools "Read"

--bare 會跳過 hooks、skills、custom commands、subagents、plugins、MCP server、auto memory 與 CLAUDE.md 的自動探索，確保每台機器結果一致，也確保不會執行 repo 帶來的東西。

8.4 MCP 治理【Official】

📌 Managed MCP 設定的優先權高於所有使用者自行設定的 scope。

企業 MCP 審核流程【建議】：

flowchart LR
    A["團隊提出 MCP server 需求"] --> B["填寫審核表：來源、作者、權限、資料流"]
    B --> C{"是自建的嗎？"}
    C -- 是 --> D["程式碼審查 + 內部託管"]
    C -- 否 --> E{"在 Anthropic Directory 中？"}
    E -- 否 --> F["拒絕，或要求自建替代品"]
    E -- 是 --> G["注意：Anthropic 做上架審查，但不做安全稽核"]
    G --> H["資安評估：它能讀什麼？能寫什麼？認證方式？"]
    D --> H
    H --> I{"通過？"}
    I -- 是 --> J["加入 allowedMcpServers / managedMcpServers"]
    I -- 否 --> F

🚨 官方原文明確聲明：Anthropic 會依上架標準審查 connector 才把它放進 Anthropic Directory，但「不對任何 MCP server 做安全稽核或管理」。 這句話必須寫進貴司的 MCP 審核表。

8.5 稽核：ConfigChange Hook【Official / 建議】

官方在 Security 頁面直接建議：用 ConfigChange hook 稽核或阻擋 session 進行中的設定變更。

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "user_settings",
        "hooks": [
          {
            "type": "command",
            "command": "/opt/corp/bin/audit-config-change.sh"
          }
        ]
      },
      {
        "matcher": "project_settings",
        "hooks": [
          {
            "type": "command",
            "command": "/opt/corp/bin/audit-config-change.sh"
          }
        ]
      }
    ]
  }
}

ConfigChange 的 matcher 值為：user_settings、project_settings、local_settings、policy_settings。exit code 2 會阻擋該設定變更。

範例稽核腳本【建議】：

#!/bin/bash
# /opt/corp/bin/audit-config-change.sh
# 記錄所有設定變更到 syslog，並阻擋對權限規則的修改
set -euo pipefail

INPUT=$(cat)
SCOPE=$(echo "$INPUT" | jq -r '.matcher // "unknown"')
USER_NAME="${USER:-unknown}"
TS=$(date -Iseconds)

logger -t claude-code-config "user=$USER_NAME scope=$SCOPE ts=$TS payload=$(echo "$INPUT" | jq -c .)"

# 若變更觸及 permissions 區塊，阻擋並提示走正式流程
if echo "$INPUT" | jq -e '.. | objects | has("permissions")' >/dev/null 2>&1; then
  echo "權限規則變更必須透過 managed settings 流程申請，已阻擋。" >&2
  exit 2
fi

exit 0

8.6 版本控管與強制升級【Official】

企業建議策略【建議】：

{
  "requiredMinimumVersion": "2.1.281"
}

搭配第 50.3 節 的升級流程。

⚠️ 注意安裝方式的自動更新差異：原生安裝會背景自動更新；Homebrew 與 WinGet 不會自動更新，必須手動 brew upgrade / winget upgrade。若貴司同時混用，版本會分歧。

8.7 資料治理【Official】

8.7.1 訓練政策

8.7.2 資料保留

🚨 本機 transcript 是明文的。 若貴司對開發機有磁碟加密或資料分級要求，~/.claude/projects/ 必須納入評估範圍。

8.7.3 遙測開關【Official】

⚠️ CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 不會關閉 WebFetch 的網域安全檢查（需 skipWebFetchPreflight: true），也不會關閉官方 marketplace 自動安裝（需 CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL）。

📌 在 Bedrock / Vertex / Foundry / Claude Platform on AWS 上，error reporting、telemetry 與 bug reporting 預設就是關閉的；session 品質調查與 WebFetch 檢查是例外，仍會執行。

🚨 v2.1.265 新增：Claude apps gateway 會傳送 user.email 與 user.groups 遙測（v1.1 新增）

導入 Claude apps gateway 的組織，使用者的電子郵件與群組歸屬會成為遙測的一部分。這是個資（PII），必須納入貴司的資料流盤點與隱私影響評估（PIA／DPIA），不能當成一般的用量指標處理。詳見第 53 章。

✅ 從正面看，這也是 gateway 能提供逐使用者、逐群組成本歸屬的原因；但資料保護與成本可視性是同一份資料的兩面，導入前請讓法遵與資安同時簽核。

⚠️ 關於 DISABLE_TELEMETRY 的副作用：關閉遙測同時會關閉 feature flag 抓取，而以下功能依賴它：Advisor Tool（見第 5.12.4 節）與 /auto-mode-setup。以停用遙測作為資安基線的企業，需接受這些功能技術上不可用。

8.7.4 法遵與授權邊界【Official】（v1.1 新增）

本節整理官方 legal-and-compliance 頁中，企業法遵與採購最常被問到的幾項。

🚨 把 Claude Code 內嵌到自家產品或服務中的限制（例如放進託管沙箱或其他 agent 基礎設施），這是自建平台的企業最容易踩線的地方：

1. 不得修改 Claude Code 二進位檔。 必須以 Anthropic 發佈的原樣安裝與執行，不得移除、停用或限制其內建的任何認證方式（包含以 Claude 帳號登入或使用者自己的 API key）。
2. 不得代末端使用者付費、轉售或居間 Claude 用量。 每一位末端使用者必須以自己的 Anthropic API key、Claude 訂閱憑證，或第三方推論供應商憑證認證，該用量直接向該使用者計費。
3. 名稱與標誌：可以用純文字準確陳述「本產品預裝 Claude Code」或「本產品執行 Claude Code」，但不得將 Claude Code 或 Anthropic 的名稱或標誌用於自家產品／功能／公司名稱、自家標誌，或以任何暗示 Anthropic 開發、背書或合作的方式使用。

🚨 認證方式的紅線（對自建 Agent 平台特別重要，呼應第 43 章）

• OAuth 認證專供 Claude Free／Pro／Max／Team／Enterprise 訂閱方案的購買者，用於 Claude Code 與其他 Anthropic 原生應用的一般使用。
• 開發者建構與 Claude 能力互動的產品或服務時（包含使用 Agent SDK），應使用 Claude Console 或受支援雲端供應商的 API key 認證。
• Anthropic 不允許第三方開發者在自己的應用中提供 Claude.ai 登入，或代使用者將請求導向 Free／Pro／Max 方案憑證；開發者亦不得收集、儲存或居間 Claude.ai 憑證或 session token——登入必須完整走 Anthropic 自己的流程。

✅ 但這不限制：客戶自行佈建與管理自己的 API key（例如設定在開發環境、secrets manager 或機器映像中，供自己的授權使用者使用），只要所產生的用量依 key 擁有者的合約計費、且未依上述方式轉售或居間。

📌 Pro 與 Max 方案所公告的用量限制，假設的是對 Claude Code 與 Agent SDK 的「一般個人使用」。 企業若規劃以個人方案憑證驅動共用自動化，這一句就是明確的不允許訊號——請改用 Console API key 或企業方案。

8.8 驗證政策是否生效【Official】

# 1. 開發機上執行
claude doctor

# 2. 在互動式 session 中
/status

在 Status 分頁看 Setting sources 一列，會顯示 Enterprise managed settings 加上實際勝出的來源：

📌 Schema 驗證失敗時的行為：Claude Code 會先跳過可修復的單筆項目（例如一條無效的權限規則）並各給一則警告，再丟棄仍失敗的頂層鍵，其餘有效的鍵繼續強制執行。所以「部分生效」是可能的，必須逐條驗證。

⚠️ Version Note：claude doctor 的 Managed settings (remote) 一列需要 v2.1.248 以上。它會回報四種結果之一：政策已載入／組織未設定 server-managed settings／抓取失敗（附原因與是否仍套用快取政策）／略過抓取（附原因）。抓取進行中時則顯示進行中。/status 在抓取失敗時、以及部分「略過抓取」的情況（例如使用者 shell 中匯出了第三方 provider 變數或自訂 ANTHROPIC_BASE_URL）也會顯示同一列。

8.8.1 Server-managed Settings 的六個治理陷阱【Official】

Server-managed settings（從 claude.ai 管理主控台派送，見第 8.1 節）在沒有 MDM 的組織特別實用，但有六件事必須在導入前想清楚：

權限與運作參數：

8.8.2 Fail-closed 啟動：forceRemoteSettingsRefresh【Official】

若你的合規要求是「沒有政策就不准啟動」，設定這個鍵：

{
  "forceRemoteSettingsRefresh": true
}

啟用後，CLI 會在啟動時卡住直到成功抓取新的遠端設定；抓取失敗就直接離開，而不是帶著快取或無政策繼續執行。這個鍵會自我延續：一旦從伺服器派送下來，它也會被快取到本機，讓後續啟動即使在新 session 首次成功抓取前也維持同樣行為。

✅ 建議同時放進 MDM／系統 managed-settings.json：這樣第一次啟動、在任何伺服器 payload 抵達之前就已經是 fail-closed。v2.1.191 起，這個旗標是優先權規則的例外——任何一個受管來源設定它，Claude Code 都會遵守，即使同時存在快取的 server-managed payload。

🚨 啟用前務必先確認網路政策允許連通 api.anthropic.com。若該端點不可達，CLI 會在啟動時離開，使用者將完全無法使用 Claude Code。claude auth 系列子指令（如 claude auth login）豁免於此檢查，讓使用者在憑證過期導致抓取失敗時仍能重新認證。

8.8.3 安全核准對話框：會擋住無人值守流程的一件事【Official】

某些具風險的設定在互動式 session 中會先跳出安全核准對話框，使用者必須核准才會套用；使用者拒絕時 Claude Code 會直接離開。

需要核准的類別：

📌 不需核准的例子：透過 claudeMd 鍵派送的受管 CLAUDE.md 不需核准（v2.1.260 起），因為那是給 Claude 的指令文字，而不是 Claude Code 要執行的指令；Claude 依那些指令使用工具時，仍然會走權限檢查。

🚨 對 CI／無人值守流程的影響：claude -p 或 Agent SDK session 無法顯示對話框，因此需要核准的設定只會套用於該次執行，不會被記錄為已核准、也不寫入本機快取。結果是每一次非互動式執行都要重新抓取設定，直到有人在互動式 session 中核准為止。導入含 hook 或 statusLine 的受管政策時，請安排一次互動式核准，否則 CI 會持續多做一次網路往返。

8.8.4 快取中被扣住的環境變數【Official】

這是一個容易被忽略、但對代理環境影響很大的行為：Claude Code 在伺服器確認 payload 之前，會扣住快取 env 區塊中的數類變數，避免快取中的 proxy、憑證機構、端點或憑證值反過來改道、攔截或重新認證那次「用來確認 payload」的設定抓取。

被扣住的類別包含：proxy 與 TLS 設定（HTTPS_PROXY、NODE_EXTRA_CA_CERTS、mTLS 用戶端憑證變數）、API 路由與 provider 選擇（ANTHROPIC_BASE_URL、各 CLAUDE_CODE_USE_*）、認證憑證（ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_OAUTH_TOKEN）、設定目錄選擇器 CLAUDE_CONFIG_DIR，以及（v2.1.223+）WIF 變數、ANTHROPIC_PROFILE／ANTHROPIC_CONFIG_DIR 與 HOME、XDG_CONFIG_HOME、APPDATA、USERPROFILE。

🚨 這對「需要 proxy 才能連到 api.anthropic.com」的企業是關鍵：不要只把 proxy 設定放在 server-managed 的 env 區塊，否則第一次啟動（無快取）根本連不出去。proxy 必須來自 endpoint-managed（MDM／managed-settings.json，需 v2.1.223+）、shell 環境，或使用者層 settings。

⚠️ Version Note：這項扣住行為需 v2.1.198 以上；在此之前，整個快取 env 區塊會在啟動時直接套用。

8.9 Corporate Launcher：強制所有行程走公司啟動器【Official】

有些組織規定工作站上的每一個行程都必須透過強制啟動器（launcher）啟動——由啟動器套用沙箱、網路管控或憑證注入，未經啟動器啟動的執行檔即屬違反政策。

Claude Code 為此提供 CLAUDE_CODE_PROCESS_WRAPPER 環境變數與對應的 processWrapper 設定鍵。

⚠️ Version Note

• CLAUDE_CODE_PROCESS_WRAPPER 需 v2.1.208 以上。更早的版本直接忽略此變數，所有行程都不經啟動器啟動。
• processWrapper 設定鍵需 v2.1.210 以上。更早的版本把它當成未知鍵忽略，不套用啟動器，且不回報任何錯誤。

🚨 這兩種「靜默失效」正是企業政策最危險的形態：政策看起來部署了，實際上完全沒生效。部署後務必用 8.9.5 的方式確認執行中的版本確實套用了。

8.9.1 為什麼不能只包 PATH 上的 claude【Official】

一個只包住 PATH 上 claude 指令的啟動器碰不到這些行程——因為它們是從二進位檔的直接路徑啟動的，不會去查 PATH。

設定 CLAUDE_CODE_PROCESS_WRAPPER 後，以下行程會經過你的啟動器：

8.9.2 🚨 涵蓋不到的行程（政策缺口清單）【Official】

這份清單請直接納入貴司的風險登錄：

🚨 Windows 上這個變數被完全忽略。

啟動器契約依賴 exec，而 Windows 不支援。設了變數的 Windows 機器會照常運作、所有行程都不經啟動器，唯一的訊號是 debug log 中的一則警告。

若貴司的啟動器政策涵蓋 Windows，這個變數在那裡無法滿足政策：規劃推行時請把 Windows 機器一律計為「未包覆」。 這與第 23 章 的 Bash 沙箱不支援原生 Windows 是同一類問題——Windows 標配的企業必須改以 WSL2、容器或 VM 落實。

8.9.3 設定步驟【Official】

步驟一：撰寫啟動器腳本

在絕對路徑（例如 /opt/corp/launcher）建立可執行腳本。Claude Code 會以完整的 Claude Code 指令作為其參數來執行它，腳本必須以 exec "$@" 結尾，讓自己被 Claude Code 取代：

#!/bin/sh
# 貴組織的前置設定：進入沙箱、套用網路管控、或注入憑證。
exec "$@"

以 chmod +x 賦予執行權限。

⚠️ 若你先前曾用啟動器取代 ~/.local/bin/claude symlink，請在同一次變更中把原本的 symlink 還原。被取代的 symlink 會讓第一個被包覆的 session 同時透過兩層啟動器去啟動背景服務，並使安裝進入「externally managed」狀態：/doctor 會回報、自動更新會保留該檔案、舊版本的清理會持續停用，直到安裝器重新接管該路徑為止。

步驟二：在 settings 的 env 區塊設定變數

必須寫在設定檔的 env 區塊，讓分離的背景服務能繼承。🚨 在 shell 裡 export 是不夠的——背景服務是按需啟動、比你的 shell 活得久，而且永遠不會重讀 shell profile。

{
  "env": {
    "CLAUDE_CODE_PROCESS_WRAPPER": "/opt/corp/launcher"
  }
}

單機放 ~/.claude/settings.json；全組織部署放 managed settings。當多個來源都設定此變數時，managed settings 的值會覆蓋 ~/.claude/settings.json 與 shell 匯出值，使用者無法把自我產生的行程指向別的啟動器。

若貴司是以個別鍵（而非 env 區塊）推送設定，可改用具名的頂層設定鍵（需 v2.1.210+）：

{
  "processWrapper": "/opt/corp/launcher"
}

📌 兩者都設定時，CLAUDE_CODE_PROCESS_WRAPPER 優先。

📌 由於 processWrapper 是具名設定，透過 remote managed settings 交付時，它會與其他「執行管理員提供之執行檔」的設定一起出現在安全核准對話框上（見 8.8.3 節）。

🚨 專案層設定無法設定啟動器。

一個 commit 進 repo 的檔案不得有能力在該機器上所有 Claude Code 行程前面塞一個二進位檔。因此 Claude Code 會忽略 .claude/settings.json 與 .claude/settings.local.json 中的 CLAUDE_CODE_PROCESS_WRAPPER（並在 debug log 留下警告），也從不從這些檔案讀取 processWrapper 鍵。

步驟三：重啟背景服務與所有 session

執行中的背景服務與已開啟的 claude session 只在啟動時讀一次變數，因此在重啟前會持續啟動未包覆的行程。

# 停止按需啟動的服務；下一個需要它的指令（如 claude agents）會啟動已包覆的服務
claude daemon stop --any

# 已安裝的服務則使用不帶 --any 的版本
claude daemon stop

然後重啟你已開啟的 claude session。

📌 無法手動重啟的機器：設定推送後啟動的第一個 session 會自動淘汰殘留的未包覆按需服務。沒有新 session 啟動的機器會一直保留未包覆的服務；而已安裝的服務永遠需要手動重啟。

8.9.4 🚨 啟動器契約（六條硬性規則）【Official】

當啟動器無法執行時，Claude Code 會拒絕啟動該行程，而不是改用未包覆的方式啟動。（Windows 例外——變數被忽略、行程未包覆啟動。）

啟動器值的格式（CLAUDE_CODE_PROCESS_WRAPPER 與 processWrapper 格式相同）：

• 多數情況就是腳本的絕對路徑，例如 /opt/corp/launcher。
• 要傳參數給啟動器，寫在路徑之後。Claude Code 把值解析為參數列表，而非 shell 指令：
  • 空白分隔 token，雙引號可group 含空白的 token。
  • 以 [ 開頭的值被當作 JSON 字串陣列讀取，例如 ["/opt/corp/launcher", "--profile", "cc"]。
  • ⚠️ Shell 語法無效：沒有變數展開、沒有 glob；未加引號的 ;、|、&、$( 等運算子會被視為設定錯誤拒絕，而不是重新解讀。

值無法使用時，Claude Code 會拒絕啟動受影響的行程並回報原因。

8.9.5 驗證【Official】

# 在 session 中：Self-exec 項目會顯示解析後的啟動指令，
# 並在執行中的背景服務與之不符時提出警告
/status

# 從 shell 印出相同資訊；即使在你 unset 變數之後
# （此時 /status 不再顯示該項目）仍可查看
claude daemon status

📌 行程監看工具中的名稱變化：設定啟動器後，ps 與 Activity Monitor 會顯示帶版本號的二進位檔名，而非 Claude Code 的 claude bg-pty-host 與 claude bg-spare 標籤——因為啟動器的 exec 重建了參數列表。這是副作用而非隱藏行為：行程本身沒有改變，且 Claude Code 一律以二進位檔路徑（而非顯示名稱）辨識自己的行程。

8.9.6 與 CLAUDE_CODE_SHELL_PREFIX 的差異【Official】

這兩者經常被混淆，而且為其中一個寫的啟動器無法當另一個用：