Troubleshooting & FAQ

Web search says "API 配置问题"

This is normal if you haven't configured a search API key. PicoClaw will still provide helpful links for manual searching.

To enable web search:

1. Option 1 (recommended): Get a free API key at brave.com/search/api (2000 free queries/month).
2. Option 2: Use built-in DuckDuckGo — no API key required. Enable tools.web.duckduckgo.enabled: true in ~/.picoclaw/config.json.

Add the Brave key under tools.web.brave.api_key if using Brave.

Content filtering errors

Some providers (e.g. Zhipu) apply content filtering. Try rephrasing your query or use a different model/provider.

Telegram: "Conflict: terminated by other getUpdates"

Another instance of the bot is running. Ensure only one picoclaw gateway is running at a time (same token).

LLM call fails (400 / invalid model ID)

Check that your model name matches the provider. For example, glm-4.7 is for Zhipu; use the correct model ID for OpenRouter/OpenAI/Anthropic. See Providers & API Keys.

Tool execution blocked (path outside working dir)

With restrict_to_workspace: true, the agent can only access paths inside the workspace. See Security & Sandbox. To allow broader access (security risk), set restrict_to_workspace: false in config or PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false.

Heartbeat not running

Ensure heartbeat.enabled is true and interval is at least 5 (minutes). If the service never started, upgrade to v0.1.1+ which includes a heartbeat startup fix.

More help

Search or open an issue: GitHub Issues. Discussions: GitHub Discussions. Discord: discord.gg/V4sAZ9XWpN.