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 next_run_at (detail / graph node state)
2. Confirm timezone: Settings → General → Timezone; tasks store tz_offset_hours
3. Cron uses your timezone; once should include timezone suffix (e.g. 2026-12-31T09:00:00+08:00)
4. v2 heap scheduling (~1s); sidebar lists roots — children in graph view
5. On OOM, set DISABLE_SCHEDULER=1 or lower SCHEDULER_MAX_CONCURRENT (see Developer Guide)

Q: Message queue / interrupt not working?

A: Queue and ↵ Run now are Admin chat only; requires active stream on current conversation and no HITL wait. Interrupt keeps partial reply and continues on the same connection.

Q: Workspace lock blocks Agent writes?

A: Open the lock panel in chat header — another process (scheduled task / other chat) may hold the path. Release manually (does not abort Agent) or wait for process end.

Q: How to back up user data?

A: Prefer Settings → Data Backup ZIP export (§6.5.6). Manual backup:

• Local: users/ + data/ (checkpoints.db, encryption.key)
• Docker: ./data/users/ volume
• S3: object storage + local users/{uid}/ config
• Important: back up ENCRYPTION_KEY or data/encryption.key

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: 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 openjellyfish

Q: Docker deployment keeps restarting with sqlite3.OperationalError: unable to open database file?

A: Data directory permission issue. The container runs as jellyfish (uid=1000), but the host's ./data directory is owned by root, so the in-container process can't write checkpoints.db.

Fix (run from the project root on the host):

mkdir -p ./data/users
sudo chown -R 1000:1000 ./data
docker compose restart openjellyfish

Verify:

ls -ld ./data ./data/users
# Expected: owner is 1000:1000

Note: With multiple FastAPI routers, the merged_lifespan is nested, so the traceback contains a long chain of repeated routing.py:216 frames. Only the bottom two lines matter (the exception type and message).

Q: After Docker deploy, the domain doesn't resolve, but curl http://localhost works on the server?

A: Check in this order:

1. DNS: nslookup yourdomain.com should resolve to the server's public IP; in the Cloudflare dashboard, confirm the A record is Proxied (orange cloud).
2. Firewall / security group: Port 80 must be open to the public (cloud provider's security group, ufw status).
3. Cloudflare SSL mode: Must be Flexible (HTTPS at the edge, HTTP to origin). If you wrongly pick Full / Full(Strict) but the server only listens on port 80, you'll see infinite 301 redirects or a 525 error.
4. Is nginx really on :80?: docker compose ps should show openjellyfish-nginx as Up with 0.0.0.0:80->80/tcp.
5. Streaming output arrives in chunks instead of token-by-token: The bundled nginx already disables proxy_buffering for /api/chat. If there is another reverse proxy (custom nginx / Caddy / Traefik) in front of the server, that layer must also disable buffering and enable WebSocket Upgrade, otherwise SSE will be buffered.