FAQ

Q: "Invalid registration code" on registration?

A: Confirm config/registration_keys.json exists and contains valid codes.

• Command line: python generate_keys.py to generate new codes
• Desktop App: go to "Registration Code Management" tab to generate
• Each registration code can only be used once

Q: Frontend cannot connect to backend?

A: Verify:

1. Backend FastAPI is running on :8000 (test at http://localhost:8000/docs)
2. Vite dev server running on :3000 (auto-proxies /api → :8000)
3. For Docker, check docker compose logs -f to confirm both services are ready
4. For Desktop App, open "About / Tools" → "Log Directory" to troubleshoot

Q: Model list is empty?

A: Need to configure at least one valid API Key:

• ANTHROPIC_API_KEY: enables Claude series models
• OPENAI_API_KEY: enables GPT series models + multimedia capabilities

Or configure your own Key in Settings → General → API Keys (recommended).

Q: Web search unavailable?

A: Admin Agent enables web tools by default, but requires search API configuration:

• CLOUDSWAY_SEARCH_KEY (recommended, used first)
• TAVILY_API_KEY (fallback)

Can configure in Settings → General → API Keys.

Q: Image/voice/video generation fails?

A: Confirm OPENAI_API_KEY is configured. To use a different API Key or endpoint, override separately with IMAGE_API_KEY / TTS_API_KEY / VIDEO_API_KEY (works as environment variables or per-admin settings).

Q: WeChat QR scanned but messages not received?

A: Follow this checklist:

1. Confirm iLink Bot service is running (after scan, status should show "Connected")
2. Check wechat.* logs in backend (requires LOG_LEVEL=INFO)
3. iLink (domestic) requires direct connection, no proxy
4. Check if WeChat session expired (context_token invalid), rescan
5. Admin WeChat and Service WeChat are two independent stacks — don't confuse them

Q: WeChat shows literal <<FILE:...>> string?

A: Should be auto-parsed by delivery.py::extract_media_tags. If still appearing:

1. Check if file path actually exists
2. Check backend logs for media download failures
3. Confirm this isn't text from non-send_message tool calls (e.g., web_search results)

Q: Script execution fails / "queue busy"?

A: Scripts execute in a sandbox with the following restrictions:

• Cannot import dangerous modules (subprocess, pathlib, ctypes, io, pickle, threading, etc.)
• Cannot use dangerous builtins (exec, eval, getattr, setattr, etc.)
• Use relative paths for files (../docs/file.csv, not /docs/file.csv), script cwd is scripts/ directory
• Memory limit 1024 MB, process count limit 256
• Global concurrency 4 scripts (adjustable via SCRIPT_CONCURRENCY)
• Queue timeout 180 seconds (adjustable via SCRIPT_QUEUE_TIMEOUT)

Q: Scheduled task not triggering?

A:

1. Check task's next_run field (visible in run records page)
2. Confirm timezone is correct: General → Timezone
3. Cron expressions interpreted in your configured timezone
4. once type must include timezone suffix (e.g., 2026-12-31T09:00:00+08:00)
5. Scheduler checks every 30s, so execution may be delayed by seconds

Q: Inbox has messages but didn't auto-forward to my WeChat?

A:

1. Confirm you've connected Admin WeChat via Settings → WeChat Integration
2. Check if users/{your-username}/admin_wechat_session.json exists
3. Inbox Agent intelligently evaluates whether forwarding is worthwhile — not every message is forwarded
4. View inbox agent run logs (visible in inbox detail page)

Q: How to back up user data?

A:

• Local mode: back up users/ and data/ directories (includes checkpoints.db, encryption.key)
• Docker mode: back up ./data/users/ directory
• S3 mode: S3 storage has built-in redundancy, but JSON configs remain local — must back up both local users/{uid}/ (except filesystem/) and data/
• Important: If you set ENCRYPTION_KEY, note that value; otherwise back up data/encryption.key (master key) — loss means all API Keys are unrecoverable

Q: Tauri Desktop App on Windows reports Cannot load native module 'Crypto.Util._cpuid_c'?

A: This is a fixed Windows \\?\ extended long path prefix bug. Please:

1. Upgrade to the latest Desktop App version
2. If self-building, confirm lib.rs includes strip_win_extended_prefix() helper
3. See Developer Guide §12.5.1

Q: Is the per-admin API Key configuration secure?

A:

• AES-256-GCM encrypted storage in users/{uid}/api_keys.json
• Master key in data/encryption.key (or ENCRYPTION_KEY environment variable)
• Frontend only reads masked version (e.g., sk-...abc123)
• Transmitted over HTTPS (must enable SSL in production)
• Strictly protect the master key file: all user API Keys are unrecoverable if lost

Q: Can multiple Admins share one API Key?

A: No. Each Admin configures independently in users/{uid}/api_keys.json. For centralized management, configure a global default key in environment variables — all users without individual config will use it as fallback.

Q: How is Service data isolated?

A: Strict isolation:

• Each Service under users/{admin_id}/services/{service_id}/
• Each Consumer conversation in users/{admin_id}/services/{svc_id}/conversations/{conv_id}/
• Consumer generated files in their conversation's generated/ directory
• Consumer cannot see Admin filesystem, other Services, or other Consumers' data

Q: Some components have wrong colors after theme switch?

A: Most components have migrated to --jf-* CSS variables. If you find missed ones, check variable definitions in frontend/src/styles/themes.css, or change hardcoded colors to var(--jf-primary) etc. See Developer Guide §5.9.

Q: How to view backend logs?

A:

• Desktop App: "About / Tools" → "Log Directory", daily-rolling log files
• Command line: see stdout directly in terminal, or python launcher.py subprocesses also write to logs/{name}-YYYYMMDD.log
• Docker: docker compose logs -f jellyfishbot

---