debug · anthropics — команда для Claude Code, Codex, GitHub Copilot, Gemini CLI
Команда debug для Claude Code, диагностирующая ошибки развёртывания надстроек Excel, Word и PowerPoint. Применяется при сбоях подключения, неверных конфигурациях и отсутствии надстройки в приложении.
Apache-2.0 ★ 41 441 обновлён 2026-09-21
/plugin marketplace add anthropics/financial-services
/plugin install claude-for-msft-365-install@claude-for-financial-servicesЧто делает 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-services2Вручную: положить файлы
.claude/commands/debug.mdВызов — /debug. Для всех проектов — ~/.claude/commands/
Вручную: положить файлы
~/.codex/prompts/debug.mdВызов — /prompts:debug. В Codex этот формат помечен устаревшим, замена — скиллы
Вручную: положить файлы
.github/prompts/debug.prompt.mdВручную: положить файлы
.gemini/commands/debug.tomlGemini хранит команды в TOML: текст запроса — в поле prompt
Вопросы о 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 от других авторов.