# How to Troubleshoot Common Issues in different-ai/openwork: A Complete Guide

> Troubleshoot common issues with different-ai/openwork. Run the openwork-doctor script, check JSON config files for stale URLs, and verify dev-profile locks for UI startup failures.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-05

---

**Use the built-in `openwork-doctor.ps1` script for network/TLS diagnostics, verify [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json) and [`desktop-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/desktop-bootstrap.json) for stale MCP URLs, and check dev-profile locks when the Electron UI fails to start.**

OpenWork is a **modular, cross-platform AI-workflow platform** that combines an Electron desktop client, a Den control plane, and the OpenCode runtime. When components fail to connect or behave unexpectedly, systematic troubleshooting across these three layers resolves most issues quickly. This guide walks through the diagnostic tools and configuration files that the different-ai/openwork repository provides to identify and fix common problems.

## Network and TLS Connection Issues

Most connectivity problems stem from DNS resolution failures, firewall blocks, TLS certificate problems, or corporate proxy interference. The repository includes purpose-built diagnostics for each scenario.

### Run the OpenWork-Doctor PowerShell Script

The primary tool for network troubleshooting is `scripts/support/openwork-doctor.ps1`. This script performs five sequential checks and prints a verdict hint identifying the most likely root cause:

| Check | Validation | Typical Verdict |
|-------|------------|---------------|
| **DNS** | Resolves hostname via `Resolve-DnsName` | `LIKELY DNS ISSUE` |
| **TCP 443** | Socket connection with 5s timeout | `LIKELY NETWORK/FIREWALL ISSUE` |
| **TLS handshake** | `SslStream` callback for certificate/chain status | `LIKELY TLS INTERCEPTION` or `LIKELY MISSING INTERMEDIATE` |
| **OpenSSL chain probe** | `openssl s_client` server chain inspection | `MISSING INTERMEDIATE CONFIRMED BY OPENSSL` |
| **Proxy detection** | `netsh winhttp show proxy` and `.DefaultWebProxy` | `PROXY DETECTED` |

Execute the script directly from GitHub:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command `
"`$p=Join-Path `$env:TEMP 'openwork-doctor.ps1'; `
Invoke-WebRequest -UseBasicParsing `
'https://raw.githubusercontent.com/different-ai/openwork/dev/scripts/support/openwork-doctor.ps1' `
-OutFile `$p; & `$p -WebUrl 'https://openwork.example.com' `
-ApiUrl 'https://api.openwork.example.com' -ExpectedIssuerMatch 'DigiCert'`"

```

The script source is fully inspectable at `scripts/support/openwork-doctor.ps1`. Detailed documentation mirroring these checks lives in `packages/docs/start-here/network-diagnostics.mdx`.

## MCP and OpenCode Configuration Problems

When the desktop client shows as "connected" but agents cannot call `search_capabilities` or `execute_capability`, the MCP entry in OpenCode's configuration typically points to a stale or local server.

### Locating Stale MCP URLs

OpenWork's MCP configuration resides in [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json). The troubleshooting flow in `packages/docs/start-here/troubleshooting/diagnostic-prompts.mdx` provides diagnostic prompts that:

1. Print the `openwork-cloud` MCP entry from all config locations (`~/.config/opencode/opencode.json`, [`desktop-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/desktop-bootstrap.json), etc.) without exposing secrets
2. Probe discovered and expected URLs with unauthenticated `curl` calls to compare OpenAPI catalogs
3. Execute live `search_capabilities` / `execute_capability` calls to verify server agreement

Paste this prompt into any OpenWork-connected LLM to automate the diagnosis:

```text
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

```

### Fixing Stale Local URLs

If the diagnostic reveals `localhost` addresses or old development servers:

