Connect Codex

Codex'i terminalinizde veya ChatGPT masaüstü uygulamasında modeller, MCP araçları ve Unity Gateway üzerinden becerilerle kullanın. Erişimi yapılandırmak için Unity Gateway CLI'yı (ug) kullanın veya bağlantıyı manuel olarak yapılandırmak için.

Araçları mevcut bir Codex kurulumuna bağlamak için Add MCP tools bölümüne gidin.

Prerequisites

Azure Databricks çalışma alanı URL'nize ve kullanmak istediğiniz modellere, MCP'lere ve becerilere erişiminiz olmalıdır. Codex'in en son sürümünü veya ChatGPT masaüstü uygulamasını yükleyin.

Yöneticiniz cihazınızı zaten yapılandırmaysa, kuruluşunuzun başlatma talimatlarını takip edin.

Terminaldeki Codex

Install ug, sonra proje dizininizden şu komutu çalıştırın:

ug codex

İş alanınızı seçmek ve giriş yapmak için talimatları takip edin. ug bağlantıyı yapılandırır ve terminalinizde Codex'i açar. Zaten kullandığınız aynı istemleri ve komutları kullanmaya başlayın. Modelleri değiştirmek için /model girin.

Codex'in verilere ve paylaşılan talimatlara erişmesini sağlamak için MCP araçları veya yetenekler ekleyerek devam edin.

ChatGPT masaüstü

macOS ve Linux'ta, bu komutu etkileşimli bir terminalde kurun ug ve çalıştırın:

ug configure --agents codex

İş alanınızı seçin ve giriş yapın. Eğer istenirse, sistem yapılandırma güncellemesini cihaz şifrenizle onaylayın. ug Unity Gateway bağlantısını ve OAuth token yenilemesini yapılandırıyor.

Masaüstü uygulamasını açın veya yeniden başlatın ve bir Codex sohbeti başlatın. Model seçiciyi kullanarak modelleri değiştirin. Komut ug codex terminal ajanını açar; yapılandırmadan sonra masaüstü uygulamasını normalde açın.

Windows'ta, aşağıdaki manuel model yapılandırmasını kullanın. Yine de araçlar ve beceriler eklemek için ug mcp add ve ug skills add kullanabilir, ardından uygulamayı yeniden başlatabilirsiniz.

Modelleri manuel olarak yapılandırmak

Bu ayarlar hem terminal ajanı hem de masaüstü uygulaması için geçerlidir. Codex'i kapatın, sonra açın veya oluşturun ~/.codex/config.toml. Windows'da kullanın %USERPROFILE%\.codex\config.toml.

Aşağıdaki ayarları dosyaya birleştirin. model ile model_provider öğelerini üst düzeyde, tüm tablo başlıklarından önce tutun ve diğer ayarları koruyun.

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>" }

Model yer tutucusunu tam Unity Kataloğu adıyla, <workspace-hostname> çalışma alanı ana adınızla ve <databricks-pat> kişisel erişim tokenınızla değiştirin. Bu örnek tokenı yerel olarak saklar; dosyayı gizli tutun ve kendi tokenınızı kullanın.

Proje dizininizden çalıştırın codex veya masaüstü uygulamasını yeniden açın. Cihazınızda yönetilen sağlayıcı ayarları varsa, yöneticilerinizden bunları güncellemesini iste; bu ayarlar bu kullanıcı yapılandırmasından önceliklidir.

Saha detayları için OpenAI'nin yapılandırma referansına bakınız.

MCP araçları ekleyin

system.ai.sandbox, system.ai.web_search veya system.ai.dbsql kullanmak için, bir hesap yöneticisinin hesap konsolundaki Previews sayfasından Unity Gateway beta sürümünü etkinleştirmesi gerekir. Hesap önizlemelerini yönet'e bakın.

  1. Çalışma alanında Unity Gateway > MCP'lerini açın. Dahili bir MCP seçin veya harici MCP sunucunuzu kaydedin.
  2. MCP'nin tam adını kopyalayın, örneğin system.ai.github veya <catalog>.<schema>.<service>.
  3. MCP'ye erişiminiz olduğunu doğrulayın.

Unity Gateway CLI'sini kullanın

Yükleyin ug, sonra MCP'yi Codex'e ekleyin:

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

Yer tutucu metni kopyaladığınız adla değiştirin. Örneğin, --names system.ai.github GitHub için kullanın. Hizmetleri etkileşimli olarak seçmek için --names öğesini çıkarın.

İlk kurulumda, çalışma alanınızı seçmek, giriş yapmak ve bir model seçmek için talimatları takip edin. ug hem model hem de MCP erişimini yapılandırır ve kimlik bilgilerini yeniler. Kendi OAuth uygulamanızla MCP erişimi için aşağıdaki manuel kurulumu kullanın.

Codex'i ug codex yeniden başlatın veya masaüstü uygulamasını yeniden açın, sonra bir aracı test edin.

MCP'leri manuel olarak yapılandırın

Giriş yapmak ve kimlik bilgilerini yenilemek için public Azure Databricks OAuth uygulamasını kullanın. Bu ayarlar terminal aracısı ve masaüstü uygulaması için geçerlidir.

Bir OAuth uygulaması kur

  1. Codex'i kapat. ~/.codex/config.toml içinde, bu ayarları en üst seviyeye, tablo başlıklarından önce ekleyin. Yerel OAuth geri çağrısına sabit bir port veriyorlar:

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

  2. Bir hesap yöneticisinden hesap konsolundaAyarlar > Uygulama bağlantıları > Bağlantı ekle seçeneğini açmasını isteyin. codex-mcp gibi bir ad kullanın, İstemci sırrı oluştur seçimini kaldırın, yönlendirme URL'sini http://127.0.0.1:8080/callback olarak ayarlayın ve ai-gateway kapsamını seçin. İstemci Kimliği'ni kaydedip kopyalayın. Bkz. OAuth uygulaması oluşturma.

  3. MCP'yi Codex'te, yer tutucuları değiştirerek kaydedin:

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

  4. Codex tarafından gösterilen geri çağrı URL'sini kontrol edin. Sunucuya özgü bir ek eki içerebilir. Yönetici, giriş yapmadan önce OAuth uygulamasının yönlendirme URL'lerine tam olarak o URL'yi eklesin. Başka bir sunucu eklerken bu kontrolü tekrarlayın.

  5. Giriş yapın, sonra Codex'i yeniden açın:

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

Geri çağrı ayarları için OpenAI'nin MCP kimlik doğrulama talimatlarına bakınız. Sonra bir aracı deneyin.

Yerel test için kişisel erişim tokenı kullanın

Sunucu adını ve belirteci değiştirerek aşağıdakileri ~/.codex/config.toml ekleyin:

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

Başka bir MCP için, mcp_servers altında benzersiz bir ad kullanın ve system.ai.dbsql öğesini tam adıyla değiştirin. Dosyayı gizli tutun, sonra Codex'i yeniden başlatın ve bir aracı test edin.

MCP aracını test edin

  1. Codex'te /mcp girin ve sunucunun bağlı olduğundan emin olun.
  2. Codex'ten o sunucunun araçlarını listelemesini iste, ardından okuma işlemi talep et. GitHub için, erişebileceğiniz bir depoda bir sorun bulmasını isteyin. Özel sunucu için, kayıt sırasında test ettiğiniz bir araç ve girdileri kullanın.
  3. Bir araç çağrısı giriş yapmanızı isterse, MCP tarafından geri gönderilen giriş bağlantısını açın, sağlayıcı onayını tamamlayın ve çağrıyı yeniden deneyin. Bu oturum açma işlemi MCP'ye dış hesabınıza erişim sağlar.
  4. Codex'in bir araç çağrısı yapıp sonucunu geri döndürdüğünü kontrol edin. Sadece bir metin yanıtı bağlantıyı doğrulamaz.

