Readie.

佈建系列 · 01 核心佈建

核心佈建:在 Mac Mini 從零到能用

一份可照著跑的佈建參照。在一台 Mac Mini 上,從安裝、設定四層、一鍵腳本、組織護欄,到顯示、編輯器、遠端、登入、上線,讓全公司用同一套 Claude Code。

對象:要佈建 Claude Code 的人結果:團隊統一、可重複、約 20 分鐘

STEP 01佈建前提與安裝

Mac Mini 是台灣中小企業最划算的「常開 AI 主機」——一台放著,全隊共用、跑排程、接 LINE bot 都行。佈建第一步:把 Node 與 Claude Code 裝成全機一致的版本。授權細節見 STEP 08。

bash
# 1. Node 18+(建議用 nvm 鎖版本,全機一致)
#    若已用 Homebrew 安裝 node 亦可,跳過這步
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
export NVM_DIR="$HOME/.nvm"; . "$NVM_DIR/nvm.sh"
nvm install --lts && nvm alias default 'lts/*'

# 2. 全機安裝 Claude Code(再跑一次就是更新到最新版)
npm install -g @anthropic-ai/claude-code

# 3. 確認版本(fullscreen 需 v2.1.89+,/tui 指令需 v2.1.110+)
claude --version
版本策略:統一、設下限、一起升

兩件事分開看。Node:全隊用 nvm 對齊同一個 LTS,確保可重現。Claude Code 本身:它會自我更新,不要凍在舊版——你要的 fullscreen 等功能反而需要夠新(/tui 需 v2.1.110+)。正確做法是設一個版本下限、全隊透過同一支腳本更新;若要避免被自動更新打斷,再用DISABLE_AUTOUPDATER 統一控管升級時機。目標是「大家版本一致且夠新」,不是「鎖在某一版」。

STEP 02設定的四層與優先序(企業統一的關鍵)

這是個人教學最常漏、卻是企業佈建最重要的一件事:Claude Code 的設定有多層,高層蓋低層。搞懂它,才能「安全的事鎖死、習慣的事統一、專案的事跟著 repo 走」。

bash
# 設定檔由高到低(高的蓋低的):
# 1) 組織強制(managed)  /Library/Application Support/ClaudeCode/managed-settings.json
# 2) CLI 參數             claude --setting ...
# 3) 專案個人            <repo>/.claude/settings.local.json   ← 個人、不進 git
# 4) 專案共用            <repo>/.claude/settings.json         ← 進 git,全隊共用
# 5) 使用者              ~/.claude/settings.json              ← 每台機器各自,優先序最低

# 企業佈建心法:
#  · 安全護欄 → 放第 1 層 managed(使用者無法覆蓋)
#  · 團隊習慣(顯示、別名、權限預設)→ 放第 5 層 user,由佈建腳本寫入
#  · 專案規範 → 放第 4 層,跟著 repo 走
層級位置企業用途
① 組織強制 managed/Library/Application Support/ClaudeCode/managed-settings.json安全底線,使用者無法覆蓋(最高)
② CLI 參數claude --setting …臨時覆寫,少用
③ 專案個人repo/.claude/settings.local.json個人偏好,不進 git
④ 專案共用repo/.claude/settings.json專案規範,進 git 全隊共用
⑤ 使用者~/.claude/settings.json每台機器習慣設定(最低)

STEP 03團隊統一設定檔

下面這份放在第 5 層(user),由佈建腳本寫進每台機器,是「全隊共同習慣」:fullscreen 不閃、捲動速度、權限白名單(安全指令免確認、危險操作要問、金鑰檔禁讀)。權限的深入說明見安全與權限專頁。

json
{
  "tui": "fullscreen",
  "theme": "dark",
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(npm run *)",
      "Read"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./**/*.key)",
      "Read(./**/*.pem)"
    ]
  },
  "env": {
    "CLAUDE_CODE_SCROLL_SPEED": "3"
  }
}
更簡單的開法

不必手改檔——在任何對話裡輸入 /tui fullscreen(需 v2.1.110+),它會自動寫進設定並無痛重啟、對話不中斷。上面的settings.json 是給批次佈建多台機器用的;單人開關用指令最快。

STEP 04一鍵佈建腳本(這頁的核心)

把前面所有步驟串成一支可重複執行的腳本。存成 provision-claude-code.shchmod +x 後在每台 Mac Mini 跑一次即可。再跑一次只會補沒做的、不會弄壞既有設定。

