Chatwoot
en
Language
en English pt_BR Portuguese (Brazil) es Spanish de German fr French ar Arabic

Enable Captain on self-hosted

Open in
View as Markdown Open in ChatGPT Open in Claude
harishmita

harishmita

Last updated on Oct 20, 2026

Discover

You can run Captain on your own Chatwoot installation with your own OpenAI key.

Plan & access: included in the Premium and Enterprise self-hosted plans. See Enterprise Edition. You need access to the Super Admin console. The Community Edition does not include Captain.

Premium and Enterprise get the same Captain features and settings.

Set up & try

Before you start

  • An OpenAI API key.

  • Optional: an OpenAI-compatible endpoint if you host your own model.

  • Optional: a Firecrawl API key for better website crawling. Without it, Chatwoot uses a simpler built-in crawler.

1. Configure Captain for the installation

  1. Open the Super Admin console and go to Settings.

  2. On the Captain card, click the settings (gear) icon.

  3. Fill in:

    • OpenAI API Key.

    • OpenAI Model sets the model for Copilot and editor features. Leave it blank to use gpt-4.1-mini. The assistant uses gpt-5.2 by default. To change it, go to Super Admin › Accounts, edit the account and open the Captain models tab. If you use a custom endpoint, make sure it serves the models you pick here.

    • OpenAI API Endpoint (optional), for a compatible self-hosted model.

    • Embedding Model (optional).

    • FireCrawl API Key (optional).

  4. Click Submit.

2. Turn Captain on for an account

Accounts created while your installation is on Premium or Enterprise have Captain turned on already. For accounts created before that:

  1. In the Super Admin console, go to Accounts.

  2. Open the account and click Edit.

  3. In the premium features, turn on Captain. Guardrails, response guidelines and scenarios come with it. For custom tools, also turn on Custom Tools (Set up custom tools for Captain).

  4. Save.

Test it

Log in to that account. Captain appears in the sidebar. Create an assistant and send a message in the Playground. See Set up a Captain assistant and connect your inboxes.

Get value

  • OpenAI bills you for usage on your own key. Chatwoot does not count Captain credits on self-hosted installations.

  • Upgrading from an older version where assistants used the Instructions field? Instructions are no longer used. Move them into guardrails and response guidelines before you upgrade (Set Captain's guardrails, guidelines and scenarios).

  • Everything else works as on Cloud. Continue with Add documents to Captain's knowledge.

Troubleshoot

Symptom Likely cause What to do
No Captain in the sidebar Not turned on for the account, or not on a Premium or Enterprise licence Check both steps; check your licence
No Tools Custom Tools is off for the account Turn them on in Super Admin > Accounts
Assistant does not reply Invalid or inactive OpenAI key, or an unsupported model name Check the key. Check your endpoint serves the assistant's model (gpt-5.2 by default, or the one set in the account's Captain models tab).
Website documents miss pages No Firecrawl key, so the simple crawler is used Add a FireCrawl API Key
Website documents fail to sync Invalid Firecrawl API key Check the Firecrawl API key is valid. If a key is set, Chatwoot always uses Firecrawl, so an invalid key makes website documents fail. Remove the key to use the built-in crawler.
Still failing An error on the server Check the web and worker logs