> ## Documentation Index
> Fetch the complete documentation index at: https://openworklabs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnostic prompts

> Paste-able prompts that let your agent debug OpenWork issues on its own.

When something in OpenWork looks wrong, the fastest debugger is usually the agent itself: it can read its own configuration, probe servers, and verify fixes in-band. This page collects paste-able diagnostic prompts. Copy the whole block for your situation into a chat and let the agent work through it.

Each prompt is safe by default: it gathers evidence first, redacts secrets, and asks before changing anything.

## 1. Cloud search shows old or missing capabilities

**Symptoms**

* `search_capabilities` returns fewer tools than you expect (for example, only `postCapabilitiesGoogleWorkspaceGmailDrafts` when newer Google Workspace capabilities should exist).
* `execute_capability` returns `unknown_capability` for a tool name that should exist.
* The cloud dashboard says a connection is "Connected as you", but the agent reports `connected: false`.

**What is usually wrong**

Your agent's `openwork-cloud` MCP entry is a snapshot: it stores a server URL and token from the moment it was connected. If it was created against a local development server or an old deployment — including via a leftover `desktop-bootstrap.json` file that overrides server URLs beneath the Settings UI — the agent keeps querying that old world forever, while the dashboard shows the current one.

**Paste this to your agent**

```text theme={null}
Debug and fix my OpenWork Cloud MCP connection. It may be pointed at a stale or local server instead of my real OpenWork Cloud server. Work through ALL phases, show your findings after each, and ask before anything destructive. Never print bearer tokens or Authorization headers — redact them.

My expected cloud web URL: https://app.openworklabs.com (replace with your self-hosted Den web URL if you run your own).

## Phase 1 — Evidence: what am I actually connected to?

1. Print the `openwork-cloud` MCP entry's `url` (redact headers) from every config you can find:
   - `~/.config/opencode/opencode.json`
   - any `.opencode/opencode.json` or `opencode.jsonc` in the current project
   - your own runtime config if you have an export tool
2. Inspect these files if they exist (they can silently override server URLs beneath the Settings UI), but report only `baseUrl`, `apiBaseUrl`, `requireSignin`, and `writtenAt`. Never print `handoff`, `claimLinks`, grants, tokens, or other credential-bearing fields:
   - `~/.config/openwork/desktop-bootstrap.json`
   - `~/Library/Application Support/com.differentai.openwork/desktop-bootstrap.json`
3. If the url from step 1 is a localhost address, find what serves that port:
   - `lsof -nP -iTCP:<port> -sTCP:LISTEN`
   - for each PID: `ps -p <PID> -o pid=,command=` and `lsof -a -p <PID> -d cwd -Fn | tail -1`

## Phase 2 — Probe both servers directly (no auth needed)

4. The server from Phase 1, through the Den web proxy:
   `curl -s -m 5 <that-origin>/api/den/openapi.json | python3 -c "import json,sys; d=json.load(sys.stdin); ps=[p for p in d.get('paths',{}) if 'google-workspace' in p]; print(len(ps)); [print(p) for p in ps]"`
5. The expected cloud web URL, same command. Compare the two lists.

## Phase 3 — Probe through your own MCP tools (in-band ground truth)

6. Call search_capabilities with {"query":"google workspace","limit":10} and report the match names.
7. Call execute_capability with {"name":"getCapabilitiesGoogleWorkspaceCalendarEvents"} and report the exact error or result shape.

## Phase 4 — Diagnose

State which world you are in:
- openwork-cloud url is localhost/127.0.0.1, OR search returned only gmail-drafts, OR execute returned unknown_capability → you are bound to a STALE server, not the expected cloud.
- a desktop-bootstrap.json contains localhost URLs → that file is the root cause (it is the desktop app's Cloud URL source of truth).

## Phase 5 — Fix (confirm with me before each destructive step)

8. If a desktop-bootstrap.json contains stale/localhost URLs: show it, then delete that file.
9. If a stale local server process is still listening: show the process, then stop it, so nothing can silently serve old answers again.
10. Tell me to do these steps in OpenWork, then wait:
    - Restart the OpenWork app.
    - In the affected workspace, open Settings → Extensions and click Refresh (re-mints the token and rewrites the Cloud MCP config).
    - Click Show hidden, then verify OpenWork Cloud Control under Your apps.
    - Run Reload OpenCode config from the command palette.
    - Start a NEW task so it receives the current tool set.

## Phase 6 — Verify (run in the NEW session)

11. search_capabilities {"query":"google workspace","limit":10} → PASS = the full current capability set (calendar, drive, and gmail capabilities ranked on top), not just drafts.
12. execute_capability {"name":"getCapabilitiesGoogleWorkspaceCalendarEvents","query":{"timeMin":"<today ISO>","timeMax":"<+3 days ISO>"}} → PASS = real events, or a clean needs_connection / missing-permission message — NOT unknown_capability.
13. Print a final report: root cause, what changed, and the before/after of probes 6/7 vs 11/12.
```

**Expected passing state**

* The `openwork-cloud` entry's `url` points at your real server and ends in `/mcp/agent` (either a direct API host or the web app's `/api/den` proxy).
* `search_capabilities` reflects your server's current catalog.
* `execute_capability` on a known capability returns data or an actionable connection message — never `unknown_capability`.

If the agent completes all phases and verification still fails, [open an issue](https://github.com/different-ai/openwork/issues) and paste the agent's final report (it is already redacted).

## 2. Cloud MCP is configured, but its tools are missing

**Symptoms**

* Settings shows an `openwork-cloud` MCP entry, but the agent calls `openwork_docs_search` for requests involving connected services.
* The agent claims that `search_capabilities` and `execute_capability` are only "conceptual capabilities" rather than callable tools.
* A connected service such as ServiceNow appears ready in OpenWork Cloud, but the task does not expose `openwork-cloud_search_capabilities` or `openwork-cloud_execute_capability`.

**What this diagnostic checks**

The prompt below runs OpenWork's bundled OpenCode executable against its generated runtime config and checks whether a fresh OpenCode process can connect to `openwork-cloud`. It does not attach to the OpenCode server already running inside OpenWork, so it combines that result with the live status shown in OpenWork and a forced tool call from a new task.

**Paste this to your agent**

```text theme={null}
Diagnose whether OpenWork Cloud MCP tools are available in this workspace. Gather evidence only: do not modify configuration, authenticate, log out, remove anything, restart services, or print configuration-file contents.

## Phase 1 — Test the task's actual tools

1. Attempt to call `openwork-cloud_search_capabilities` with `{"query":"ServiceNow incident","type":"mcp","limit":10}`. Do not use documentation or explain alternatives. Record whether the runtime accepts the tool call and its exact non-secret result or rejection.
2. Attempt to call `openwork_extension_list_actions`. Record whether the runtime accepts the call. Do not infer tool availability from an answer to "list your tools"; models can omit or invent tools.

## Phase 2 — Find OpenWork's exact OpenCode runtime

3. Detect whether this machine is Windows, macOS, or Linux.
4. Find the exact OpenCode executable used by the OpenWork desktop app. Prefer the bundled executable in OpenWork's `resources/sidecars` directory; do not assume an unrelated `opencode` on `PATH` is the same binary. If multiple OpenWork builds are running, use the process associated with this task when that can be established safely; otherwise report the ambiguity.
5. Find OpenWork's generated `runtime-opencode-config.json` beside the active `server.json`. Respect discovered `OPENWORK_SERVER_CONFIG`, `OPENWORK_RUNTIME_DB`, or XDG overrides. Typical locations are:
   - Windows: `%APPDATA%\openwork\runtime-opencode-config.json`
   - macOS/Linux: `${XDG_CONFIG_HOME:-$HOME/.config}/openwork/runtime-opencode-config.json`
6. Report whether the runtime config exists and its last-modified time. Never display, copy, parse, or summarize its contents: it can contain Authorization headers and other credentials.

## Phase 3 — Run a safe fresh-process probe

7. From this task's workspace root, set `OPENCODE_CONFIG` to the discovered runtime config for the subprocess only, then run:
   - `<exact-opencode-executable> --version`
   - `<exact-opencode-executable> mcp list`
8. Do not run `mcp add`, `mcp auth`, `mcp logout`, `debug config`, or any command that changes or prints configuration. Do not use `--print-logs` if it could expose headers or tokens.
9. Report:
   - operating system
   - exact OpenCode executable path and version
   - runtime config path, existence, and last-modified time
   - whether `openwork-cloud` is listed
   - its exact status and non-secret error
   - whether the failing workspace is the primary managed workspace or may be a secondary workspace configured dynamically

Important: `opencode mcp list` starts a fresh process. Do not claim that it attaches to or tests the OpenCode server already running inside OpenWork. Describe it only as a fresh-process probe using the same binary and generated config.

## Phase 4 — Classify the result

- Fresh probe omits `openwork-cloud`: the generated config is missing, the wrong runtime config was selected, or this is a secondary workspace whose MCPs are registered dynamically.
- Fresh probe reports `failed` or `needs_auth`: preserve the exact non-secret error; investigate token, endpoint, TLS, or authentication.
- Fresh probe reports `connected`, but Phase 1 rejects the Cloud tool: the stored endpoint and token work, but the live desktop engine or task has stale/missing tool registration.
- Both Phase 1 calls are rejected: investigate whether the running engine loaded the injected config and plugins, plus project/global tool-deny policy.
- The forced Cloud call works, but a natural request chooses documentation: tool exposure is healthy; investigate system-prompt steering.

Finish with a concise redacted report. Never reveal bearer tokens, Authorization values, cookies, passwords, API keys, local server tokens, or strings beginning with `ow_mcp_at_`.
```

**Verify inside OpenWork**

1. In the affected workspace, open **Settings → Extensions** and click **Refresh**.
2. Click **Show hidden**, then find **OpenWork Cloud Control** under **Your apps**. This row shows live OpenCode MCP status; the catalog card only proves that the entry is configured.
3. Expand the row and retain its status and non-secret error: **Ready**, **Issue**, **Sign in needed**, **Offline**, or **Paused**.
4. Return to the task, open the command palette, run **Reload OpenCode config**, and create a new task in the same workspace.
5. Repeat the forced Cloud tool call from Phase 1.

**How to interpret both results**

| Fresh `opencode mcp list` | OpenWork status / forced call                   | Likely boundary                                           |
| ------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
| Missing or failed         | Missing or failed                               | Generated config, endpoint, token, TLS, or authentication |
| Connected                 | In-app status failed                            | Live engine registration or workspace routing             |
| Connected                 | In-app Ready, forced call rejected              | Stale task tool snapshot or engine compatibility          |
| Connected                 | Forced call succeeds, natural request uses docs | Agent steering rather than MCP exposure                   |