---
title: "Manage connections"
description: "Manage the full connection lifecycle and understand app-specific behavior."
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.

# Manage connections

OcHub stores connections separately for each app. A Claude Code connection does not
automatically appear in Codex, but **Copy to app** can regenerate it in the
target tool's format.

## Discover existing configuration

When you open an app page, OcHub reads the tool's current live configuration:

- Recognized connections appear under Direct connections.
- Connections already present in the tool but not currently selected are marked
  Added.
- The active connection is marked Current.
- If a custom field cannot be represented completely, inspect the write preview
  before saving so it is not lost.

## Everyday connection actions

| Action | Use it for |
| --- | --- |
| Edit | Change endpoints, keys, models, notes, or advanced fields |
| Drag to reorder | Change list and system-menu order |
| Copy to app | Regenerate a new connection in another app's format |
| Add to tool | Preload a connection without making it current |
| Switch | Make it the live connection immediately |
| Remove from tool | Keep OcHub data while removing the live tool entry |
| Delete | Permanently remove the connection from OcHub |

If a connection is current, switch to another one before deleting it.

## Official login

**Use official login** writes no third-party Base URL or API key. It keeps the
tool's own login state. Use it when:

- Claude Code or Codex is already signed in with an official account.
- You need to switch temporarily from a third-party API back to the official
  service.
- You want to preserve native subscription and account features.

For Codex, both `auth.json` and `config.toml` belong to the active connection
version. When either file changes outside OcHub, review and save that version
before switching away if you want to keep it.

## App-specific settings

Open **App settings** in the upper-right corner of an app page:

| App | Main settings |
| --- | --- |
| Claude Code | Skip MCP onboarding, Claude plugin integration, custom config directory |
| Codex | Unified history, migrate existing sessions, custom config directory |
| OpenCode | Custom config directory |
| OpenClaw | Custom config directory |
| Hermes | Custom config directory |
| Grok Build | Custom config directory |

A custom directory changes where configuration, MCP, or session history is
read. Restart OcHub and the target tool after saving it.

## Checks in the editor

- **Test URL** measures the latency of an HTTP response.
- **Fetch models** requests the model list with the current endpoint and key.
- **Check balance** works only for upstream services that implement a
  compatible balance endpoint.
- **Files to be written** shows generated content and destination paths.
- **Common configuration** merges an app-level shared snippet into connections
  that enable it.

A successful test does not prove that a model can be called. A real request
from the target CLI is the final check.

## When configuration changed externally

OcHub treats each active connection as a saved configuration version. Before
switching, it compares that saved version with the files currently on disk:

1. Review the side-by-side file diff. Red shows the saved version and green
   shows the current file.
2. Choose **Save as new version** to store the current files in the active
   connection, then switch. Switching back later restores this new version.
3. Choose **Revert to saved** to discard the current on-disk edits, restore the
   saved connection version, then switch.
4. Choose **Cancel** to leave both OcHub and the live files unchanged.

This flow applies to every switch-style app whose live configuration OcHub can
read, including Claude Code, Codex, Grok Build, Kimi Code, and switch plugins.
Codex shows `auth.json` and `config.toml` as separate files. Even malformed
`auth.json` text is included and can be saved and restored exactly.

Do not let OcHub, cc-switch, and a manual editor write the same file at once.

## Verify a new connection

After saving or switching a connection in any app:

1. Review the generated file and path.
2. Confirm the card is Added or Current after saving.
3. Fully restart the target tool.
4. Select the new provider and model.
5. Make one short request.
6. Check tool errors, OcHub usage, or upstream logs.

| Problem | Common cause |
| --- | --- |
| Connection missing | It was saved but not added, or the directory is wrong |
| One connection replaced another | Duplicate Provider ID in a coexistence app |
| 401 | Key, environment variable, or launch environment mismatch |
| 404 / body error | Wrong backend, protocol, or API mode |
| Model appears but fails | Model ID, context limit, or permission mismatch |
| Advanced save fails | Incorrect JSON/YAML node type |

## App-specific field guides

| App | Continue with |
| --- | --- |
| Claude Code / Claude Desktop | [Authentication, role models, MCP, and plugins](/claude/configure) |
| Codex | [OAuth, Responses, reasoning, and session history](/codex/configure) |
| Grok Build | [Profiles, API backends, and environment variables](/grok-build/configure) |
| OpenCode | [AI SDK packages, provider IDs, and OMO](/opencode/configure) |
| OpenClaw | [Protocols, default model, and tool permissions](/openclaw/configure) |
| Hermes | [API modes, models, and memory](/hermes/configure) |

To bring in connections from an older manager, use
[Migrate from cc-switch](/guides/migration) instead of copying every entry by
hand.

Source: https://docs.ochub.org/guides/providers/index.mdx