bash
#!/usr/bin/env bash
# provision-claude-code.sh — 在 Mac Mini 佈建 Claude Code 團隊統一環境
# 可重複執行(idempotent):跑第二次只會補沒做的、不會弄壞既有設定
set -euo pipefail

# ── 1. Node(沒有就擋下,請先裝 nvm 或 brew install node)──
export NVM_DIR="$HOME/.nvm"; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
command -v node >/dev/null || { echo "✗ 找不到 Node,請先安裝(nvm / Homebrew)"; exit 1; }

# ── 2. 安裝或更新 Claude Code,並檢查版本下限 ──
MIN="2.1.110"   # /tui 等功能的下限;要凍結升級時機可另設 DISABLE_AUTOUPDATER=1
npm install -g @anthropic-ai/claude-code
CUR="$(claude --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
[ "$(printf '%s\n%s\n' "$MIN" "$CUR" | sort -V | head -1)" = "$MIN" ] \
  || { echo "✗ Claude Code $CUR 低於下限 $MIN,請更新後重跑"; exit 1; }
echo "✓ Claude Code $CUR(≥ $MIN)"

# ── 3. 寫入團隊統一 user 設定(安全 deep-merge,保留既有設定)──
mkdir -p "$HOME/.claude"
TEAM_SETTINGS='{"tui":"fullscreen","theme":"dark","env":{"CLAUDE_CODE_SCROLL_SPEED":"3"},"permissions":{"allow":["Bash(git status)","Bash(git diff:*)","Bash(npm run *)","Read"],"ask":["Bash(git push:*)"],"deny":["Read(./.env)","Read(./**/*.key)","Read(./**/*.pem)"]}}'
if [ -f "$HOME/.claude/settings.json" ]; then
  echo "$TEAM_SETTINGS" | jq -s '.[0] * .[1]' "$HOME/.claude/settings.json" - \
    > "$HOME/.claude/settings.json.tmp" && mv "$HOME/.claude/settings.json.tmp" "$HOME/.claude/settings.json"
else
  echo "$TEAM_SETTINGS" | jq . > "$HOME/.claude/settings.json"
fi
echo "✓ 已寫入 ~/.claude/settings.json"

# ── 4. cc 別名(已存在就不重複加)──
grep -q "alias cc=" "$HOME/.zshrc" 2>/dev/null || echo "alias cc='claude'" >> "$HOME/.zshrc"
echo "✓ cc 別名就緒(開新分頁或 source ~/.zshrc 生效)"

echo "── 完成。接著請各帳號執行一次 'claude' 完成登入 ──"

加上組織強制護欄

真正的企業統一靠這層:把「絕不允許」的事放進 managed-settings.json,使用者改不掉、關不了。為什麼這層才是真護欄,見安全與權限專頁。

bash
# 組織強制護欄:使用者無法覆蓋的安全底線(最高優先序)
#  需 sudo;只放「絕不允許」的事,不要放顯示偏好
sudo mkdir -p "/Library/Application Support/ClaudeCode"
sudo tee "/Library/Application Support/ClaudeCode/managed-settings.json" >/dev/null <<'JSON'
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./**/*.key)",
      "Read(./**/*.pem)",
      "Bash(rm -rf:*)",
      "Bash(curl:* | sh)"
    ]
  }
}
JSON
echo "✓ 組織護欄已佈署,全機使用者一致且無法關閉"

STEP 05顯示模式:fullscreen

預設模式每吐一字就重畫整頁——畫面狂閃、捲不上去、滑鼠難選、開久了吃記憶體。切到fullscreen(差分渲染、只畫可見內容)一次解決。注意這目前是官方研究預覽(research preview),行為可能調整。

bash
/tui fullscreen     # 開啟(會自動重啟並保留對話,最簡單)
/tui                # 查目前用哪個 renderer
/tui default        # 關閉,退回經典模式

# 完全停用(環境變數,連 tui 設定都蓋過)
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 claude

Fullscreen 與預設模式比較:

功能預設模式Fullscreen
畫面閃爍❌ 每字重畫整頁✅ 差分渲染,穩定
往上捲看歷史❌ 一直被拉回底部✅ 上捲自動暫停跟隨
記憶體用量❌ 隨對話增長✅ 恆定
滑鼠選取複製靠終端機原生✅ 拖曳選取、放開自動複製
Cmd/Ctrl+click 開檔勉強✅ 可開檔/開 URL(mac 按 Cmd、其他按 Ctrl)
搜尋整段對話終端機原生 Cmd+FCtrl+O 進 transcript,再按 / 搜(按 [ 倒回 scrollback 即可用 Cmd+F)

STEP 06外部編輯器(編輯長文字 / 貼上的大段內容)

貼一大段文字進去會變成 [Pasted text +20 lines] 無法再改。按 Ctrl+G 就能用編輯器開啟、改完存檔自動帶回——這在新版 Claude Code 已是內建動作chat:externalEditor),你要做的只是「指定它開哪個編輯器」。

企業佈建的關鍵選擇:預設用終端機編輯器,不要用 GUI 編輯器。因為 Mac Mini 多半是遠端 SSH 進去用,GUI 編輯器(CotEditor、VS Code)只會開在那台機器的實體螢幕上,SSH 使用者按了不會有反應。

bash
# 企業預設:micro(現代終端機編輯器,支援滑鼠、Ctrl+S 存檔,SSH 也能用)
brew install micro 2>/dev/null || true

# 指定 Ctrl+G 要開哪個編輯器(nano 為免裝備援;進階者可用 vim)
grep -q "EDITOR=" "$HOME/.zshrc" || echo "export EDITOR='micro'" >> "$HOME/.zshrc"
source "$HOME/.zshrc"

# Ctrl+G 已是內建動作,不需要 wrapper script:
#   按 Ctrl+G → 用 $EDITOR 開啟目前輸入 → 存檔關閉 → 內容自動帶回對話

選編輯器

編輯器設定適用
micro(建議)export EDITOR='micro'本機+SSH 都可,新手友善、有滑鼠
nanoexport EDITOR='nano'免安裝備援,本機+SSH
vimexport EDITOR='vim'進階者,本機+SSH
CotEditor / VS Codeexport EDITOR='code --wait'⚠️ 只限坐在機器前的本機使用者,SSH 下不可用
三個已知狀況

① 部分版本會自動偵測 IDE 而不一定吃 $EDITOR,佈建後請實測。 ② Ctrl+G 在 SSH 下開 GUI 編輯器會靜默失敗——所以才用終端機編輯器。 ③ 在 fullscreen(滑鼠捕捉)下按 Ctrl+G 偶有跳脫序列亂碼,遇到就改用終端機編輯器或暫時關 fullscreen。

STEP 07遠端 Mac Mini 的眉角(最容易踩雷)

Mac Mini 多半是放著、用 SSH 或 tmux 遠端進去操作——這正是 fullscreen 最容易出狀況的場景。先知道,省下半天除錯。

  • tmux 滑鼠:要在 ~/.tmux.conf set -g mouse on 滾輪才有效,否則滾動跑去控制 tmux。
  • tmux -CC 不相容:iTerm2 的 tmux 整合模式(tmux -CC)下別開 fullscreen,滑鼠會失效、雙擊可能弄壞畫面。一般 tmux 沒問題。
  • SSH 剪貼簿:選取的字透過 OSC 52 回傳,部分終端機預設擋掉(iTerm2 要開「允許存取剪貼簿」)。
  • 純鍵盤操作:若滑鼠捕捉在遠端很卡,設 CLAUDE_CODE_DISABLE_MOUSE=1——保留不閃與低記憶體,改回終端機原生選取。
  • SSH + tmux 會更閃:tmux 不支援同步輸出。若很明顯,直接在獨立分頁跑 Claude Code,別包在 tmux 裡。

STEP 08登入授權(個人 / 團隊 / 無頭機)

Claude Code 對團隊有完整方案,這是個人教學最常漏的一塊。挑符合你計費方式的一種即可。

bash
# 個人:執行 claude,瀏覽器登入(Pro / Max / Team / Enterprise 皆同)
claude

# 無頭 Mac Mini(SSH、開不了瀏覽器):產生一年期 OAuth token
claude setup-token
export CLAUDE_CODE_OAUTH_TOKEN="貼上 token"   # 放機器層環境或 secrets

# 走 API 計費 / 自動化:用金鑰,建議 apiKeyHelper 從 vault 動態取,不要硬寫
export ANTHROPIC_API_KEY="sk-ant-..."
  • 團隊/企業:用 Claude for Teams / Enterprise,成員各自用 Claude.ai 帳號登入;Enterprise 另有 SSO 與 managed policy(集中控管設定)。
  • 無頭 Mac Mini:SSH 進去開不了瀏覽器,用 claude setup-token 產生一年期 token,設成 CLAUDE_CODE_OAUTH_TOKEN
  • 金鑰管理:憑證存在 macOS Keychain;要輪替用 apiKeyHelper 從 vault 動態取,別把長期金鑰硬寫進設定檔。

STEP 09把知識也統一:CLAUDE.md

設定統一只是地基。真正讓 Claude Code 變戰力、且不綁在某個人腦袋裡的,是把工作守則寫成每個 repo 根目錄的 CLAUDE.md,跟著 git 走——等於每次對話自動載入的團隊守則。

markdown
# 專案說明(放在每個 repo 根目錄 CLAUDE.md,跟著 git 走)

## 這是什麼
一句話描述。技術棧、進入點、怎麼跑起來。

## 團隊規範
- 套件管理一律用 pnpm
- 改動前先讀相關檔案,不要憑空假設 API
- 提交訊息用繁體中文,一行摘要

## 絕不可做
- 不要碰 .env 與任何金鑰檔(managed 層已強制禁讀)
- 沒有人工確認前不要 git push

跨工具標準:AGENTS.md 橋接

AGENTS.md 是跨 AI 工具的開放標準(Cursor、Copilot、Devin… 都認)。但Claude Code 只讀 CLAUDE.md、不讀 AGENTS.md。團隊若同時用多種工具,做法是讓CLAUDE.md 去 import 既有的 AGENTS.md——一份來源、全工具一致,不必各寫各的。

markdown
# CLAUDE.md 內容:import 既有的 AGENTS.md,兩邊同一份來源
@AGENTS.md

## Claude Code 專屬(選填)
- src/billing/ 底下的改動用 plan mode

# 不需要 Claude 專屬內容時,直接 symlink 即可:
#   ln -s AGENTS.md CLAUDE.md

小提醒:跑 /init 時若 repo 已有 AGENTS.md(或 .cursorrules 等),它會讀進來整併。讓 Claude 能爬網、操作瀏覽器、查資料庫的 MCP 工具與金鑰治理,見MCP 工具標準化專頁。

STEP 10上線部署(選擇性)

用 Claude Code 做出來的工具要 24 小時可用、可分享,就得部署到雲端。平台不必綁特定家,依需求挑,重點是金鑰一律放平台環境變數、別 hardcode 進 repo

bash
# 選平台(依需求,不綁特定家):
#   純前端 / 靜態頁     → Cloudflare Pages 或 Vercel
#   有後端 / DB / 要常駐 → Vercel / Railway / Zeabur 擇一
# 鐵則:金鑰一律放平台環境變數,別 hardcode 進 repo

# 範例 A:Vercel(你現有官網、EECP 都在這)
npm i -g vercel && vercel deploy --prod

# 範例 B:Cloudflare Pages(靜態)
npm i -g wrangler && wrangler pages deploy ./dist

STEP 11驗證佈建成功與後續維護

bash
claude --version                              # 版本對不對
jq . ~/.claude/settings.json                  # 設定檔格式正確(會報錯就是壞了)
cat "/Library/Application Support/ClaudeCode/managed-settings.json"  # 護欄在不在
claude --version && cc                         # cc 別名能啟動

常見狀況

  • 設了還是閃:八成 JSON 壞了。用 jq . ~/.claude/settings.json 檢查;另外設定只在啟動時讀取,要完全關掉重開。
  • 功能不存在 / 指令無效:版本太舊。重跑佈建腳本即更新,或 npm install -g @anthropic-ai/claude-code
  • cc 找不到source ~/.zshrc 或開新分頁;確認用的是 zsh(echo $SHELL)。
  • 維護:定期重跑佈建腳本即同步全機版本與設定;護欄改動只需更新一份managed-settings.json

把工具變成戰力

佈建好環境,只是開始。
讓全公司真的用同一套,才是價值。

Readie 幫台灣中小企業把 AI 從「裝好了」帶到「天天在用、人人一致」——不換系統、不買新軟體,從你們每天已經在用的工具與一台 Mac Mini 開始。

Readie AI 導入顧問 · 創辦人 Marco Liu · 19 年產業經驗