▋
docs/troubleshooting.md

Troubleshooting

Start with /setup status and /profile. Most Clanky setup issues are profile, credential, or ownership issues.

Clanky Starts But The Model Cannot Answer

Check auth:

/openai-whoami
/model

Fix:

/openai-login

Also check whether CLANKY_OPENAI_API_KEY or OPENAI_API_KEY is set in the launch environment. Env vars override stored profile auth.

I Am In The Wrong Profile

Check:

/profile

Fix launch flags:

clanky --home ~/.clanky --profile personal --cwd .

For disposable testing, prefer:

pnpm dev:setup:fresh

Discord Text Does Not Respond

Check:

/discord-whoami
/discord-status
/setup status

Common causes:

  • No Discord credential is stored and CLANKY_DISCORD_TOKEN is not set.
  • Clanky needs a restart after /discord-login.
  • CLANKY_CHAT_GATEWAY_OWNER=off is suppressing the gateway.
  • The message does not match DMs, mentions, replies, wake names, conversation binding, or engagement-window rules.
  • Another Clanky instance is already handling the same Discord conversation.

Discord Subagents Look Stuck

Check:

/subagents status
/subagents modal
clanky logs --profile personal --home ~/.clanky

Clanky's gateway subagents are only the Discord multitasking path. For real multi-agent work, fan out into herdr panes instead.

Discord Voice Does Not Join

Check:

/discord-voice status
/voice-logs tail
/discord-status

Common causes:

  • Voice is not enabled.
  • Guild or channel ids are missing or outside the allowlist.
  • Discord credential is missing or was added after launch.
  • OpenAI credential is missing for Realtime.
  • Native helper failed to build or start.

Validate native pieces:

pnpm voice:native:test
pnpm voice:build

If a previous build used the wrong system Opus library:

pnpm voice:native:clean
pnpm voice:native:test

For live checks, use Discord Voice Live Runbook.

Voice Speaks With The Wrong TTS Provider

Check:

/discord-voice status
/elevenlabs-whoami

Env vars override profile settings. Look for:

  • CLANKY_DISCORD_VOICE_TTS_PROVIDER
  • CLANKY_VOICE_TTS_PROVIDER
  • CLANKY_DISCORD_VOICE_REALTIME_AGENT_PROVIDER
  • CLANKY_VOICE_REALTIME_AGENT_PROVIDER
  • XAI_API_KEY
  • CLANKY_ELEVENLABS_API_KEY
  • ELEVENLABS_API_KEY
  • CLANKY_ELEVENLABS_VOICE_ID

Profile settings can be changed with:

/discord-voice set realtime-provider xai
/discord-voice set xai-model grok-voice-latest
/discord-voice set tts-provider elevenlabs
/discord-voice set elevenlabs-voice <voice-id>

Go Live Or Screen Watch Does Not Work

Normal bot-token voice can join channels and play audio. Native Discord Go Live screen watching depends on user-token/selfbot behavior and should be considered live-gated. Use the voice runbook and confirm the credential kind before debugging media code.

Web Or Browser Work Fails

Check:

/web

For OpenAI hosted web search, configure OpenAI auth. For Playwright routes, install Chromium once:

pnpm browser:install

For Chrome CDP routes, start or attach to a Chrome debug session through the browser helper scripts documented in the web operator skill.

Media Generation Fails

Check:

/media
/openai-whoami
/xai-whoami

OpenAI images use OpenAI auth. xAI image/video generation uses xAI auth. Env vars can override stored profile auth.

MCP Tools Are Missing

Check:

/mcp

Custom MCP servers come from CLANKY_MCP_SERVERS, a JSON object keyed by server name. Discord tools are native Clanky tools, not an MCP server; they appear when the profile has a Discord credential. When CLANKY_TOOL_SEARCH=1 is set for supported Anthropic Claude 4+ models, Clanky registers configured MCP server tools as direct mcp__server__tool wrappers. Servers can set deferLoading: true and use toolOverrides.<tool>.deferLoading: false for hot tools that should remain loaded while the rest are discovered on demand.

Docs Checks

Clanky keeps source docs as markdown in this repo. The deployed docs site is owned by the shared docs layer, not a local Clanky app. Run pnpm check to validate repository docs and TypeScript references together.