---
title: "Configure a direct connection"
description: "Add a connection, write it to a target tool, and make your first safe switch."
version: "en"
---

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

# Configure a direct connection

A direct connection writes the connection's settings to the selected AI tool, and
the tool calls that provider without passing through the OcHub gateway. It is the
best way to get started.

## Use this path when

- You are configuring OcHub for the first time.
- One tool should call one provider endpoint directly.
- You want to keep using the tool's official account login.

If several tools should share routing, model aliases, or a backup upstream, use
[a model provider](/getting-started/relay) instead.

## Add a connection

1. **Choose an app.** Open the tool you want to configure under Apps in the
   sidebar.

2. **Open the editor.** Select **Add connection**. If OcHub already discovered
   local configuration, edit the discovered entry instead of creating a
   duplicate.

3. **Choose a starting point.** Use a preset when one fits, or start blank.
   Give the connection a descriptive name such as “Work account” or “Backup
   endpoint.”

4. **Enter connection details.** Use the endpoint and key documented by the
   provider. The model provider editor handles `/v1` itself; for a direct connection,
   rely on the generated file preview shown by the page.

5. **Run available checks.** Try **Test URL**, **Fetch models**, or **Check
   balance** where available. A successful URL test only proves that the
   endpoint returned an HTTP response; it does not prove that the key and model
   work.

6. **Review the write preview.** Expand **Files to be written** and verify the
   destination path and important fields. If the preview is empty, complete the
   name and connection details first.

7. **Save.** Saving adds the connection to OcHub. Whether it is immediately
   written to the tool depends on the action offered by that app page.

> **Keep real keys out of docs and screenshots**
>
> API keys belong only in local configuration. Before sharing a log or preview,
> replace keys, access tokens, and authenticated URL parameters with placeholders.

## Add versus switch

| Action | Meaning |
| --- | --- |
| Add to tool | Add the connection to the tool configuration without necessarily making it current |
| Switch | Write or select the connection and make it current |
| Import | Open the target app and ask it to confirm an import, as with Cherry Studio |
| Remove from tool | Remove the live tool entry while keeping the connection in OcHub |
| Delete | Permanently remove the connection from OcHub |

After a successful switch, **Current connection** at the top of the page shows
the new connection and its card is marked Current.

## Verify the change

1. Quit and reopen the target CLI so an existing process does not keep cached
   configuration.
2. Send a short request.
3. If it succeeds, refresh **Usage** in OcHub and look for the session or
   request record.
4. If the tool still uses the old configuration, check whether its configured
   directory matches the actual installation.

## Handle external edits

If another program changes the active connection files, OcHub shows a
side-by-side diff during the next switch:

- **Save as new version** stores the current files in the active connection,
  then switches. Returning to it later restores this version.
- **Revert to saved** discards the current file edits, restores the saved
  version, then switches.
- **Cancel** changes neither the live files nor the saved connection.

For Codex, the dialog compares `auth.json` and `config.toml` separately and also
includes malformed `auth.json` text.

## Roll back

- To use another connection, select **Switch** on its card.
- To restore the tool's own account state, switch to an Official login
  provider.
- To stop OcHub from managing the tool, disable it in **Settings → Apps and
  plugins**. Disabling does not modify the tool's current live configuration.

Source: https://docs.ochub.org/getting-started/direct-connection/index.mdx