К основному содержанию
команда CX Codex официальный · Anthropic

debug · anthropics — команда для Claude Code, Codex, GitHub Copilot, Gemini CLI

Команда debug для Claude Code, диагностирующая ошибки развёртывания надстроек Excel, Word и PowerPoint. Применяется при сбоях подключения, неверных конфигурациях и отсутствии надстройки в приложении.

Apache-2.0 ★ 41 441 обновлён 2026-09-21

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add anthropics/financial-services
/plugin install claude-for-msft-365-install@claude-for-financial-services
Открыть на GitHub

Что делает debug

Эта команда помогает выявлять причины сбоев в работе надстроек. Она позволяет анализировать отчёты об ошибках, проверять параметры манифеста, сравнивать их с отправленными запросами и устранять проблемы с кэшированием конфигураций. Инструмент поддерживает ручную очистку кэша манифестов для macOS и Windows через специализированные сценарии, что ускоряет обновление настроек после внесения правок.

Команда требует использования вспомогательных файлов — scripts/clear-addin-cache.sh для macOS или scripts/clear-addin-cache.ps1 для Windows. Для работы необходимо знать идентификатор надстройки <Id>. Перед применением изменений обязательно полностью перезапускайте офисное приложение, так как запущенный процесс может блокировать обновление кэша.

Какие задачи решает

  • выявить причину сбоя подключения к серверу
  • сравнить параметры манифеста с фактическим запросом
  • удалить устаревшую конфигурацию надстройки
  • проверить текущую версию в панели администрирования

Примеры запросов агенту

  • /plugin:debug
  • Используй debug для анализа логов подключения
  • Запусти clear-addin-cache.ps1 -Id <GUID> -Apply для сброса кэша на Windows

Как установить debug

1Через маркетплейс плагинов

/plugin marketplace add anthropics/financial-services
/plugin install claude-for-msft-365-install@claude-for-financial-services

2Вручную: положить файлы

.claude/commands/debug.md

Вызов — /debug. Для всех проектов — ~/.claude/commands/

Вопросы о debug

Как установить debug?

Используйте последовательность команд /plugin marketplace add anthropics/financial-services и /plugin install claude-for-msft-365-install@claude-for-financial-services.

Что делает debug?

Диагностирует проблемы развёртывания надстроек, анализируя сообщения об ошибках и помогая сбросить локальный кэш конфигураций.

Что нужно для работы debug?

Необходим идентификатор надстройки <Id> и наличие скриптов очистки кэша scripts/clear-addin-cache.sh или scripts/clear-addin-cache.ps1.

Исходный текст

debug.md · Apache-2.0
---
description: Diagnose deployment issues (stale config, connect failures, missing add-in)
---

# Debug a Claude Office deployment

You are helping an enterprise admin diagnose why the deployed add-in isn't
working right. Start by asking **what's wrong**, then route.

## Triage

Ask the admin to describe the symptom. Route by answer:

| Symptom | Section |
|---|---|
| Updated the manifest but users still see old config | [Stale config after update](#stale-config-after-update) |
| Add-in shows "Connection failed" | [Read the error paste](#read-the-error-paste) |
| Add-in doesn't appear in Excel/PowerPoint at all | [Add-in not visible](#add-in-not-visible) |
| Want to test/iterate a manifest locally before deploying | [Sideload a manifest for local debugging](#sideload-a-manifest-for-local-debugging) |
| Sign-in popup fails or loops | [Admin consent](#admin-consent) |
| Need to see the browser console | [Opening browser devtools](#opening-browser-devtools-on-the-add-in) |

If they have an error paste from the add-in (the **Copy error details** button
on the connect-failed screen), always start there. It carries everything.

---

## Read the error paste

Paste structure:

```
Claude for Office connection failed (<Provider>)
Build: <sha>

<friendly message>

Request:
  <key>: <value actually sent>
  ...

Manifest params:
  <key>: <value the deployed manifest carries>
  ...

Raw error:
<SDK/HTTP error>
```

**What to check:**

- `Request:` vs `Manifest params:` delta. Keys are the same snake_case names
  in both blocks, so diff directly. If they differ, the user typed override
  values into the form. If they match, the manifest values went through
  unchanged.
- `Manifest params:` `m` key is the version tag (e.g. `unified-1.0.0.11`). If
  it's below what you last uploaded, the user is on a stale manifest. Go to
  [Stale config](#stale-config-after-update).
- `Raw error:` is the ground truth. Common patterns:
  - `invalid_client` (401, Google) → wrong `google_client_secret` for that
    `google_client_id`. Verify in GCP Console → Credentials.
  - `Load failed (<host>)` → network blocked at the WebView layer. Firewall
    needs to allow that host.
  - `STS AssumeRoleWithWebIdentity failed` → AWS IAM OIDC provider
    misconfigured or role trust policy wrong.
  - `HTTP 401/403` (gateway) → bad token or gateway rejected the key.

---

## Stale config after update

Two caches, two clocks:

| Layer | Who holds it | TTL | How to clear |
|---|---|---|---|
| Service | M365 Admin Center → Exchange Online → client | Up to **72h** for updates (24h for fresh deploys) | Wait, or redeploy with a fresh `<Id>` |
| Client | Office app's Wef folder on each machine | Until app restart, sometimes longer | Clear the cached manifests (see below) |

Microsoft's own FAQ:
> It can take up to 72 hours for add-in updates, changes from turn on or turn off to reflect for users.
> https://learn.microsoft.com/en-us/microsoft-365/admin/manage/centralized-deployment-faq

### Confirm what Admin Center is serving

Admin Center silently ignores re-uploads with the same `<Version>`. If you
uploaded a fix without bumping the fourth segment, it never took. Open M365
Admin Center → Integrated apps → your add-in → check the listed version.

### Force a client-side refresh

A stale **sideloaded** manifest is stored differently per platform:

- **macOS** — a file `<addin-id>.manifest-*.xml` in each app's
  `Documents/wef` folder, alongside every other add-in.
- **Windows** — a **registry** value under
  `HKCU:\SOFTWARE\Microsoft\Office\16.0\Wef\Developer` (there is no
  per-add-in file to delete; clearing the `Wef` *folder* is a different,
  blunter operation — see the caveat below).

Use the helper scripts. They target **only** your add-in's `<Id>` and do
direct `rm`/registry edits — they do **not** shell out to
`office-addin-dev-settings` (its removal path has burned us on customer
calls):

- macOS: [`scripts/clear-addin-cache.sh`](../scripts/clear-addin-cache.sh)
- Windows: [`scripts/clear-addin-cache.ps1`](../scripts/clear-addin-cache.ps1)

Quit Excel/Word/PowerPoint first. The scripts are **ID-first** — pass the
add-in `<Id>` directly (handy when iterating across new/multiple IDs); the
manifest path is an optional convenience that just reads `<Id>` for you.

```bash
# macOS — list everything, do nothing:
./scripts/clear-addin-cache.sh

# Dry-run by ID (preferred), or via the manifest:
./scripts/clear-addin-cache.sh --id <GUID>
./scripts/clear-addin-cache.sh ~/path/to/manifest.xml

# Actually remove (only this ID's files):
./scripts/clear-addin-cache.sh --id <GUID> --apply
```

```powershell
# Windows — same flow, registry-scoped:
.\scripts\clear-addin-cache.ps1                  # list, do nothing
.\scripts\clear-addin-cache.ps1 -Id <GUID>       # dry-run
.\scripts\clear-addin-cache.ps1 -Id <GUID> -Apply
```

Both **dry-run by default** — nothing is removed without `--apply` /
`-Apply`. No-args lists every registered add-in so you confirm the ID
first. Other add-ins are never affected.

If the ID matches nothing the script says **NOT cleared** and exits non-zero
— that means a typo or an already-removed add-in, *not* success. Re-run with
no arguments and copy the ID from the list. Don't escalate to a folder-wide
wipe on the strength of a miss here.

**Neither script can touch the user's data.** Chat history, skills, MCP
registrations, and memory are stored by the WebView, keyed by the origin the
add-in is served from — not by add-in ID. On macOS that's a different subtree
from the manifests (`Data/Library/WebKit/WebsiteData` vs `Data/Documents/wef`);
on Windows the clear script only ever writes to `HKCU`, never to disk. Clearing
the manifest by ID is safe to do on a machine whose history matters.

**You must fully restart the Office app after clearing.** Removing the
file/registry entry does nothing until the app re-reads it on launch — and
a *backgrounded* app counts as still running. Quit **and reopen** Excel /
Word / PowerPoint, confirming no lingering process first:
`pkill -f "Microsoft Excel"` (macOS) / check Task Manager (Windows). The
script also prints this reminder when it finishes.

**Deleting local/sideloaded manifests by ID is safe and works.** In
practice, removing just the one add-in's file (macOS) or registry value
(Windows) cleanly drops that add-in and leaves the rest loading normally —
we do this routinely. Microsoft's "don't delete individual files" warning
is about a *different* cache (below), not these local dev/sideload entries;
don't let it scare you off the surgical path here.

> **Centrally-deployed (Admin Center) staleness on Windows** is a
> *different* cache: `%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\<guid>\…`,
> stored under opaque hashes, **not** by add-in ID. Microsoft's official
> guidance is conservative — clear that folder's contents as a whole
> because *"deleting individual manifest files can cause all add-ins to
> stop loading."* In practice targeted deletion there can work too, but
> the filenames aren't ID-mapped so it's hard to be surgical — which is
> why these scripts deliberately do **not** touch it. If a
> centrally-deployed update is
> stale, prefer waiting out the service TTL or redeploying with a fresh
> `<Id>` (below) over hand-deleting that cache.
>
> ⚠️ **On Windows that wipe is destructive.** The add-in's chat history,
> skills, MCP registrations, and memory live *inside* the same tree
> (`%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\webview2\…`), and Anthropic
> cannot restore them. The widely circulated "just delete the `Wef` folder"
> fix deletes the user's conversations along with the manifest cache. If
> anyone is about to do it, run
> [`:export-data`](export-data.md) first.

If it's still stale after the restart, the service-side cache hasn't caught
up. Wait, or use a fresh `<Id>` (below).

Microsoft's cache-clear doc: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/clear-cache

### Nuclear option: redeploy with a fresh Id

If 72h is unacceptable, a fresh `<Id>` UUID forces Admin Center and every
client to treat it as a brand-new add-in (24h fresh-deploy SLA, usually much
faster). Edit `manifest.xml`, replace the text inside `<Id>` with a new UUID
(`uuidgen` on mac/linux, `[guid]::NewGuid()` in PowerShell), re-upload.

---

## Add-in not visible

- **Not in the ribbon:** Check M365 Admin Center → Integrated apps → your
  add-in → Users tab. Is the user (or their group) assigned? Nested groups
  aren't supported.
- **Shows "My Add-ins" but not the ribbon button:** The manifest's `<Hosts>`
  may not include this app. Check both `<Hosts>` lists (top-level and under
  `<VersionOverrides>`).
- **Fresh deploy, been <24h:** Normal. Microsoft's SLA is 24h for first-time
  deployment visibility.

---

## Sideload a manifest for local debugging

For iterating on a manifest **without going through Admin Center deployment**
(no 24–72h cache wait), point Office at a local manifest file directly. The
manifest stays wherever it is on disk; you just tell Office where to find it.
Pick the recipe for the customer's OS.

Use the helper scripts — they read the `<Id>` from the manifest and
install it the right way per platform (macOS: a `<Id>.manifest.xml` file in
each app's `Documents/wef`; Windows: a registry value under
`HKCU:\SOFTWARE\Microsoft\Office\16.0\Wef\Developer` named by the `<Id>`).
Both do direct file/registry writes — **not** `office-addin-dev-settings`.

- macOS install: [`scripts/sideload-addin.sh`](../scripts/sideload-addin.sh)
- Windows install: [`scripts/sideload-addin.ps1`](../scripts/sideload-addin.ps1)
- Remove (either OS): `clear-addin-cache.{sh,ps1}` — see
  [Force a client-side refresh](#force-a-client-side-refresh)

```bash
# macOS — installs directly:
./scripts/sideload-addin.sh ~/path/to/manifest.xml
```

```powershell
# Windows — installs directly:
.\scripts\sideload-addin.ps1 C:\path\to\manifest.xml
```

Sideloading is additive and idempotent, so it installs directly — **no
dry-run** (unlike the destructive `clear-addin-cache`, which stays dry-run
by default). The install names the entry by the add-in `<Id>`, so removal
later is the exact inverse: `clear-addin-cache.{sh,ps1} --id <GUID>
--apply` (the sideload script prints the precise remove command on
completion).

Then **fully quit and reopen** Excel / Word / PowerPoint — check Task
Manager (Windows) / `pkill -f "Microsoft Excel"` (macOS) first; a
backgrounded app won't re-read the registry or rescan the folder. The
add-in appears under **Insert → My Add-ins** (Windows also shows it on the
**Home** tab / **Shared Folder** group); pin it.

**Notes (both platforms):**
- This is per-user and per-machine — it doesn't touch tenant deployment. It's
  purely for the customer to debug/iterate on their own box.
- A locally sideloaded manifest **wins over** a centrally deployed one with
  the same `<Id>`, so this is also a fast way to test a manifest fix before
  re-uploading to Admin Center.
- Pair this with [browser devtools](#opening-browser-devtools-on-the-add-in)
  to see console/network while iterating.
- If a stale copy keeps loading, also clear the cache — see
  [Force a client-side refresh](#force-a-client-side-refresh).

Microsoft's sideloading references:
- Windows: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/create-a-network-shared-folder-catalog-for-task-pane-and-content-add-ins
- macOS: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/sideload-an-office-add-in-on-mac

---

## Admin consent

If the user sees a sign-in popup that closes immediately or loops, the tenant
hasn't granted admin consent to the Claude app. Run
[`:consent`](consent.md) to generate the consent URL for a Global Admin to
approve. The symptom in error pastes: `user_canceled` in the raw error (the
broker maps any unclassifiable close to that).

---

## Silent SSO / Entra token failures

- **`AADSTS50194: …not configured as a multi-tenant application` /
  `Use a tenant-specific endpoint`** — your `graph_client_id` (or the
  `entra_scope` resource app) is a single-tenant app, and the add-in build is
  old enough to still request tokens against the `/common` authority. Newer
  builds resolve a tenant-specific authority automatically when
  `graph_client_id` is set. Fix: have users update to the latest add-in
  version. There is no manifest workaround on an old build.
- **`entra_scope requires graph_client_id`** — `entra_scope` was set without
  `graph_client_id`. Custom-scope access tokens must be issued by your own
  Entra app, not the default; set both. The build script also rejects this
  pairing.
- **Silent SSO fails, then an interactive popup works** — expected on first
  run before a service principal exists in the tenant. Once admin consent is
  granted (see above) the silent path succeeds.

---

## Opening browser devtools on the add-in

When you need the WebView's console — JS errors, network tab, the add-in's
debug logs — you have to attach the host OS's browser devtools. The add-in runs
in an embedded WebView with no address bar and no built-in F12, so each OS
has its own recipe.

### macOS (Safari Web Inspector)

Three gates. **Gate 3 is the one everyone misses.**

1. **Office developer extras** — quit the app first, then:
   ```bash
   defaults write com.microsoft.Excel OfficeWebAddinDeveloperExtras -bool true
   defaults write com.microsoft.Powerpoint OfficeWebAddinDeveloperExtras -bool true
   defaults write com.microsoft.Word OfficeWebAddinDeveloperExtras -bool true
   ```
   Makes right-click → **Inspect Element** appear inside the task pane.

2. **Safari Develop menu** — Safari → Settings → Advanced → check *Show
   features for web developers*.

3. **macOS Developer Tools allowlist** (Sonoma and later) — System Settings
   → Privacy & Security → Developer Tools → toggle **Terminal** on. Without
   this, Safari's Develop menu shows *"No Inspectable Applications"* even
   with gates 1 and 2 open.

With the task pane open, either right-click inside it → **Inspect Element**,
or go to Safari → Develop → *[your machine name]* → find the add-in host
(`pivot.claude.ai` in prod, your configured domain otherwise).

**Gotchas:**
- **Office updates silently reset gate 1.** If inspection worked last week
  and doesn't now, re-run the `defaults write`.
- *"No Inspectable Applications"* = gate 3 missing, or the Office app wasn't
  fully quit before `defaults write`. `pkill -f "Microsoft Excel"` then
  relaunch.
- The task pane has to be **open** (not just the app) for it to appear under
  Safari's Develop menu.

### Windows (Edge DevTools)

Depends on which WebView engine Office is using. Current M365 on Win10/11
with the WebView2 runtime gets Chromium; older perpetual Office or machines
without the runtime may still be on IE11/Trident.

**WebView2 (Chromium — the common case):**

Right-click inside the task pane → **Inspect**. That's it, no gates. If
right-click doesn't show Inspect, install **Microsoft Edge DevTools
Preview** from the Microsoft Store — it lists all attachable WebView2
targets including Office add-ins. Launch it, find the add-in's URL in the
target list, click to attach.

**IE11/Trident (legacy Office 2019/2021 perpetual):**

Run the IEChooser from an admin PowerShell:
```powershell
& "C:\Windows\SysWOW64\F12\IEChooser.exe"
```
Pick the add-in's page from the list. If the list is empty, the task pane
isn't open yet — open it first, then refresh IEChooser.

Microsoft's walkthrough: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/debug-add-ins-using-devtools-edge-chromium

© Anthropic · Apache-2.0 · anthropics/financial-services

Похожие слэш-команды

Все слэш-команды по теме «Настройка агента: память, контекст, субагенты» →

Сначала — debug от других авторов.

debug Lex Christopherson Команда debug для Claude Code передаёт описание ошибки скиллу debug-like-expert для расследования. Она запускает методичный разбор конкретной проблемы. CX Codex +1 ★ 1 988звёзд репо doca-debug NVIDIA Скилл doca-debug для Claude Code разбирает сбои DOCA по слоям: установка, сборка, линковка, запуск и драйвер. Разбирает ошибки символов, DOCAERROR и пустой вывод инструментов. CX Codex +1 162установок deployment Railway Скилл deployment для Claude Code управляет релизами в Railway: читает логи сборки, перезапускает контейнеры и снимает деплои. Помогает разбирать сбои сервиса и смотреть историю выкаток. CX Codex +1 69установок render-debug Render Скилл render-debug разбирает упавшие деплои на Render по логам, метрикам и состоянию базы, находит причину и предлагает правку. CX Codex +1 617установок smart-fix Seth Hobson Команда smart-fix для Claude Code, которая запускает цепь специализированных агентов для анализа и исправления production-проблем. CX Codex +1 ★ 126звёзд репо cmux-debugging manaflow-ai Скилл cmux-debugging для Claude Code и других платформ: добавляет отладочные логи и диагностирует проблемы UI и рантайма в cmux — терминальный рендеринг, вкладки, drag-and-drop, разные версии macOS. CX Codex +1 5 000установок ccam-devtools Son Nguyen Плагин ccam-devtools для Claude Code помогает отлаживать сессии Claude Code Agent Monitor, проверять хуки и экспортировать данные мониторинга. CX Codex ★ 1 198звёзд репо

Из того же набора116

Весь набор →
setup Команда setup настройки для Claude Code, проводящая администратора через подключение надстройки Claude Office к облачной инфраструктуре. CX Codex +1 ★ 41 441звёзд репо manifest Команда manifest для Claude Code собирает XML-манифест надстройки с настройками облачного провайдера. Для Outlook она выбирает отдельный шаблон, а перед развёртыванием требует согласия администратора Microsoft Graph. CX Codex +1 ★ 41 441звёзд репо export-data Команда export-data для Claude Code копирует локальную историю чатов, скиллы и настройки надстройки перед пересборкой машины. CX Codex +1 ★ 41 441звёзд репо entra-app Команда entra-app для Claude Code описывает регистрацию приложения Microsoft Entra в собственном тенанте. Она помогает настроить вход для Outlook, шлюза, Foundry или sovereign cloud. CX Codex +1 ★ 41 441звёзд репо consent Команда consent для Claude Code подготавливает согласие администратора Azure для Entra SSO и доступа Outlook к Microsoft Graph. Администратор арендатора открывает ссылку и подтверждает разрешения. CX Codex +1 ★ 41 441звёзд репо bootstrap Команда bootstrap для Claude Code, которая настраивает endpoint для динамической конфигурации и управления серверами MCP. Запускается при инициализации расширения для загрузки параметров пользователей. CX Codex +1 ★ 41 441звёзд репо access-policies Помогает собрать конфигурацию access_policies в формате IAM. Администратор настраивает правила доступа надстройки к файлам с метками конфиденциальности. CX Codex +1 ★ 41 441звёзд репо verify Скилл verify для Claude Code проверяет административные скрипты и команды для пакета claude-for-msft-365-install в изолированном каталоге. Запускается при проверке изменений в скриптах управления. CX Codex +1 ★ 41 441звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой