Hubungkan Codex

Gunakan Codex di terminal Anda atau aplikasi desktop ChatGPT dengan model, alat MCP, dan keterampilan melalui Unity Gateway. Gunakan CLI Unity Gateway (ug) untuk mengonfigurasi akses, atau mengonfigurasi koneksi secara manual.

Untuk menghubungkan alat ke pengaturan Codex yang sudah ada, buka Tambah alat MCP.

Prerequisites

Anda membutuhkan URL workspace Azure Databricks Anda dan akses ke model, MCP, dan keterampilan yang ingin Anda gunakan. Instal versi terbaru Codex atau aplikasi desktop ChatGPT.

Jika admin Anda sudah mengonfigurasi perangkat Anda, ikuti instruksi peluncuran organisasi Anda.

Codex di terminal

Instal, uglalu jalankan perintah ini dari direktori proyek Anda:

ug codex

Ikuti petunjuk untuk memilih ruang kerja Anda dan masuk. ug mengonfigurasi koneksi dan membuka Codex di terminal Anda. Mulailah bekerja dengan prompt dan perintah yang sama yang sudah Anda gunakan. Untuk mengubah model, masukkan /model.

Lanjutkan dengan Menambahkan alat MCP atau Menambahkan keterampilan untuk memberikan akses Codex ke data dan instruksi yang dibagikan.

Desktop ChatGPT

Di macOS dan Linux, instal ug dan jalankan perintah ini di terminal interaktif:

ug configure --agents codex

Pilih ruang kerja Anda dan masuk. Jika diminta, setujui pembaruan konfigurasi sistem dengan kata sandi perangkat Anda. ug mengonfigurasi koneksi Unity Gateway dan penyegaran token OAuth.

Buka atau restart aplikasi desktop dan mulai percakapan Codex. Gunakan pemilih model untuk mengganti model. Perintah ug codex membuka agen terminal; buka aplikasi desktop seperti biasa setelah konfigurasi.

Di Windows, gunakan konfigurasi model manual di bawah ini. Anda masih bisa menggunakan ug mcp add dan ug skills add menambahkan alat serta keterampilan, lalu restart aplikasi.

Konfigurasikan model secara manual

Pengaturan ini berlaku untuk terminal agent dan aplikasi desktop. Tutup Codex, lalu buka atau buat ~/.codex/config.toml. Di Windows, gunakan %USERPROFILE%\.codex\config.toml.

Gabungkan pengaturan berikut ke dalam file. Simpan model dan model_provider di tingkat atas, sebelum header tabel apa pun, dan pertahankan pengaturan yang tidak terkait.

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

Ganti placeholder model dengan nama Unity Catalog lengkapnya, <workspace-hostname> dengan nama host workspace Anda, dan <databricks-pat> dengan token akses pribadi Anda. Contoh ini menyimpan token secara lokal; jaga file tetap privat dan gunakan token Anda sendiri.

Jalankan codex dari direktori proyek Anda atau buka kembali aplikasi desktop. Jika perangkat Anda memiliki pengaturan provider yang dikelola, minta admin Anda memperbaruinya; pengaturan tersebut lebih diutamakan daripada konfigurasi pengguna ini.

Lihat referensi konfigurasi OpenAI untuk detail setiap kolom.

Tambahkan alat MCP

Untuk menggunakan system.ai.dbsql, system.ai.sandbox, atau system.ai.web_search, admin akun harus mengaktifkan beta Unity Gateway dari halaman Pratinjau konsol akun. Lihat Kelola pratinjau akun.

  1. Buka MCP Unity Gateway > di ruang kerja Anda. Pilih MCP bawaan atau daftarkan server MCP eksternal Anda.
  2. Salin nama lengkap MCP, seperti system.ai.github atau <catalog>.<schema>.<service>.
  3. Pastikan Anda memiliki akses ke MCP.

Gunakan CLI Unity Gateway

Instal, uglalu tambahkan MCP ke Codex:

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

Ganti placeholder dengan nama yang Anda salin. Misalnya, gunakan --names system.ai.github untuk GitHub. Untuk memilih layanan secara interaktif, hilangkan --names.

Saat penyiapan awal, ikuti petunjuk untuk memilih ruang kerja Anda, masuk, dan memilih model. ug mengonfigurasi akses model dan MCP keduanya serta memperbarui kredensial. Untuk akses MCP dengan aplikasi OAuth Anda sendiri, gunakan pengaturan manual di bawah ini.

Restart Codex dengan ug codex, atau buka kembali aplikasi desktop, lalu uji alat.

Konfigurasikan MCP secara manual

Gunakan aplikasi publik Azure Databricks OAuth untuk masuk dan memperbarui kredensial. Pengaturan ini berlaku untuk terminal agent dan aplikasi desktop.

Siapkan aplikasi OAuth

  1. Tutup Codex. Di ~/.codex/config.toml, tambahkan pengaturan ini pada level teratas, sebelum header tabel apa pun. Mereka memberikan callback OAuth lokal port yang tetap:

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

  2. Minta admin akun membuka Pengaturan > Koneksi aplikasi > Tambahkan koneksi di konsol akun. Gunakan nama seperti codex-mcp, hapus centang Buat rahasia klien, atur URL pengalihan ke http://127.0.0.1:8080/callback, dan pilih cakupan ai-gateway. Simpan dan salin Client ID. Lihat Buat aplikasi OAuth.

  3. Daftarkan MCP di Codex, menggantikan placeholder:

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

  4. Periksa URL callback yang dicetak oleh Codex. Dapat menyertakan akhiran khusus server. Minta admin menambahkan URL tersebut persis ke URL pengalihan aplikasi OAuth sebelum login. Ulangi pemeriksaan ini saat menambahkan server lain.

  5. Masuk, lalu buka kembali Codex:

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

Untuk pengaturan callback, lihat instruksi otentikasi MCP OpenAI. Lalu uji alat.

Gunakan token akses pribadi untuk pengujian lokal

Tambahkan hal berikut ke ~/.codex/config.toml, menggantikan hostname dan token:

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

Untuk MCP lain, gunakan nama unik di bawah mcp_servers dan ganti system.ai.dbsql dengan nama lengkapnya. Jaga file tetap privat, lalu restart Codex dan uji alat.

Uji alat MCP

  1. Di Codex, masukkan /mcp dan periksa apakah server terhubung.
  2. Minta Codex untuk mencantumkan tool server tersebut, lalu minta operasi baca. Untuk GitHub, mintalah untuk menemukan masalah di repositori yang bisa Anda akses. Untuk server kustom, gunakan alat dan input yang Anda uji saat registrasi.
  3. Jika panggilan alat meminta Anda untuk masuk, buka tautan login yang dikembalikan oleh MCP, selesaikan persetujuan penyedia, lalu coba lagi panggilan. Proses masuk ini memberikan akses kepada MCP ke akun eksternal Anda.
  4. Periksa bahwa Codex melakukan panggilan alat dan mengembalikan hasilnya. Jawaban lewat pesan teks saja tidak bisa memverifikasi koneksi.

Untuk menggunakan data Azure Databricks, sambungkan ke system.ai.genie_one_mcp untuk pertanyaan bisnis atau system.ai.dbsql untuk SQL. Misalnya, minta SQL MCP untuk menjalankan SELECT 1 AS result.

Untuk izin, kebijakan, dan penggunaan, lihat Tata kelola MCP.

Menambahkan keterampilan

Gunakan CLI Unity Gateway

Jalankan pemilih interaktif:

ug skills add

Atau unduh keterampilan spesifik yang dipublikasikan:

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

Restart Codex atau aplikasi desktop. Keahlian yang diunduh tersedia secara lokal di ~/.agents/skills/. Jalankan ulang unduhan untuk mendapatkan versi yang diperbarui.

Untuk mengekspos skill milik skema melalui MCP sebagai gantinya, jalankan:

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

Sambungkan registri keterampilan secara manual

Tambahkan hal berikut ke ~/.codex/config.toml:

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

Ganti nama host dan token. Pertahankan garis miring di bagian belakang URL. Restart Codex dan minta menggunakan skill yang sudah dipublikasikan, seperti Use <catalog>.<schema>.<skill-name> to review this query.

Registri memuat instruksi skill melalui MCP. Untuk menginstal berkas skill yang sudah Anda miliki, tempatkan folder skill lengkap, termasuk SKILL.md dan file yang dibundel, di ~/.agents/skills/.

Keterampilan Unity Gateway masih dalam tahap Beta. Lihat Mengatur keterampilan untuk pemberdayaan dan izin.

Troubleshooting

  • Aplikasi desktop masih meminta masuk OpenAI: Di macOS atau Linux, jalankan ug configure --agents codex ulang secara interaktif dan selesaikan pembaruan konfigurasi sistem. Profil CLI saja tidak mengonfigurasi aplikasi desktop. Untuk pengaturan manual, periksa apakah ada model_provider di level atas dan requires_openai_auth = false ada di tabel provider. Jangan tambahkan flag tersebut ke penyedia yang menggunakan auth tabel untuk penyegaran token OAuth.

  • Permintaan gagal dengan kesalahan WebSocket: Atur supports_websockets = false di tabel penyedia Azure Databricks yang aktif. Jika admin Anda mengelola konfigurasi itu, minta mereka memperbaruinya. Restart aplikasi setelahnya.

  • Model tidak ditemukan: Periksa izin akses model Anda. Atur model ke nama Unity Catalog lengkap di konfigurasi aktif dan mulai percakapan baru.

  • Koneksi MCP atau skill gagal: Periksa URL, izin, dan kesalahan konektor. Untuk koneksi manual, juga periksa kedaluwarsa token. Untuk masalah penyiapan ug, jalankan ug doctor. Skill yang diunduh dapat tetap tersedia meskipun koneksi registry gagal.

  • Login ke workspace berfungsi, tetapi sebuah alat meminta Anda untuk masuk: Buka tautan login yang dikembalikan oleh MCP, masuk ke penyedia eksternal, lalu coba lagi permintaan. Proses masuk ke Workspace dan penyedia adalah langkah yang terpisah.

  • OAuth melaporkan ketidakcocokan pengalihan atau koneksi mengalami time-out: Cocokkan URL pengalihan aplikasi OAuth dengan URL persis yang dilaporkan Codex, termasuk akhiran apa pun, dan periksa akses jaringan. Perubahan aplikasi OAuth dapat memakan waktu hingga 30 menit untuk berlaku.

Langkah berikutnya

  • Terakhir diperbarui pada