Skip to content

Manage connections

Manage the full connection lifecycle and understand app-specific behavior.

Updated View as Markdown
For humans

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.

Live OcHub connection page rendered by GPUI WebAssembly

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.

Edit, save, and apply

The connection editor has General, Advanced, and Config files views. Save and apply stay in the footer. Check configuration appears in Config files; Copy to app appears in Advanced. Presets use a dropdown in General for new connections and Advanced when editing an existing connection. General covers routine setup; Advanced retains the extra options supported by the app. Changing views does not turn off configured advanced options.

Action Result
Save to OcHub Save a separate editing draft, including incomplete fields or invalid raw text; the connection record and target configuration stay unchanged
Check configuration Check syntax, required fields, and local constraints; no model request or account-permission check
Apply to app / Write to app Save the selected draft revision, validate it, and write the target; commit the connection record only after application completes
Import in target app Require confirmation by the external app; retain the draft while confirmation is pending

Normal save keeps the editor open. Resume later from the app page’s draft entry. Command+S / Ctrl+S performs the same save, including invalid raw-editor text. OcHub does not automatically save every keystroke. Leaving changed content offers continue editing, discard changes, or save and leave.

Draft saved, configuration written, and client adoption are separate states. If application fails, inspect the failed stage and continue from the retained draft. Disconnection keeps the current text in memory; reconnect before saving or applying. In-memory text is not a persisted draft.

Undo this application appears only when a complete write receipt is available. Undo verifies that the current state still matches this operation’s result and refuses to overwrite later changes. With a shared file, even a new edit to another connection can block undo. Operations involving credentials, gateway preparation, or external import do not offer undo unless their full recovery scope is covered.

Everyday connection actions

Connection rows keep the switch or add-to-tool action visible. Expand the arrow at the end of a row to edit, duplicate, or delete it; select the arrow again to collapse the 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 Create a separate draft in the target app’s format; review and apply it there without changing the source
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
Illustrated walkthroughClick a screen to enlarge it, then use ← → to walk the steps. The blue outline marks the control or result.
1
STEP 01Open a connection
2
STEP 02Edit its fields
3
STEP 03Add it to the tool
4
STEP 04Switch it live
5
STEP 05Copy it to another app
6
STEP 06Remove or delete carefully

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 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.

Codex history options use checkboxes and save as soon as you change them. Import existing Codex sessions appears after you enable Unify Codex session history.

The directory field is a draft until you select Save directory. Changing a history checkbox keeps your directory edits. If you continue typing while a save is in progress, select Save directory again to store the newer text.

Checks in the editor

Config files shows candidate content and paths. Final files are merged with existing configuration in the target environment; the preview is not a promise to replace an entire file unconditionally. Long lines scroll horizontally.

Use Edit to change raw text. Update edits merges parsable content into the form without writing the target. Back to editor retains the text. Invalid text can still be saved as a draft; fix it before returning to structured fields. Unmodeled keys are retained. Exact formatting and comment preservation depend on the app’s format and adapter.

Common configuration is an app-level shared snippet. Matching keys override connection values under the actual merge rules; this is not default inheritance. Changing the snippet affects connections that use it. Saving a draft leaves the shared content unchanged; an explicit apply commits the change.

Supported built-in apps also provide Test URL, Fetch models, and Check balance for an HTTP response, model catalog, or compatible balance endpoint. None proves that a real model request succeeds. Recheck after changing the configuration, then verify with a real request from the target tool.

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 applying edits or switching an existing connection:

  1. Review the generated file and path.
  2. Confirm Configuration written, or finish confirmation in the external app. Saving a draft alone does not write the target.
  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 Only a draft was saved without applying, 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 apply fails Incorrect JSON/YAML node type; invalid content can still be saved as a draft

App-specific field guides

To bring in connections from an older manager, use Migrate from cc-switch instead of copying every entry by hand.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close