Azure Databricks verilerini kullanmak için, iş soruları için system.ai.dbsql veya SQL için system.ai.genie_one_mcp bağlanın. Örneğin, SQL MCP'den SELECT 1 AS result çalıştırmasını isteyin.

İzinler, politikalar ve kullanım için bkz. MCP'yi yönet.

Beceri ekleme

Unity Gateway CLI'sini kullanın

Etkileşimli seçiciyi çalıştırın:

ug skills add

Ya da yayımlanmış belirli bir beceriyi indirin:

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

Codex'i veya masaüstü uygulamasını yeniden başlatın. İndirilen beceriler ~/.agents/skills/ içinde yerel olarak kullanılabilir. Güncellenmiş bir sürüm edinmek için indirmeyi yeniden çalıştırın.

Bir şemanın yeteneklerini MCP üzerinden ortaya çıkarmak için şunu izleyin:

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

Beceri kaydını manuel olarak bağlayın

aşağıdakini ekleyin ~/.codex/config.toml:

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

Ana bilgisayar adını ve token'ı değiştirin. URL'deki sondaki eğik çizgiyi koruyun. Codex'i yeniden başlatın ve yayımlanmış bir beceriyi kullanmasını iste, örneğin Use <catalog>.<schema>.<skill-name> to review this query.

Kayıt defteri, beceri talimatlarını MCP üzerinden yükler. Zaten sahip olduğunuz beceri dosyalarını yüklemek için, SKILL.md ve paketlenmiş dosyalar dahil olmak üzere beceri klasörünün tamamını ~/.agents/skills/ içine yerleştirin.

Unity Gateway yetenekleri Beta'da. Etkinleştirme ve izinler için Yönetim becerileri bölümünü inceleyebilirsiniz.

Troubleshooting

  • Masaüstü uygulaması hâlâ OpenAI giriş istiyor: macOS veya Linux'ta, etkileşimli olarak tekrar çalıştırın ug configure --agents codex ve sistem yapılandırma güncellemesini tamamlayın. Sadece CLI profili masaüstü uygulamasını yapılandırmaz. Manuel kurulum için, bunun model_provider en üst seviyede olduğundan ve requires_openai_auth = false sağlayıcı tablosunda olduğundan emin olun. Bu bayrağı, OAuth token yenileme için tablo kullanan auth bir sağlayıcıya eklemeyin.

  • İstekler bir WebSocket hatasıyla başarısız olur:supports_websockets = false değerini etkin Azure Databricks sağlayıcı tablosunda ayarlayın. Eğer yöneticiniz bu yapılandırmayı yönetiyorsa, güncellemelerini iste. Sonra uygulamayı yeniden başlatın.

  • Bir model eksik: Model izinlerinizi kontrol edin. model öğesini etkin yapılandırmada tam Unity Catalog adı olarak ayarlayın ve yeni bir konuşma başlatın.

  • Bir MCP veya beceri bağlantısı başarısız olursa: URL, izinler ve bağlantı hatasını kontrol edin. Manuel bağlantılar için token süresi dolmasını da kontrol edin. ug kurulum sorunları için ug doctor komutunu çalıştırın. İndirilen bir yetenek, kayıt bağlantısı arızalansa bile kullanılabilir kalabilir.

  • Workspace oturum açma çalışıyor, ancak bir araç sizden oturum açmanızı istiyor: MCP tarafından döndürülen oturum açma bağlantısını açın, harici sağlayıcıda oturum açın, ardından çağrıyı yeniden deneyin. İş alanı ve sağlayıcı oturum açma ayrı adımlardır.

  • OAuth bir yönlendirme uyumsuzluğu bildiriyor veya bağlantı zaman aşımına uğruyor: OAuth uygulamasının yönlendirme URL'sini, Codex'in rapor ettiği tam URL ile herhangi bir son ek de dahil olmak üzere eşleştirin ve ağ erişimini kontrol edin. OAuth uygulaması değişikliklerinin etkili olması 30 dakikayı bulabilir.

Sonraki Adımlar

  • Son güncelleştirme: