設定檔、點檔案與套件管理器：那些以點開頭的檔案是什麼（Chinese original）

你裝好一個工具，教學說「打開 ~/.someconfig/config.yaml，把這一行改成…」。

你打開那個資料夾，什麼都沒看到。

檔案在那裡。它只是以 . 開頭，而這類檔案預設是隱藏的。

一、Dotfile：以點開頭的檔案

在 macOS 與 Linux 上，檔名以 . 開頭的檔案預設不顯示。這是一個很舊的慣例：這些檔案是給程式讀的設定，不是給你翻閱的內容，所以把它們藏起來避免干擾。

你會反覆遇到的幾個：

檔案	是什麼
`~/.zshrc`、`~/.bashrc`	終端機每次啟動時讀的設定（PATH、別名、環境變數）
`~/.gitconfig`	Git 的全域設定（你的名字、email）
`~/.ssh/`	SSH 金鑰所在的目錄，見網路是怎麼說話的
`~/.someconfig/config.yaml`	各種工具自己的設定

怎麼看到它們：

ls -a          # 終端機：-a 是 all，包含隱藏檔案

Finder 裡按 Cmd+Shift+.（句號）可以切換顯示隱藏檔案。Windows 檔案總管是「顯示」→「隱藏的項目」。

一個重要的習慣：改之前先備份。

cp ~/.zshrc ~/.zshrc.bak

設定檔改錯一個字，可能讓整個終端機啟動時報錯。有備份就是十秒鐘的事。

二、YAML：用縮排表達層級的格式

多數 AI 工具的設定檔是 YAML（副檔名 .yaml 或 .yml）。它長這樣：

model:
  provider: deepseek
  name: deepseek-chat
channels:
  telegram:
    enabled: true
    token: "123456:ABC"

對照同樣內容的 JSON：

{
  "model": { "provider": "deepseek", "name": "deepseek-chat" },
  "channels": { "telegram": { "enabled": true, "token": "123456:ABC" } }
}

YAML 用縮排表示「誰屬于誰」，JSON 用大括號。 YAML 讀起來像人寫的大綱，所以被廣泛用於設定檔。

YAML 最常見的三個錯誤

1. 縮排用了 Tab。

YAML 禁止用 Tab 縮排，只能用空格。 這是一個硬規則，違反就整份解析失敗，而且錯誤訊息常常只說「found character that cannot start any token」，不會說是 Tab 的問題。

多數編輯器可以設定「按 Tab 鍵插入空格」。如果不確定，把那一行刪掉重打，用空格。

2. 縮排不一致。

同一層的東西必須縮排同樣多。慣例是兩個空格：

channels:
  telegram:
    enabled: true
  discord:
    enabled: false      # 與 telegram 同層，縮排要一樣

3. 冒號後面沒有空格。

model:deepseek-chat     # 錯
model: deepseek-chat    # 對

為什麼 YAML 對空白字元特別敏感

因為縮排就是它的語法。JSON 用括號，所以你隨便換行排版都不影響含義；YAML 沒有括號，縮排就是唯一的層級資訊，所以一個多餘的空格會改變整份文件的結構。

除錯方法：多數工具有一個「檢查設定」的指令（例如 hermes config check、openclaw doctor）。改完設定先跑它，比啟動失敗後猜原因快得多。具體指令見該工具的官方文件 —— 不要憑記憶打，本站已經因為憑記憶寫指令而移除過四篇文章。

三、套件管理器：brew、apt 與其他

套件管理器就是「幫你裝軟體的軟體」。

它解決的問題是：一個工具通常依賴其他東西（某個函式庫、某個執行環境），手動一個個裝很容易漏、很容易版本不對、而且解除安裝時很難清乾淨。

系統	常見的套件管理器
macOS	Homebrew（指令是 `brew`）
Ubuntu / Debian	`apt`
Fedora / RHEL	`dnf`
Windows	`winget`（內建）；開發者常用 `choco` 或 `scoop`
Python 套件	`pip`、`uv`
Node.js 套件	`npm`、`pnpm`

Homebrew 是 macOS 上的事實標準，裝好之後：

brew install 工具名        # 裝
brew list                  # 看裝了什麼
brew upgrade               # 全部更新

它的一個設計值得知道：Homebrew 預設把東西裝在 /opt/homebrew（Apple Silicon）或 /usr/local（Intel Mac），而不是系統目錄 —— 這樣裝完之後你就不需要 sudo 了。如果你發現每次 brew 都要 sudo，通常是權限出問題。

為什麼有些工具的說明不用 brew

不是每個工具都在 Homebrew 上。 一個工具不在 brew 裡，不代表它不正規 —— 它可能只提供官方安裝腳本或桌面安裝包。

本站已經遇過這個坑：一篇文章教用 brew install 安裝某個 Agent 工具，而那條指令根本不存在。官方給的是安裝腳本與桌面包。所以：

永遠以官方文件的安裝方式為準。 如果官方給了安裝腳本，就用腳本；不要因為你習慣 brew 就假設有 brew 版本。

四、Script：把指令存起來重跑

腳本就是「一串照順序執行的指令，存在一個檔案裡」。

你原本在終端機一行一行打的東西，存成檔案就能一次跑完：

#!/bin/bash
cd ~/my-project
git pull
npm install
npm run build

第一行的 #!/bin/bash 叫 shebang，它告訴系統「用 bash 來跑我」。

要能執行它，需要兩件事：

chmod +x 檔名.sh      # 給它執行權限
./檔名.sh             # 執行（./ 是「這個目錄下的」）

為什麼這對 AI 工具有關：Agent 常常會幫你寫一個腳本。這時候你要知道兩件事：

執行前先讀一遍。 尤其是 curl … | bash 這種「下載一段腳本然後立刻用你的權限執行」的形式 —— 你完全不知道裡面寫了什麼。見終端機保命指南的「新手最貴的一個習慣」。
腳本失敗時，看它停在哪一行。 錯誤訊息通常會給行號。

五、Regex：你需要懂到什麼程度

正規表達式是一套描述「文字長什麼樣子」的記號，用來在大量文字裡找出符合某個模式的片段。

好消息：作為 AI 工具使用者，你幾乎不需要會寫 regex。 你需要的是看得懂別人寫的那一條在做什麼，因為你會在這些地方遇到它：

設定檔裡的過濾規則（「忽略符合這個模式的檔案」）
錯誤訊息（「路徑不符合 ^[a-z-]+$」）
Agent 的權限規則（「允許執行符合這個模式的指令」）

五分鐘夠用的四個符號：

符號	意思	例子
`^`	開頭	`^src/` = 以 `src/` 開頭
`$`	結尾	`\.mdx$` = 以 `.mdx` 結尾
`.`	任意一個字元	`a.c` = a 加任意一字加 c
`*`	前面那個東西零次或多次	`ab*c` = ac、abc、abbc

注意 . 在 regex 裡是「任意字元」，所以要表示真正的句點必須寫 \. —— 這就是為什麼你會看到 \.mdx 而不是 .mdx。

本站用 regex 做的一個實際例子：內容閘門檢查 markdown 連結是否指向存在的文章，用的模式是 \[([^\]]*)\]$(/[a-zA-Z0-9\-_/]+)$。你不需要看懂它，只需要知道這類規則可以被自動化 —— 這就是為什麼本站能在 470 個檔案上跑死鏈檢查，而不是一篇一篇人工看。

不要做的事：不要叫 AI「用 regex 幫我處理」然後不看結果。regex 很容易寫得比你想的更寬或更窄。先拿幾個例子驗證它，包括應該符合的與不該符合的。

見 Regex（正規表示式）。

六、把這些串起來

一個典型的「照教學設定工具」流程會用到全部五個：

1. 用套件管理器裝工具          （brew install / 官方腳本）
2. 找到它的設定檔              （通常是 ~/.something/config.yaml，隱藏的）
3. 先備份，再改                （cp config.yaml config.yaml.bak）
4. 用工具自己的檢查指令驗證     （doctor / config check）
5. 出錯時讀錯誤訊息的行號

第 4 步最常被跳過，而它最省事。 第 5 步怎麼讀，見怎麼讀錯誤訊息。設定錯誤在「檢查」階段會給你明確的訊息；在「啟動」階段通常只給你一個崩潰。

下一步

YAML / Dotfile（點檔案） / Homebrew（brew） / Script（腳本） / Regex（正規表示式） / Config File（設定檔）
開發環境設定 —— 把這些用在一個真實的環境上
裝完沒反應 —— 設定檔與 PATH 的問題在那裡有排查順序
怎麼讀錯誤訊息 —— 第 5 步
網路是怎麼說話的 —— ~/.ssh/ 與金鑰
Agent 到底看得到什麼 —— 為什麼設定檔裡的 key 需要保護