> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/RightNow-AI/openfang/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues, diagnostics, and solutions for OpenFang

Common issues, diagnostics, and answers to frequently asked questions about OpenFang.

## Quick Diagnostics

Run the built-in diagnostic tool first:

```bash theme={null}
openfang doctor
```

This checks:

* Configuration file exists and is valid TOML
* API keys are set in environment
* Database is accessible
* Daemon status (running or not)
* Port availability
* Tool dependencies (Python, signal-cli, etc.)

### Check Daemon Status

```bash theme={null}
openfang status
```

### Check Health via API

```bash theme={null}
curl http://127.0.0.1:4200/api/health
curl http://127.0.0.1:4200/api/health/detail  # Requires auth
```

### View Logs

OpenFang uses `tracing` for structured logging. Set the log level via environment:

```bash theme={null}
RUST_LOG=info openfang start          # Default
RUST_LOG=debug openfang start         # Verbose
RUST_LOG=openfang=debug openfang start  # Only OpenFang debug, deps at info
```

## Installation Issues

<Accordion title="cargo install fails with compilation errors">
  **Cause**: Rust toolchain too old or missing system dependencies.

  **Fix**:

  ```bash theme={null}
  rustup update stable
  rustup default stable
  rustc --version  # Need 1.75+
  ```

  On Linux, you may also need:

  ```bash theme={null}
  # Debian/Ubuntu
  sudo apt install pkg-config libssl-dev libsqlite3-dev

  # Fedora
  sudo dnf install openssl-devel sqlite-devel
  ```
</Accordion>

<Accordion title="openfang command not found after install">
  **Fix**: Ensure `~/.cargo/bin` is in your PATH:

  ```bash theme={null}
  export PATH="$HOME/.cargo/bin:$PATH"
  # Add to ~/.bashrc or ~/.zshrc to persist
  ```
</Accordion>

<Accordion title="Docker container won't start">
  **Common causes**:

  * No API key provided: `docker run -e GROQ_API_KEY=... ghcr.io/RightNow-AI/openfang`
  * Port already in use: change the port mapping `-p 3001:4200`
  * Permission denied on volume mount: check directory permissions
</Accordion>

## Configuration Issues

<Accordion title="Config file not found">
  **Fix**: Run `openfang init` to create the default config:

  ```bash theme={null}
  openfang init
  ```

  This creates `~/.openfang/config.toml` with sensible defaults.
</Accordion>

<Accordion title="Missing API key warnings on start">
  **Cause**: No LLM provider API key found in environment.

  **Fix**: Set at least one provider key:

  ```bash theme={null}
  export GROQ_API_KEY="gsk_..."     # Groq (free tier available)
  # OR
  export ANTHROPIC_API_KEY="sk-ant-..."
  # OR
  export OPENAI_API_KEY="sk-..."
  ```

  Add to your shell profile to persist across sessions.
</Accordion>

<Accordion title="Config validation errors">
  Run validation manually:

  ```bash theme={null}
  openfang config show
  ```

  Common issues:

  * Malformed TOML syntax (use a TOML validator)
  * Invalid port numbers (must be 1-65535)
  * Missing required fields in channel configs
</Accordion>

<Accordion title="Port already in use">
  **Fix**: Change the port in config or kill the existing process:

  ```bash theme={null}
  # Change API port in config.toml:
  # [api]
  # listen_addr = "127.0.0.1:3001"

  # Or find and kill the process using the port
  # Linux/macOS:
  lsof -i :4200
  # Windows:
  netstat -aon | findstr :4200
  ```
</Accordion>

## LLM Provider Issues

<Accordion title="Authentication failed / 401 errors">
  **Causes**:

  * API key not set or incorrect
  * API key expired or revoked
  * Wrong env var name

  **Fix**: Verify your key:

  ```bash theme={null}
  # Check if the env var is set
  echo $GROQ_API_KEY

  # Test the provider
  curl http://127.0.0.1:4200/api/providers/groq/test -X POST
  ```
</Accordion>

<Accordion title="Rate limited / 429 errors">
  **Cause**: Too many requests to the LLM provider.

  **Fix**:

  * The driver automatically retries with exponential backoff
  * Reduce `max_llm_tokens_per_hour` in agent capabilities
  * Switch to a provider with higher rate limits
  * Use multiple providers with model routing
</Accordion>

<Accordion title="Slow responses">
  **Possible causes**:

  * Provider API latency (try Groq for fast inference)
  * Large context window (use `/compact` to shrink session)
  * Complex tool chains (check iteration count in response)

  **Fix**: Use per-agent model overrides to use faster models for simple agents:

  ```toml theme={null}
  [model]
  provider = "groq"
  model = "llama-3.1-8b-instant"  # Fast, small model
  ```
</Accordion>

<Accordion title="Model not found">
  **Fix**: Check available models:

  ```bash theme={null}
  curl http://127.0.0.1:4200/api/models
  ```

  Or use an alias:

  ```toml theme={null}
  [model]
  model = "llama"  # Alias for llama-3.3-70b-versatile
  ```

  See the full alias list:

  ```bash theme={null}
  curl http://127.0.0.1:4200/api/models/aliases
  ```
</Accordion>

<Accordion title="Ollama / local models not connecting">
  **Fix**: Ensure the local server is running:

  ```bash theme={null}
  # Ollama
  ollama serve  # Default: http://localhost:11434

  # vLLM
  python -m vllm.entrypoints.openai.api_server --model ...

  # LM Studio
  # Start from the LM Studio UI, enable API server
  ```
</Accordion>

## Channel Issues

<Accordion title="Telegram bot not responding">
  **Checklist**:

  1. Bot token is correct: `echo $TELEGRAM_BOT_TOKEN`
  2. Bot has been started (send `/start` in Telegram)
  3. If `allowed_users` is set, your Telegram user ID is in the list
  4. Check logs for "Telegram adapter" messages
</Accordion>

<Accordion title="Discord bot offline">
  **Checklist**:

  1. Bot token is correct
  2. **Message Content Intent** is enabled in Discord Developer Portal
  3. Bot has been invited to the server with correct permissions
  4. Check Gateway connection in logs
</Accordion>

<Accordion title="Slack bot not receiving messages">
  **Checklist**:

  1. Both `SLACK_BOT_TOKEN` (xoxb-) and `SLACK_APP_TOKEN` (xapp-) are set
  2. Socket Mode is enabled in the Slack app settings
  3. Bot has been added to the channels it should monitor
  4. Required scopes: `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
</Accordion>

<Accordion title="Webhook-based channels (WhatsApp, LINE, Viber, etc.)">
  **Checklist**:

  1. Your server is publicly accessible (or use a tunnel like ngrok)
  2. Webhook URL is correctly configured in the platform dashboard
  3. Webhook port is open and not blocked by firewall
  4. Verify token matches between config and platform dashboard
</Accordion>

<Accordion title="Channel adapter failed to start">
  **Common causes**:

  * Missing or invalid token
  * Port already in use (for webhook-based channels)
  * Network connectivity issues

  Check logs for the specific error:

  ```bash theme={null}
  RUST_LOG=openfang_channels=debug openfang start
  ```
</Accordion>

## Agent Issues

<Accordion title="Agent stuck in a loop">
  **Cause**: The agent is repeatedly calling the same tool with the same parameters.

  **Automatic protection**: OpenFang has a built-in loop guard:

  * **Warn** at 3 identical tool calls
  * **Block** at 5 identical tool calls
  * **Circuit breaker** at 30 total blocked calls (stops the agent)

  **Manual fix**: Cancel the agent's current run:

  ```bash theme={null}
  curl -X POST http://127.0.0.1:4200/api/agents/{id}/stop
  ```

  Or via chat command: `/stop`
</Accordion>

<Accordion title="Agent running out of context">
  **Cause**: Conversation history is too long for the model's context window.

  **Fix**: Compact the session:

  ```bash theme={null}
  curl -X POST http://127.0.0.1:4200/api/agents/{id}/session/compact
  ```

  Or via chat command: `/compact`

  Auto-compaction is enabled by default when the session reaches the threshold (configurable in `[compaction]`).
</Accordion>

<Accordion title="Agent not using tools">
  **Cause**: Tools not granted in the agent's capabilities.

  **Fix**: Check the agent's manifest:

  ```toml theme={null}
  [capabilities]
  tools = ["file_read", "web_fetch", "shell_exec"]  # Must list each tool
  # OR
  # tools = ["*"]  # Grant all tools (use with caution)
  ```
</Accordion>

<Accordion title="Permission denied errors in agent responses">
  **Cause**: The agent is trying to use a tool or access a resource not in its capabilities.

  **Fix**: Add the required capability to the agent manifest. Common ones:

  * `tools = [...]` for tool access
  * `network = ["*"]` for network access
  * `memory_write = ["self.*"]` for memory writes
  * `shell = ["*"]` for shell commands (use with caution)
</Accordion>

<Accordion title="Agent spawning fails">
  **Check**:

  1. TOML manifest is valid: `openfang agent spawn --dry-run manifest.toml`
  2. LLM provider is configured and has a valid key
  3. Model specified in manifest exists in the catalog
</Accordion>

## API Issues

<Accordion title="401 Unauthorized">
  **Cause**: API key required but not provided.

  **Fix**: Include the Bearer token:

  ```bash theme={null}
  curl -H "Authorization: Bearer your-api-key" http://127.0.0.1:4200/api/agents
  ```
</Accordion>

<Accordion title="429 Too Many Requests">
  **Cause**: GCRA rate limiter triggered.

  **Fix**: Wait for the `Retry-After` period, or increase rate limits in config:

  ```toml theme={null}
  [api]
  rate_limit_per_second = 20  # Increase if needed
  ```
</Accordion>

<Accordion title="CORS errors from browser">
  **Cause**: Trying to access API from a different origin.

  **Fix**: Add your origin to CORS config:

  ```toml theme={null}
  [api]
  cors_origins = ["http://localhost:5173", "https://your-app.com"]
  ```
</Accordion>

<Accordion title="WebSocket disconnects">
  **Possible causes**:

  * Idle timeout (send periodic pings)
  * Network interruption (reconnect automatically)
  * Agent crashed (check logs)

  **Client-side fix**: Implement reconnection logic with exponential backoff.
</Accordion>

<Accordion title="OpenAI-compatible API not working with my tool">
  **Checklist**:

  1. Use `POST /v1/chat/completions` (not `/api/agents/{id}/message`)
  2. Set the model to `openfang:agent-name` (e.g., `openfang:coder`)
  3. Streaming: set `"stream": true` for SSE responses
  4. Images: use `image_url` with `data:image/png;base64,...` format
</Accordion>

## Desktop App Issues

<Accordion title="App won't start">
  **Checklist**:

  1. Only one instance can run at a time (single-instance enforcement)
  2. Check if the daemon is already running on the same ports
  3. Try deleting `~/.openfang/daemon.json` and restarting
</Accordion>

<Accordion title="White/blank screen in app">
  **Cause**: The embedded API server hasn't started yet.

  **Fix**: Wait a few seconds. If persistent, check logs for server startup errors.
</Accordion>

<Accordion title="System tray icon missing">
  **Platform-specific**:

  * **Linux**: Requires a system tray (e.g., `libappindicator` on GNOME)
  * **macOS**: Should work out of the box
  * **Windows**: Check notification area settings, may need to show hidden icons
</Accordion>

## Performance

<Accordion title="High memory usage">
  **Tips**:

  * Reduce the number of concurrent agents
  * Use session compaction for long-running agents
  * Use smaller models (Llama 8B instead of 70B for simple tasks)
  * Clear old sessions: `DELETE /api/sessions/{id}`
</Accordion>

<Accordion title="Slow startup">
  **Normal startup**: \<200ms for the kernel, \~1-2s with channel adapters.

  If slower:

  * Check database size (`~/.openfang/data/openfang.db`)
  * Reduce the number of enabled channels
  * Check network connectivity (MCP server connections happen at boot)
</Accordion>

<Accordion title="High CPU usage">
  **Possible causes**:

  * WASM sandbox execution (fuel-limited, should self-terminate)
  * Multiple agents running simultaneously
  * Channel adapters reconnecting (exponential backoff)
</Accordion>

## FAQ

<Accordion title="How do I switch the default LLM provider?">
  Edit `~/.openfang/config.toml`:

  ```toml theme={null}
  [default_model]
  provider = "groq"
  model = "llama-3.3-70b-versatile"
  api_key_env = "GROQ_API_KEY"
  ```
</Accordion>

<Accordion title="Can I use multiple providers at the same time?">
  Yes. Each agent can use a different provider via its manifest `[model]` section. The kernel creates a dedicated driver per unique provider configuration.
</Accordion>

<Accordion title="How do I add a new channel?">
  1. Add the channel config to `~/.openfang/config.toml` under `[channels]`
  2. Set the required environment variables (tokens, secrets)
  3. Restart the daemon
</Accordion>

<Accordion title="How do I update OpenFang?">
  ```bash theme={null}
  # From source
  cd openfang && git pull && cargo install --path crates/openfang-cli

  # Docker
  docker pull ghcr.io/RightNow-AI/openfang:latest
  ```
</Accordion>

<Accordion title="Can agents talk to each other?">
  Yes. Agents can use the `agent_send`, `agent_spawn`, `agent_find`, and `agent_list` tools to communicate. The orchestrator template is specifically designed for multi-agent delegation.
</Accordion>

<Accordion title="Is my data sent to the cloud?">
  Only LLM API calls go to the provider's servers. All agent data, memory, sessions, and configuration are stored locally in SQLite (`~/.openfang/data/openfang.db`). The OFP wire protocol uses HMAC-SHA256 mutual authentication for P2P communication.
</Accordion>

<Accordion title="How do I back up my data?">
  Back up these files:

  * `~/.openfang/config.toml` (configuration)
  * `~/.openfang/data/openfang.db` (all agent data, memory, sessions)
  * `~/.openfang/skills/` (installed skills)
</Accordion>

<Accordion title="How do I reset everything?">
  ```bash theme={null}
  rm -rf ~/.openfang
  openfang init  # Start fresh
  ```
</Accordion>

<Accordion title="Can I run OpenFang without an internet connection?">
  Yes, if you use a local LLM provider:

  * **Ollama**: `ollama serve` + `ollama pull llama3.2`
  * **vLLM**: Self-hosted model server
  * **LM Studio**: GUI-based local model runner

  Set the provider in config:

  ```toml theme={null}
  [default_model]
  provider = "ollama"
  model = "llama3.2"
  ```
</Accordion>

<Accordion title="What's the difference between OpenFang and OpenClaw?">
  | Aspect      | OpenFang   | OpenClaw     |
  | ----------- | ---------- | ------------ |
  | Language    | Rust       | Python       |
  | Channels    | 40         | 38           |
  | Skills      | 60         | 57           |
  | Providers   | 20         | 3            |
  | Security    | 16 systems | Config-based |
  | Binary size | \~30 MB    | \~200 MB     |
  | Startup     | \<200 ms   | \~3 s        |

  OpenFang can import OpenClaw configs: `openfang migrate --from openclaw`
</Accordion>

<Accordion title="How do I report a bug or request a feature?">
  * Bugs: Open an issue on [GitHub](https://github.com/RightNow-AI/openfang/issues)
  * Security: See SECURITY.md for responsible disclosure
  * Features: Open a GitHub discussion or PR
</Accordion>

<Accordion title="What are the system requirements?">
  | Resource | Minimum               | Recommended        |
  | -------- | --------------------- | ------------------ |
  | RAM      | 128 MB                | 512 MB             |
  | Disk     | 50 MB (binary)        | 500 MB (with data) |
  | CPU      | Any x86\_64/ARM64     | 2+ cores           |
  | OS       | Linux, macOS, Windows | Any                |
  | Rust     | 1.75+ (build only)    | Latest stable      |
</Accordion>

<Accordion title="How do I enable debug logging for a specific crate?">
  ```bash theme={null}
  RUST_LOG=openfang_runtime=debug,openfang_channels=info openfang start
  ```
</Accordion>

<Accordion title="Can I use OpenFang as a library?">
  Yes. Each crate is independently usable:

  ```toml theme={null}
  [dependencies]
  openfang-runtime = { path = "crates/openfang-runtime" }
  openfang-memory = { path = "crates/openfang-memory" }
  ```

  The `openfang-kernel` crate assembles everything, but you can use individual crates for custom integrations.
</Accordion>

<Note>
  Still having issues? Join the [Discord community](https://discord.gg/sSJqgNnq6X) or [open a GitHub issue](https://github.com/RightNow-AI/openfang/issues).
</Note>