1. Delete [`desktop-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/desktop-bootstrap.json) (or the entire local config directory)
2. Restart the desktop app to mint a fresh MCP token
3. Navigate to **Settings → Extensions → Refresh**

For manual configuration, create or edit [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json):

```json
{
  "mcp": {
    "openwork": {
      "type": "remote",
      "enabled": true,
      "url": "https://api.openworklabs.com/mcp/agent",
      "oauth": {}
    }
  }
}

```

Place this file in your project root or `~/.config/opencode/`, then reload the OpenCode configuration.

## Desktop Client Startup Failures

When the Electron UI fails to open despite a visible dev banner, a **profile lock conflict** is the usual cause.

### Reading the Startup Banner

The desktop prints diagnostic information on startup:

```

[openwork] dev profile=feature-xyz cdp=http://127.0.0.1:9223

```

This reveals the **Chrome DevTools Protocol (CDP) endpoint** and active **dev profile**. The profile directory is tracked via lock files under `dev/.warden/`.

### Resolving Profile Locks

The [`dev/scripts/dev-web-local.sh`](https://github.com/different-ai/openwork/blob/main/dev/scripts/dev-web-local.sh) script coordinates Vite dev-server ports and Electron CDP ports. When conflicts occur:

- Kill stray Electron processes (running `pnpm dev:worktree` automatically creates unique profiles per worktree)
- Delete the lock file under `dev/.warden/`

If the banner displays a CDP URL but no window appears, this confirms a profile lock rather than a fundamental startup failure.

## Self-Hosted Den Deployment Issues

For Den instances behind corporate firewalls, enable **Outbound Diagnostic** via environment variables:

```dotenv
DEN_DIAGNOSTICS_ORIGIN=https://diagnostics.mycompany.internal
DEN_DIAGNOSTICS_BEARER_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

```

The Den process then contacts your trusted diagnostics service to verify DNS, proxy, and TLS reachability from inside the cluster. See the *Den outbound diagnostic* section in `packages/docs/start-here/network-diagnostics.mdx` for implementation details.

Ensure the token is a synthetic 24-character string and that `DEN_DIAGNOSTICS_ORIGIN` matches your deployment's DNS name—mismatches here produce 403 errors despite valid credentials.

## Quick Reference: Symptom-to-Fix Mapping

| Symptom | Likely Cause | Resolution |
|---------|------------|------------|
| `search_capabilities` returns partial tool list (e.g., only `gmail-drafts`) | Stale local MCP server in config | Delete [`desktop-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/desktop-bootstrap.json), restart app, refresh extensions |
| TLS "certificate unknown" errors | Missing intermediates or proxy re-signing | Run `openwork-doctor.ps1`, add corporate root to trust store, or allowlist host |
| UI never opens but CDP URL visible | Profile lock or port conflict | Kill Electron processes or delete `.warden` lock file |
| Den outbound 403 with valid token | Unwhitelisted origin or malformed token | Verify 24-character token format and DNS-origin match |

## Summary

- **Network/TLS problems:** Run `scripts/support/openwork-doctor.ps1` and consult `packages/docs/start-here/network-diagnostics.mdx`
- **MCP configuration issues:** Check [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json) and [`desktop-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/desktop-bootstrap.json) for stale URLs; use diagnostic prompts in `packages/docs/start-here/troubleshooting/diagnostic-prompts.mdx`
- **Desktop UI failures:** Inspect the startup banner for CDP/profile info; resolve locks via [`dev/scripts/dev-web-local.sh`](https://github.com/different-ai/openwork/blob/main/dev/scripts/dev-web-local.sh) patterns
- **Self-hosted Den:** Configure `DEN_DIAGNOSTICS_ORIGIN` and `DEN_DIAGNOSTICS_BEARER_TOKEN` for firewall-protected deployments

## Frequently Asked Questions

### How do I know if my MCP is pointing to the wrong server?

The diagnostic prompt in `packages/docs/start-here/troubleshooting/diagnostic-prompts.mdx` automatically compares your configured MCP URL against the expected cloud URL. If `search_capabilities` returns tools you don't recognize (or too few tools), this indicates a stale local server. The prompt will flag any `localhost` entries or mismatched OpenAPI catalogs.

### What causes TLS handshake failures in OpenWork?

Corporate proxies that re-sign certificates, missing intermediate certificates in the server chain, or incorrect system trust stores. Run `openwork-doctor.ps1` with your target URLs—the script's `SslStream` callback identifies whether the leaf issuer is an internal proxy CA (`LIKELY TLS INTERCEPTION`) or whether intermediates are missing (`LIKELY MISSING INTERMEDIATE`).

### Why does the desktop app show a CDP URL but no window appears?

An existing Electron process holds the profile lock or CDP port. The dev banner confirms the app reached CDP initialization; the missing window indicates a conflict. Use `pnpm dev:worktree` to generate a fresh isolated profile, or manually delete the lock file in `dev/.warden/`.

### How do I diagnose Den connectivity from inside a corporate network?

Set `DEN_DIAGNOSTICS_ORIGIN` and `DEN_DIAGNOSTICS_BEARER_TOKEN` environment variables, then restart Den. The process will report its outbound connectivity test results to your specified diagnostics endpoint, revealing DNS, proxy, and TLS problems from the cluster's perspective.