Перевірка та виправлення

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

Параметри

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 і викликає doctor.Run у internal/doctor/doctor.go, який виконує перевірки у фіксованому порядку й повертає результати. --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: кожен обліковий запис, запущений із цієї оболонки, успадковує змінну, і Claude Code віддає їй перевагу над власним входом облікового запису. Без виправлення; видаліть змінну самостійно.
3. Тека (checkProfile). Відсутня тека облікового запису є помилкою й завершує перевірки цього облікового запису. Права доступу з будь-якими бітами для групи чи інших є попередженням; --fix виконує chmod 0700.
4. Файл входу (checkCredentials). .credentials.json перевіряється через lstat. Символьне посилання є помилкою, бо кожен обліковий запис повинен мати власний токен, і не виправляється. Режим, відмінний від 0600, є попередженням; --fix виконує chmod 0600. Потім зчитується вхід (на macOS спершу з в'язки ключів). Відсутність входу є попередженням, що вказує на ccam login <name>. Прострочений токен оновлення дає помилку login expired; прострочений токен доступу є лише інформацією, бо Claude Code оновить його під час наступного запуску. Жодне з цього не виправляється.
5. Спільні посилання (share.Check). Порівнює кожен шлях у share.Layout з налаштуваннями спільного використання облікового запису, використовуючи лише lstat і readlink. Повідомляє про чотири випадки: відсутнє посилання, посилання, що вказує не туди, справжній файл там, де має бути посилання, і залишене посилання для елемента, який тепер локальний. Відсутнє посилання є попередженням, інші випадки — помилками.
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 іде до резервної копії, а його вміст стає початковим вмістом групи, якщо група порожня.
• Посилання, залишене для елемента, який тепер локальний, видаляється, і обліковий запис отримує копію вмісту групи.

Окрім видалення посилань, кожен крок переміщує дані до групи або до теки резервних копій. Нічого не видаляється.

Безпека та граничні випадки

• Звичайний 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/.

Пов'язані сторінки

• Спільні сервери MCP, налаштування та історія
• Копіювання наявного налаштування
• Ліміти використання та перемикання облікових записів
• Команди