Troubleshooting
Start with /doctor — it checks runtime version, provider credentials, config integrity, plugin/MCP status, and Sentry telemetry.
Startup Issues
"command not found: clew"
npm global install path may not be in PATH. Use npx clew-code or bun x clew-code as alternatives.
"Bun not found"
Clew requires Bun 1.3+ as the runtime for the npm package.
Provider Issues
"No API key configured"
Set at least one provider API key as an environment variable. See Providers for the full list.
export ANTHROPIC_API_KEY=sk-ant-...
export DEEPSEEK_API_KEY=sk-...Run /doctor to verify configured providers.
"Rate limited" or "Quota exceeded"
Set a fallback model via CLI: --fallback-model <model>. Or use /model to switch to a different provider. For rate limit options during a session, use /rate-limit-options.
Build Issues
TypeScript errors during build
bun run build
# TypeScript errors may exist in uncommitted code or external modules.
# Run targeted checks:
bun x tsc --noEmit
bun test Windows-specific issues
- ripgrep is bundled at
src/utils/vendor/ripgrep/x64-win32/rg.exe - TTY polyfill may be needed for Ink compatibility
- PowerShell and Bash may behave differently for tool execution
- Windows argv normalization in
src/entry.ts
MCP Issues
"MCP server connection failed"
Verify the server command exists and paths are correct. Check JSON config syntax with /mcp command.
MCP tools not appearing
Use /mcp to check server status. Tools are loaded at startup via --mcp-config or through assembleToolPool() during server connection. Verify the server implements tools/list correctly.
Plugin Issues
Plugin not loading
Check plugin manifest format and location. Use /plugin and /reload-plugins to refresh. For directory-based plugins, use --plugin-dir <path>.
Feature Flags
Some features require compile-time or runtime flags:
| Feature | Required Flag |
|---|---|
| Bridge mode | BRIDGE_MODE=1 |
| Voice mode | VOICE_MODE=1 |
| LSP tool | ENABLE_LSP_TOOL=1 |
| Computer Use | ENABLE_COMPUTER_USE=1 (Windows) |
| Proactive features | KAIROS=1 |
| Agent triggers | AGENT_TRIGGERS=1 |
| Code index | CODE_INDEX=1 |
Getting Help
- In-app diagnostics:
/doctor— comprehensive environment check - Status overview:
/status— version, model, API connectivity, tool statuses - GitHub Issues: Report bugs and feature requests
- Debug mode: Run with
DEBUG=1orDEBUG=provider:anthropicfor detailed logging