Connect Codex

Korzystaj z Codexu w terminalu lub w aplikacji desktopowej ChatGPT z modelami, narzędziami MCP i umiejętnościami przez Unity Gateway. Użyj CLI Unity Gateway ()ug do skonfigurowania dostępu lub ręcznej konfiguracji połączenia.

Aby połączyć narzędzia z istniejącym systemem Codex, przejdź do Dodaj narzędzia MCP.

Prerequisites

Potrzebujesz adresu URL do swojego workspace Azure Databricks oraz dostępu do modeli, MCP i umiejętności, których chcesz używać. Zainstaluj najnowszą wersję Codex lub aplikację desktopową ChatGPT.

Jeśli administrator już skonfigurował urządzenie, postępuj zgodnie z instrukcjami uruchomienia organizacji.

Kodeks w terminalu

Instaluj ug, a następnie uruchom to polecenie z katalogu projektu:

ug codex

Postępuj zgodnie z instrukcjami, aby wybrać swoją przestrzeń pracy i zalogować się. ug konfiguruje połączenie i otwiera Codex w terminalu. Zacznij pracować z tymi samymi promptami i komendami, których już używasz. Aby zmienić model, wpisz /model.

Kontynuuj dodawanie narzędzi MCP lub dodawaj umiejętności, aby dać Codexowi dostęp do danych i udostępnianych instrukcji.

Aplikacja komputerowa ChatGPT

Na macOS i Linux zainstaluj ug i wykonaj to polecenie w interaktywnym terminalu:

ug configure --agents codex

Wybierz swoją przestrzeń roboczą i zaloguj się. Jeśli zostanie o to zapytany, zatwierdz aktualizację konfiguracji systemu hasłem do urządzenia. ug konfiguruje połączenie z Unity Gateway oraz odświeżanie tokenów OAuth.

Otwórz lub zrestartuj aplikację desktopową i rozpocznij rozmowę w Codex. Użyj selektora modeli, aby zmienić model. Polecenie ug codex otwiera agenta terminala; po konfiguracji normalnie otwórz aplikację desktopową.

Na Windows użyj ręcznej konfiguracji modelu poniżej. Nadal możesz używać ug mcp add i ug skills add dodawać narzędzia oraz umiejętności, a potem restartować aplikację.

Konfiguruj modele ręcznie

Te ustawienia dotyczą zarówno agenta terminala, jak i aplikacji desktopowej. Zamknij Codex, następnie otwórz lub utwórz ~/.codex/config.toml. W systemie Windows użyj polecenia %USERPROFILE%\.codex\config.toml.

Połącz poniższe ustawienia z plikiem. Zachowaj model i model_provider na najwyższym poziomie, przed nagłówkami tabeli, i zachowaj niepowiązane ustawienia.

model = "<catalog>.<schema>.<model-name>"
model_provider = "databricks"

[model_providers.databricks]
name = "Databricks"
base_url = "https://<workspace-hostname>/ai-gateway/codex/v1"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
http_headers = { Authorization = "Bearer <databricks-pat>" }

Zastąp symbol zastępczy modelu jego pełną nazwą w Unity Catalog, element <workspace-hostname> nazwą hosta obszaru roboczego, a element <databricks-pat> swoim osobistym tokenem dostępu. Ten przykład przechowuje token lokalnie; zachowaj plik prywatny i używaj własnego tokena.

Uruchom codex z katalogu projektu lub ponownie otwórz aplikację desktopową. Jeśli Twoje urządzenie ma zarządzane ustawienia operatora, poproś administratora o ich aktualizację; te ustawienia mają pierwszeństwo przed tą konfiguracją użytkownika.

Zobacz informacje referencyjne dotyczące konfiguracji OpenAI, aby poznać szczegóły pól.

Dodaj narzędzia MCP

Aby używać system.ai.dbsql, system.ai.sandbox lub system.ai.web_search, administrator konta musi włączyć wersję beta Unity Gateway na stronie Podglądy w konsoli konta. Zobacz Podglądy konta.

  1. Otwórz Unity Gateway MCPs > w swoim workspace. Wybierz wbudowany MCP lub zarejestruj swój zewnętrzny serwer MCP.
  2. Skopiuj pełne imię i nazwisko MCP, takie jak system.ai.github lub <catalog>.<schema>.<service>.
  3. Potwierdź, że masz dostęp do MCP.

Użyj narzędzia Unity Gateway CLI

Zainstaluj ug, a następnie dodaj MCP do Codexu:

ug mcp add --agents codex --names <catalog>.<schema>.<service>

Zastąp symbol zastępczy nazwą, którą skopiowałeś. Na przykład w przypadku GitHub użyj --names system.ai.github. Aby wybierać usługi interaktywnie, pomiń --names.

Przy pierwszej konfiguracji postępuj zgodnie z instrukcjami, aby wybrać obszar roboczy, zalogować się i wybrać model. ug konfiguruje zarówno dostęp do modelu, jak i MCP oraz odświeża poświadczenia uwierzytelniające. Aby uzyskać dostęp do MCP za pomocą własnej aplikacji OAuth, skorzystaj z instrukcji konfiguracji poniżej.

Zrestartuj Codex za pomocą ug codex, albo ponownie otwórz aplikację desktopową, a potem przetestuj narzędzie.

Konfiguruj MCPs ręcznie

Użyj publicznej aplikacji Azure Databricks OAuth, aby się zalogować i odświeżyć poświadczenia uwierzytelniające. Te ustawienia dotyczą agenta terminala i aplikacji desktopowej.

Ustaw aplikację OAuth

  1. Zamknij Codex. W ~/.codex/config.toml, dodaj te ustawienia na najwyższym poziomie, przed nagłówkami tabel. Przypisują lokalnemu callbackowi OAuth stały port:

    mcp_oauth_callback_port = 8080
mcp_oauth_callback_url = "http://127.0.0.1:8080/callback"

  2. Niech administrator konta otworzy Ustawienia > Połączenia aplikacji > Dodaj połączenie w konsoli konta. Użyj nazwy takiej jak codex-mcp, wyczyść Wygeneruj sekret klienta, ustaw adres URL przekierowania na http://127.0.0.1:8080/callback i wybierz zakres ai-gateway. Zapisz i skopiuj identyfikator klienta. Zobacz Stwórz aplikację OAuth.

  3. Zarejestruj MCP w Codex, zastępując zastępcze oznaczenia:

    codex mcp add databricks-tools \
  --url "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>" \
  --oauth-client-id <client-id>

  4. Sprawdź URL callbacku wyświetlony przez Codex. Może zawierać przyrostek specyficzny dla serwera. Niech administrator doda dokładnie ten adres URL do adresów URL przekierowań aplikacji OAuth przed zalogowaniem. Powtórz ten test przy dodawaniu kolejnego serwera.

  5. Zaloguj się, a następnie ponownie otwórz Codex:

    codex mcp login databricks-tools --scopes ai-gateway,offline_access

Aby poznać ustawienia callback, zobacz instrukcje uwierzytelniania MCP w OpenAI. Następnie przetestuj narzędzie.

Użyj osobistego tokena dostępu do testów lokalnych

Dodaj następujące do ~/.codex/config.toml, zastępując nazwę hosta i token:

[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql"
http_headers = { Authorization = "Bearer <databricks-pat>" }

W przypadku innego MCP użyj unikalnej nazwy pod mcp_servers i zastąp system.ai.dbsql jego pełną nazwą. Zachowaj plik jako prywatny, potem zrestartuj Codex i przetestuj narzędzie.

Przetestuj narzędzie MCP

  1. W Codex wprowadź /mcp i sprawdź, czy serwer jest połączony.
  2. Poproś Codex o wylistowanie narzędzi tego serwera, a następnie poproś o operację odczytu. W GitHubie poproś go, żeby znalazł zgłoszenie w repozytorium, do którego masz dostęp. Do serwera niestandardowego użyj narzędzia i danych wejściowych, które przetestowano podczas rejestracji.
  3. Jeśli wywołanie narzędzia wymaga zalogowania, otwórz link logowania zwrócony przez MCP, dokończ wyrażenie zgody u dostawcy, a następnie ponów wywołanie. To logowanie daje MCP dostęp do Twojego konta zewnętrznego.
  4. Sprawdź, czy Codex wykonuje wywołanie narzędzia i zwraca wynik. Sama odpowiedź tekstowa nie potwierdza połączenia.

Aby korzystać z danych Azure Databricks, połącz się z system.ai.genie_one_mcp w przypadku pytań biznesowych lub z system.ai.dbsql w przypadku SQL. Na przykład, poproś SQL MCP o uruchomienie SELECT 1 AS result.

Informacje o uprawnieniach, politykach i użytkowaniu znajdziesz w Zarządzanie MCP.

Dodawanie umiejętności

Użyj narzędzia Unity Gateway CLI

Uruchom interaktywny picker:

ug skills add

Albo pobierz konkretną opublikowaną umiejętność:

ug skills add --names <catalog>.<schema>.<skill-name>

Zrestartuj Codex lub aplikację desktopową. Pobrane umiejętności są dostępne lokalnie w ~/.agents/skills/. Uruchom ponowne pobranie, aby uzyskać zaktualizowaną wersję.

Aby zamiast tego udostępnić możliwości schematu za pośrednictwem MCP, uruchom:

ug skills add --location "<catalog>.<schema>" --via mcp

Podłącz rejestr umiejętności ręcznie

Dodaj następujące do ~/.codex/config.toml:

[mcp_servers.databricks-skill-registry]
url = "https://<workspace-hostname>/ai-gateway/skills/"
http_headers = { Authorization = "Bearer <databricks-pat>" }

Zamień nazwę hosta i token. Zachowaj ukośnik na końcu adresu URL. Restartuj Codex i poproś go o użycie opublikowanej umiejętności, takiej jak Use <catalog>.<schema>.<skill-name> to review this query.

Rejestr ładuje instrukcje umiejętności przez MCP. Aby zainstalować pliki umiejętności, które już masz, umieść cały folder umiejętności, w tym SKILL.md i dołączone pliki, w ~/.agents/skills/.

Umiejętności Unity Gateway są w fazie beta. Zobacz Zarządzanie umiejętnościami dla umożliwień i uprawnień.

Troubleshooting

  • Aplikacja desktopowa nadal prosi o logowanie do OpenAI: Na macOS lub Linux uruchom ug configure --agents codex interaktywnie i zakończ aktualizację konfiguracji systemu. Sam profil CLI nie konfiguruje aplikacji desktopowej. W przypadku ręcznej konfiguracji sprawdź, czy model_provider znajduje się na najwyższym poziomie, a requires_openai_auth = false w tabeli dostawców. Nie dodawaj tej flagi do dostawcy, który używa tabeli auth do odświeżania tokenów OAuth.

  • Wysyłanie żądań kończy się niepowodzeniem z powodu błędu WebSocket: Ustaw supports_websockets = false w tabeli aktywnego dostawcy Azure Databricks. Jeśli administrator zarządza tą konfiguracją, poproś go o aktualizację. Następnie zrestartuj aplikację.

  • Brakuje modelu: Sprawdź uprawnienia modelu. Ustaw dla model pełną nazwę Unity Catalog w aktywnej konfiguracji i rozpocznij nową rozmowę.

  • Połączenie MCP lub umiejętności nie działa: Sprawdź adres URL, uprawnienia i błąd łącznika. W przypadku ręcznych podłączeń sprawdź też wygaśnięcie tokenów. W przypadku problemów z ug konfiguracją uruchom ug doctor. Pobrana umiejętność może pozostać dostępna nawet w przypadku awarii połączenia z rejestrem.

  • Logowanie w Workspace działa, ale narzędzie prosi o zalogowanie: Otwórz link logowania zwrócony przez MCP, zaloguj się u zewnętrznego dostawcy, a następnie ponów wywołanie. Workspace i logowanie dostawcy to osobne etapy.

  • OAuth zgłasza niedopasowanie przekierowania lub czas wygaśnięcia połączenia: Dopasuj adres URL aplikacji OAuth do dokładnego URL, który raportuje Codex, w tym dowolnego sufiksu, i sprawdź dostęp do sieci. Zmiany w aplikacji OAuth mogą wejść w życie do 30 minut.

Następne kroki

  • Ostatnia aktualizacja o