> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opsh.dxu.one/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Problems & Fixes

> Fix the most common Opsh problems: terminal startup failures, API key errors, slow responses, unexpected warp mode behavior, and more.

If something isn't working as expected, the issues below cover the most common causes and how to resolve them. If your problem isn't listed here, check that you're on the latest version of Opsh and that your config file at `~/.opsh/config.json` is valid JSON.

<AccordionGroup>
  <Accordion title="Opsh doesn't start automatically when I open a terminal">
    Opsh relies on a shell integration block added to your shell rc file during installation. If it's missing or your PATH isn't set correctly, Opsh won't be available automatically.

    1. Verify that `~/.opsh/bin` is present: run `ls ~/.opsh/bin`.
    2. Check that `~/.opsh/bin` is in your `PATH`: run `echo $PATH` and look for it.
    3. Re-run the install script to restore the shell integration:
       ```bash theme={null}
       curl -fsSL https://opsh.dxu.one/install.sh | bash
       ```
    4. Check that the environment variable `OPSH_DISABLE_AUTO` is not set in your shell environment. If it is, Opsh's auto-start is suppressed — unset it or remove it from your rc file.
    5. Open a new terminal after making any changes.
  </Accordion>

  <Accordion title="&#x22;API key is not configured&#x22; error">
    Opsh needs a valid API key for your chosen AI provider before it can generate any commands.

    * Run `opsh --init` to go through the setup wizard and enter your provider and API key interactively.
    * Alternatively, open `~/.opsh/config.json` in a text editor and set the `apiKey` field under your provider's configuration.
  </Accordion>

  <Accordion title="Provider request failed (HTTP error)">
    An HTTP error from your provider usually means a configuration problem or a connectivity issue.

    1. Confirm your API key is correct and has not expired. Generate a new key from your provider's dashboard if needed.
    2. Check your internet connection.
    3. Open `~/.opsh/config.json` and verify that the `baseUrl` field matches your provider's API endpoint exactly.
    4. If you're using Ollama for local inference, make sure Ollama is running: `ollama serve`.
  </Accordion>

  <Accordion title="The generated command doesn't do what I asked">
    The AI model may have interpreted your request differently than you intended. You have a few options at the confirmation prompt:

    * Press **r** to regenerate the command with a safer or simpler interpretation, keeping your original request.
    * Press **e** to open an edit prompt and modify the command manually before running it.
    * Cancel with **n** and rephrase your request more specifically — for example, include the exact file name, directory, or flags you need.
    * If Opsh isn't using enough context from your recent history, increase `recentContextLimit` in `~/.opsh/config.json` to give the model more shell history to work with.
  </Accordion>

  <Accordion title="Warp mode auto-runs a command I wanted to review">
    Warp mode automatically runs commands classified as **safe**. If you want to review everything before it executes, turn warp mode off.

    * In the REPL, type `!warp` to toggle warp mode off for the current session.
    * To disable it permanently, open `~/.opsh/config.json` and set `"warpMode": false`.
  </Accordion>

  <Accordion title="I want to run a raw shell command without AI">
    You can bypass AI generation and send input directly to your shell in two ways:

    * In the REPL, type `!cmd` to toggle raw command mode. While active, everything you type is passed directly to the shell without going through the AI.
    * For one-off raw commands, use your normal shell directly instead of Opsh's one-shot mode — `opsh "!cmd ..."` is not supported in one-shot.
  </Accordion>

  <Accordion title="Opsh is slow or has high latency">
    Response time depends entirely on the AI provider and model you've configured.

    * Switch to a faster model. Good options for low latency include Gemini 2.5 Flash (`gemini-2.5-flash`), Claude Haiku 3.5 (`claude-3-5-haiku-20241022`), or GPT-5 mini (`gpt-5-mini`).
    * If you use OpenRouter, consider its auto-router, which routes requests to a fast available model automatically.
    * For zero-latency, fully local inference, configure Opsh to use [Ollama](https://ollama.com) with a model running on your machine.
  </Accordion>
</AccordionGroup>