ccam
繁體中文
文件常見問題GitHub

部落格

功能

檢查和修復

最後更新：2026年10月19日
已使用 ccam 0.6.0 和 Claude Code 2.1.302 驗證

本頁由英文機器翻譯而成，歡迎提供修正。 在 GitHub 上編輯此頁

本頁內容
  1. 用法
  2. 選項
  3. 運作方式
  4. 安全性和特殊情況
  5. 相關內容

ccam doctor 會檢查你的 ccam 安裝：Claude Code 執行檔、每個帳號的資料夾、登入和共用連結、共用的 MCP 伺服器、用量端點，以及你的快捷指令。ccam doctor --fix 會修復不會遺失資料的問題，並先把要取代的檔案移到備份資料夾。當 ccam <name> 因共用連結問題而停止、你手動還原檔案之後，或 Claude Code 更新之後，請執行它。

用法

ccam doctor                  # check everything, change nothing
ccam doctor --fix            # check, then repair what is safe to repair
ccam --dry-run doctor --fix  # report only: what --fix would repair

每項檢查結果是一行，前面有一個標記：✓ 正常、· 資訊、! 警告、✗ 錯誤。帳號的檢查結果以帳號名稱開頭。

$ ccam doctor
✓ Claude Code 2.1.302 (Claude Code) (/home/me/.local/bin/claude)
! personal: folder permissions are 755 (should be 0700)
! personal: .credentials.json permissions are 644 (should be 0600)
✓ personal: login valid (me@example.com)
✗ personal: /home/me/.local/share/ccam/profiles/personal/settings.json: set to shared but is a real file, not a link
· personal: unknown entries (Claude Code layout may have changed): newthing
! work: not logged in → `ccam login work`
✓ work: share links OK
! missing shortcuts in /home/me/.local/bin: ccp

`ccam doctor --fix` repairs what it can.

加上 --fix 時，每個已修復的項目結尾會加上 → fixed：

$ ccam doctor --fix
✓ Claude Code 2.1.302 (Claude Code) (/home/me/.local/bin/claude)
! personal: folder permissions are 755 (should be 0700) → fixed
! personal: .credentials.json permissions are 644 (should be 0600) → fixed
✓ personal: login valid (me@example.com)
✗ personal: /home/me/.local/share/ccam/profiles/personal/settings.json: set to shared but is a real file, not a link → fixed
· personal: unknown entries (Claude Code layout may have changed): newthing
! work: not logged in → `ccam login work`
✓ work: share links OK
! missing shortcuts in /home/me/.local/bin: ccp → fixed

選項

選項 作用 預設值
--fix 修復可以安全修復的問題（變更的檔案會先備份） 關閉
--dry-run（全域） 執行所有檢查，但不修復任何東西，即使加上 --fix 也一樣 關閉

ccam doctor 不接受參數。它支援 --dry-run：ccam --dry-run doctor --fix 會印出和 ccam doctor 相同的檢查結果，且不變更任何東西。

只要還有至少一個 ✗ 項目未修復，結束代碼就是 1，否則為 0。警告和資訊絕不會讓執行失敗。沒有加 --fix 而執行失敗時，ccam 最後會印出一行空白和 `ccam doctor --fix` repairs what it can.。無法載入設定時，也會以 1 結束並顯示 ccam: 錯誤。

運作方式

internal/cli/doctor.go 會載入 ~/.config/ccam/config.toml，並呼叫 internal/doctor/doctor.go 中的 doctor.Run；它以固定順序執行各項檢查並傳回結果。--fix 會以 Options.Fix 傳入，在試執行時設為 false。

中間的區塊會對每個帳號執行一次。各項檢查以及 --fix 對它們的處理如下：

  1. Claude Code 版本（checkClaude）。以和啟動器相同的方式找出 claude 執行檔，並執行 claude --version。如果版本不是以 2.1.302 開頭（這是 ccam 驗證資料夾結構時所用的版本，doctor.LayoutVersion），會加上 · ccam was verified against the folder layout of Claude Code 2.1.302. Any 'unknown entries' below may mean the layout changed。找不到執行檔或 --version 失敗則為錯誤。不修復。
  2. 環境變數中的登入資訊（checkAuthEnv）。設定了 CLAUDE_CODE_OAUTH_TOKEN、ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN 時發出警告：從該 shell 啟動的每個帳號都會繼承它，而且 Claude Code 會優先使用它，而不是帳號自己的登入。不修復；請自行取消設定。
  3. 資料夾（checkProfile）。帳號資料夾不存在時為錯誤，並結束該帳號的檢查。權限中設定了任何群組或其他使用者的位元時為警告；--fix 會執行 chmod 0700。
  4. 登入檔案（checkCredentials）。以 lstat 檢查 .credentials.json。符號連結是錯誤，因為每個帳號都必須有自己的權杖，而且不會修復。權限不是 0600 時為警告；--fix 會執行 chmod 0600。接著讀取登入資訊（在 macOS 上會先從鑰匙圈讀取）。沒有登入是警告，並提示使用 ccam login <name>。更新權杖過期是錯誤 login expired；存取權杖過期只是資訊，因為 Claude Code 會在下次啟動時更新它。這些都不會修復。
  5. 共用連結（share.Check）。只用 lstat 和 readlink，把 share.Layout 中的每個路徑和帳號的共用設定比對。它會回報四種情況：缺少連結、連結指向別處、應該是連結的地方是實際檔案，以及已改為 local 的項目仍殘留連結。缺少連結是警告，其他都是錯誤。
  6. 未知項目（checkUnknownEntries）。列出帳號資料夾中 ccam 不認得的頂層名稱（share.Known），作為 Claude Code 資料夾結構可能已變更的提示。僅供參考。
  7. 外掛路徑（checkPlugins）。外掛登錄檔（installed_plugins.json、known_marketplaces.json）儲存的是絕對路徑。在每個群組的 plugins/ 中，經過某個帳號資料夾的路徑會在該帳號被移除或重新命名時失效。--fix 會用 profile.RewritePluginPaths 把它們改寫為群組資料夾，以原子寫入的方式更新登錄檔。
  8. MCP 伺服器（checkMCP）。每個群組的 mcp.json 只載入一次。無法讀取的檔案是錯誤；未通過 mcp.Validate 的伺服器是警告。不修復。
  9. 用量回應格式（checkUsageFormat）。不使用快取，以一般的 3 秒限制逐一向用量端點查詢帳號，直到有一個回應為止。如果回應已經無法解析，它會警告 ccam usage 將改用狀態列的快取。這是唯一使用網路的檢查。
  10. 快捷指令（checkShims）。只在有帳號設定了快捷指令時執行。~/.local/bin 中缺少連結是警告；--fix 會呼叫 shim.Install，它只建立缺少的連結，絕不碰其他檔案。bin 資料夾不在 PATH 上時為警告，不會修復。

啟動流程會當場建立缺少的連結，但遇到任何可能遺失資料的情況就會停止，並提示你使用這個指令：

$ ccam work
ccam: stopped because of share link problems:
  /home/me/.local/share/ccam/profiles/work/CLAUDE.md: set to shared but is a real file, not a link
Repair them with `ccam doctor --fix`, then run again

遇到任何共用連結問題時，--fix 會以帳號的共用設定同時作為目前狀態和目標狀態呼叫 share.Build，再執行 Plan.Apply。Build 會根據磁碟上的實際內容重新推導每個步驟，產生的計畫和 ccam share 使用的相同，所以修復遵循的規則和開啟共用時一樣。

這裡的 settings.json 是實際檔案。因為群組已經有內容不同的 settings.json，衝突會採用預設選擇 KeepGroup，保留群組的副本。帳號的檔案會移到帳號資料夾內的 .ccam-backup/<time>/settings.json，並由 os.Symlink 把該路徑連結到群組。其他情況：

  • 如果群組還沒有副本，帳號的檔案會移到群組中，成為群組的第一份內容。
  • 如果是資料夾，群組沒有的檔案會移到群組中，其餘的放到備份。
  • history.jsonl 的預設方式是 merge by line：先是群組的各行，再接上你新增的各行。群組原本的副本會保存在 .ccam-backup/<time>/group/。
  • 指向其他群組的連結會被取代。指向 ccam 以外資料夾的連結會放到備份，如果群組是空的，就以其內容作為群組的初始內容。
  • 已改為 local 的項目所殘留的連結會被移除，帳號會取得一份群組內容的副本。

除了移除連結以外，每個步驟都是把資料移到群組或備份資料夾。不會刪除任何東西。

安全性和特殊情況

  • 單純執行 ccam doctor 絕不會變更任何東西。在腳本中若要確保不變更，請把 --dry-run 和 --fix 一起使用。
  • doctor --fix 不會檢查帳號是否正在執行。修復帳號的共用連結之前，請先結束該帳號的 Claude Code，因為工作階段會持續寫入這些檔案。
  • 如果共用修復失敗，ccam 會對該帳號回報 could not repair share links: <error>，並略過它的未知項目檢查。其他帳號仍會繼續檢查。
  • 如果 ccam share 中途失敗，它會先儲存目標設定，並告訴你用 ccam doctor --fix 完成。
  • 符號連結的 .credentials.json、過期的登入和環境變數中的登入資訊只會回報，絕不會變更。
  • 外掛登錄檔的改寫以原子方式寫入，但不會複製到 .ccam-backup/。

在 GitHub 上編輯此頁

本頁內容