# Claude Code'u genişletmek: Yabancı modelleri yönlendirmek ve Codex'i ikinci bir agent olarak kullanmak

**Ders materyali** · „Yapay Zekâ Tasarımı" Modülü / Agentic AI
**Format:** Claude AI Design için handoff · kurs katılımcılarıyla serbestçe paylaşılabilir
**Kapsam:** birbiri üzerine kurulu iki oturum (her biri yakl. 90 dk.)

---

## Bu belge hakkında

Bu materyal, bağımsız olarak işlenebilen veya birleştirilebilen iki bölümden oluşur:

- **Bölüm 1 – Model yönlendirme:** Claude Code'un başka bir sağlayıcıya (burada Z.ai
  üzerinden GLM-5.2) nasıl yönlendirileceği, böylece *Opus* gibi alışılmış katmanların
  yabancı bir modele erişmesi.
- **Bölüm 2 – Codex eklentisi:** `openai/codex-plugin-cc` ile Claude Code içine ikinci,
  bağımsız bir kodlama agent'ının (Codex) nasıl entegre edileceği.

Her iki bölümün ortak fikri: **Claude Code açıktır.** Arkasındaki *modeli*
değiştirebilirsiniz (Bölüm 1) ve yanına *ek agent'lar* koyabilirsiniz (Bölüm 2). Her iki
teknik birbirinden bağımsızdır ve hatta aynı anda kullanılabilir.

> **Katılımcılar için önemli bağlantı:** Claude Code'u yönlendirme yoluyla GLM'e
> yönlendirdiğinizde, *yalnızca Claude Code* GLM üzerinden çalışır. Codex eklentisi ise
> ayrı Codex oturumunu ve OpenAI modellerini kullanmaya devam eder. İki yol birbirini
> etkilemez — ancak ayrı ayrı faturalandırılır.

---

## Ortak öğrenme hedefleri

Her iki oturumun ardından katılımcılar şunları yapabilir:

1. Claude Code'un ortam değişkenleri üzerinden nasıl yapılandırıldığını açıklamak;
2. Claude Code'u Anthropic uyumlu bir yabancı uç noktaya yönlendirmek;
3. katman takma adlarını (opus/sonnet/haiku) herhangi bir modele eşlemek;
4. Marketplace üzerinden bir eklenti kurmak ve ayarlamak;
5. incelemeler ve devredilen görevler için ikinci bir agent kullanmak;
6. her iki yaklaşımın risklerini adlandırmak (maliyetler, veri yolları, agent döngüleri,
   güven sınırları).

---
---

# BÖLÜM 1 — Claude Code'da yabancı modelleri yönlendirmek (örnek: GLM-5.2)

## 1.1 Temel prensip

Claude Code varsayılan olarak `api.anthropic.com` ile konuşur. Bir ayar dosyasındaki
`env` bloğu üzerinden bu hedef uç nokta tamamen başka yöne çevrilebilir. Artık birden
fazla sağlayıcı **Anthropic uyumlu bir uç nokta** sunuyor — Z.ai'nin (Zhipu AI, GLM
ailesi) yanı sıra örneğin Kimi ile Moonshot ve MiniMax de. Bunlarda yönlendirme, ek bir
proxy olmadan gerçek bir drop-in ikame olarak çalışır. GLM-5.2 burada örnek olarak
kullanılıyor; Kimi veya MiniMax de aynı `env` değişkenleri üzerinden entegre edilir —
yalnızca temel URL ve model ID'leri değiştirilir (ör. Z.ai için
`https://api.z.ai/api/anthropic`).

**Asıl püf noktası:** Claude Code dahili olarak yalnızca *katman takma adları* olan
`opus`, `sonnet` ve `haiku`'yu tanır. `ANTHROPIC_DEFAULT_*_MODEL` değişkenleri
üzerinden her katmanı somut bir GLM modeline eşlersiniz. CLI'da `/model opus` seçtiğinizde
istek aslında `glm-5.2`'ye gider.

```
   Sen (terminalde)
        │
        ▼
   Claude Code ──ANTHROPIC_BASE_URL──►  api.z.ai/api/anthropic
        │                                     │
   /model opus                          isteği çevirir
        │                                     ▼
   şununla eşler:                        GLM-5.2 yanıt verir
   ANTHROPIC_DEFAULT_OPUS_MODEL          Anthropic formatında
```

## 1.2 Ön koşullar

| Ön koşul | Ayrıntılar |
|---|---|
| Z.ai hesabı | Z.ai Open Platform'da kayıt |
| API anahtarı | „API Keys" bölümünde oluşturun |
| Coding planı | GLM Coding erişimi için abonelik (kota tabanlı; GLM-5.2 dahil) |
| Claude Code | güncel olarak kurulu |

## 1.3 Adım adım

**Adım 1 — API anahtarını edinin.** Z.ai Open Platform'da kayıt olun, „API Keys"
altında bir anahtar oluşturun ve kopyalayın.

**Adım 2 — Ayar dosyasını açın.**
- *Projeye özgü* (anahtarlar için önerilir): repo kök dizininde
  `.claude/settings.local.json`. Bu dosya varsayılan olarak Git tarafından yok sayılır.
- *Makine genelinde:* `~/.claude/settings.json`.

**Adım 3 — `env` bloğunu girin** (resmi Z.ai yapılandırması):

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "DEIN_ZAI_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "API_TIMEOUT_MS": "3000000"
  }
}
```

**Adım 4 — Claude Code'u tamamen yeniden başlatın.** Ortam değişkenleri yalnızca
*süreç başlangıcında bir kez* okunur. Yeni bir sekme açmak yeterli değildir — süreci
tamamen sonlandırıp `claude`'u sıfırdan başlatın.

**Adım 5 — Doğrulama.**
- `echo $ANTHROPIC_BASE_URL` → `https://api.z.ai/api/anthropic` çıktısını vermeli.
- CLI'da `/model` kontrol edin → `glm-5.2` / `GLM-5.2` göstermeli, Claude'a geri
  düşmemeli (fallback yok).
- Kimlik testi: „What model are you?" → GLM-5.2 kendini doğru şekilde tanımlar. „Claude"
  diyorsa yönlendirme hatalıdır.

## 1.4 Alanların anlamı

| Alan | İşlevi |
|---|---|
| `ANTHROPIC_AUTH_TOKEN` | Gateway için Bearer token. **Z.ai'de kesinlikle burada olmalı**, `ANTHROPIC_API_KEY` içinde değil. |
| `ANTHROPIC_BASE_URL` | Tüm trafiği yabancı uç noktaya yönlendirir. |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | *haiku* katmanı → ekonomik `glm-4.7`. |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | *sonnet* katmanı → `glm-5.2[1m]` (1 milyonluk bağlam). |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | *opus* katmanı → `glm-5.2[1m]`. |
| `API_TIMEOUT_MS` | Yükseltildi, çünkü GLM daha yavaş yanıt verir ve aksi halde agent döngüleri zaman aşımına uğrar. |

## 1.5 Sık yapılan hatalar (ders için)

- **Yanlış anahtar değişkeni:** Z.ai `ANTHROPIC_AUTH_TOKEN` bekler, `ANTHROPIC_API_KEY`
  değil. En sık görülen yeni başlayan hatası.
- **URL'de yanlış yol:** Anthropic uyumlu yol `/api/anthropic`'tir — genel OpenAI yolu
  değil.
- **Sürecin yeniden başlatılmaması:** Değişiklik ancak tam bir yeniden başlatmadan sonra
  etkinleşir.
- **Rakip oturum:** Aktif bir Claude Max oturumu veya shell'deki bir `ANTHROPIC_API_KEY`
  önceliğe sahip olabilir. Hangi rotanın aktif olduğunu `/status` ile kontrol edin.
- **Git'e sızan anahtar:** `.claude/settings.local.json` dosyasını mutlaka `.gitignore`
  içinde bırakın.

## 1.6 İpucu: temiz geçiş

GLM ile normal Claude arasında geçiş yapmak isteyenler, global bir yönlendirme yerine
ayrı bir shell fonksiyonu oluştursa daha iyi olur — böylece hangi sağlayıcının hangi
terminalde aktif (ve faturalandırılıyor) olduğu her zaman nettir:

```bash
# ~/.zshrc veya ~/.bashrc içinde
claude-zai() {
  ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" \
  ANTHROPIC_AUTH_TOKEN="$Z_AI_API_KEY" \
  claude "$@"
}
```
Ardından GLM için `claude-zai`, Anthropic için normal `claude`.

## 1.7 Tartışma soruları (Bölüm 1)

1. Yönlendirme Z.ai'de neden *proxy olmadan* çalışırken, diğer birçok sağlayıcıda neden
   yalnızca OpenRouter gibi bir gateway üzerinden çalışır?
2. `ANTHROPIC_AUTH_TOKEN` ile `ANTHROPIC_API_KEY` arasındaki fark nedir?
3. Kod başka bir hukuk alanındaki bir uç noktaya gittiğinde hangi veri gizliliği sorusu
   ortaya çıkar?
4. *haiku* neden bilinçli olarak *opus*'tan daha ekonomik bir modele eşlenir?

---
---

# BÖLÜM 2 — Codex'i ikinci bir agent olarak entegre etmek (`openai/codex-plugin-cc`)

**Depo:** `openai/codex-plugin-cc` · Lisans Apache-2.0 · Dil JavaScript

## 2.1 Konu nedir?

Claude Code, Anthropic'in agentic kodlama aracıdır. Codex ise OpenAI'nin karşılığıdır.
Her ikisi de kendi CLI'ı, kendi oturumu ve kendi modelleri olan bağımsız agent'lardır.

`codex-plugin-cc` eklentisi ikisini birbirine bağlar: **Codex'i Claude Code içinden**
çağırmayı mümkün kılar — kendi kodunuzu ikinci, bağımsız bir örneğe incelettirmek veya
tüm görevleri Codex'e devretmek için.

**Didaktik ana fikir — agent'lar arası „Second Opinion":** Kodu insan bir meslektaşa
incelettiğiniz gibi, burada da *başka* bir modelin yargısını alırsınız. İlkinin
varsayımlarını paylaşmayan ikinci bir agent, çoğu zaman asıl yazarın (insan ya da yapay
zekâ) gözden kaçırdığı hataları bulur.

> **Hatırlatma:** Eklenti *ikinci bir yapay zekâ runtime'ı* başlatmaz. Aynı makinede
> yerel olarak kurulu Codex CLI'ı çağırır — aynı kurulum, aynı oturum, aynı repo
> checkout'u. Claude Code yalnızca uzaktan kumandadır.

## 2.2 Mimari

```
   Sen (terminalde)
        │
        ▼
   Claude Code  ──çağırır──►  codex-plugin-cc  ──sarmalar──►  Codex App Server
                                (Slash komutları)                │
                                                                 ▼
                                                        yerel Codex CLI
                                                        (aynı oturum,
                                                         aynı config.toml)
```

Sonuçları:
- **Tek oturum yeterli:** Codex'te zaten oturum açmış olan hemen başlayabilir.
- **Paylaşılan yapılandırma:** Eklenti, Codex'in doğrudan kullandığı `config.toml`
  dosyasının aynısını okur.
- **Kullanım Codex kotasına yazılır**, Claude'unkine değil.

## 2.3 Ön koşullar

| Ön koşul | Ayrıntılar |
|---|---|
| Codex erişimi | ChatGPT aboneliği (Free dahil) **veya** OpenAI API anahtarı |
| Node.js | Sürüm 18.18 veya daha yeni |
| Claude Code | eklenti/Marketplace desteğiyle |

## 2.4 Kurulum — adım adım

**Adım 1 — Marketplace ekleyin**
```
/plugin marketplace add openai/codex-plugin-cc
```

**Adım 2 — Eklentiyi kurun**
```
/plugin install codex@openai-codex
```

**Adım 3 — Eklentileri yeniden yükleyin**
```
/reload-plugins
```

**Adım 4 — Kurulum kontrolü**
```
/codex:setup
```
Codex'in kurulu ve oturum açılmış olup olmadığını kontrol eder. Codex yoksa ve npm
mevcutsa, kurulum Codex'i yüklemeyi önerir.

**Manuel Codex kurulumu (isteğe bağlı):**
```
npm install -g @openai/codex
```

**Oturum açma (gerekirse):**
```
!codex login
```
> Baştaki `!` bir shell komutunu doğrudan Claude Code içinden çalıştırır.

**Başarı kontrolü:** Sonrasında slash komutları görünür ve `codex:codex-rescue`
alt-agent'ı `/agents` altında belirir.

## 2.5 Komut referansı — yedi komut (Handout)

| Komut | Amaç | Kodu değiştirir mi? | Yönlendirilebilir mi? |
|---|---|---|---|
| `/codex:review` | Mevcut çalışmanın normal, salt okunur incelemesi | Hayır | Hayır |
| `/codex:adversarial-review` | Tasarımın ve varsayımların eleştirel incelemesi | Hayır | Evet (odak metni) |
| `/codex:rescue` | Görevi Codex'e devretme (hata, düzeltme, devam) | Evet | Evet |
| `/codex:transfer` | Claude oturumunu Codex thread'i olarak sürdürme | — | — |
| `/codex:status` | Çalışan ve son Codex işlerini gösterme | Hayır | — |
| `/codex:result` | Tamamlanmış bir işin nihai sonucunu alma | Hayır | — |
| `/codex:cancel` | Aktif bir arka plan işini iptal etme | Hayır | — |

### `/codex:review` — ikinci görüş
Mevcut, commit edilmemiş değişikliklerin incelemesi. `--base <ref>` ile branch
karşılaştırması.
```
/codex:review
/codex:review --base main
/codex:review --background
```
*Öğretim noktası:* Çok dosyalı incelemeler zaman alır → arka planda çalıştırın ve
`/codex:status` / `/codex:result` ile toplayın.

### `/codex:adversarial-review` — Şeytanın avukatı
Seçilen uygulamayı sorgulayan **yönlendirilebilir** bir inceleme: varsayımlar,
trade-off'lar, hata modları, alternatifler. Bayrakların ardından serbest odak metni gelir.
```
/codex:adversarial-review --base main challenge whether this was the right caching and retry design
/codex:adversarial-review --background look for race conditions and question the chosen approach
```
*Didaktik karşıtlık:* `review` = „Kod doğru mu?" · `adversarial-review` =
„Bu genel olarak doğru yol muydu?"

### `/codex:rescue` — işi devretme
Bir görevi `codex:codex-rescue` alt-agent'ı üzerinden devreder. Bayraklar: `--background`,
`--wait`, `--resume`, `--fresh`, `--model`, `--effort`.
```
/codex:rescue investigate why the tests started failing
/codex:rescue --model gpt-5.4-mini --effort medium investigate the flaky integration test
/codex:rescue --resume apply the top fix from the last run
```
Doğal dilde de devredilebilir:
```
Ask Codex to redesign the database connection to be more resilient.
```
*Notlar:* `--model`/`--effort` olmadan Codex varsayılanları seçer. `spark`,
`gpt-5.3-codex-spark`'a eşlenir. Takip istekleri, repodaki son görevi sürdürür.

### `/codex:transfer` — bağlamı taşımak
Mevcut Claude oturumundan kalıcı bir Codex thread'i oluşturur ve
`codex resume <session-id>` çıktısını verir. Başlanmış bir debug konuşmasını aynı
bağlamla Codex'te sürdürmek için kullanışlıdır. Kaynak `~/.claude/projects` altında
bulunmalıdır.

### İş yönetimi: `status`, `result`, `cancel`
```
/codex:status              # iş hâlâ çalışıyor mu?
/codex:result              # nihai sonucu al (Codex oturum ID'si dahil)
/codex:cancel task-abc123  # belirli bir işi iptal et
```

## 2.6 Tipik akışlar

**Teslimattan önce inceleme**
```
/codex:review
```
**Bir sorunu Codex'e devretmek**
```
/codex:rescue investigate why the build is failing in CI
```
**Uzun süreli bir işi başlatıp sonra almak**
```
/codex:adversarial-review --background
/codex:rescue --background investigate the flaky test
/codex:status
/codex:result
```

## 2.7 Review Gate — ileri düzey ve dikkatle

```
/codex:setup --enable-review-gate
/codex:setup --disable-review-gate
```
Gate etkinse, eklenti bir `Stop` hook'u üzerinden Claude'un yanıtına kancalanır ve
Codex'e hedefli bir inceleme yaptırır. Codex sorun bulursa, Claude bunları giderene kadar
durma işlemi **engellenir**.

> **Uyarı:** Gate, uzun süreli bir Claude ↔ Codex döngüsü oluşturabilir ve kullanım
> limitini hızla tüketebilir. Yalnızca oturumu etkin biçimde gözlemlerken etkinleştirin.

**Agent döngülerini ve maliyet kontrolünü** ele almak için iyi bir fırsat.

## 2.8 Yapılandırma

Reasoning effort'u ve varsayılan modeli Codex'in `config.toml` dosyası üzerinden
yönetirsiniz:
```toml
model = "gpt-5.4-mini"
model_reasoning_effort = "high"
```
Yükleme sırası: kullanıcı düzeyi `~/.codex/config.toml` → proje düzeyi
`.codex/config.toml` (yalnızca proje *trusted* ise). Alternatif bir uç nokta
`openai_base_url` üzerinden ayarlanabilir.

## 2.9 Tartışma soruları (Bölüm 2)

1. İncelemede neden *başka* bir model, kodu yazan modelden çoğu zaman daha iyi sonuçlar
   verir?
2. `adversarial-review`, `review`'dan ne zaman daha mantıklıdır? İki durum belirtin.
3. Eklentinin *yerel* Codex CLI'ını ve onun oturumunu kullanması, veri gizliliği ve
   maliyetler açısından ne anlama gelir?
4. `--wait` ile `--background` arasındaki farkı açıklayın.
5. Review Gate hangi tehlikeyi barındırır ve bu nasıl sınırlandırılır?

---
---

# Kapanış uygulama görevi (Bölüm 1 ve 2'yi birleştirir)

**Amaç:** Her iki tekniği de gerçekçi bir akış içinde deneyimlemek.

1. Küçük bir repo klonlayın ve bir branch'e ince bir hata yerleştirin
   (ör. off-by-one veya race condition).
2. **Bölüm 1:** Claude Code'u `.claude/settings.local.json` üzerinden GLM-5.2'ye
   yönlendirin ve `/model` ile bir kimlik testi kullanarak doğrulayın.
3. Hatayı GLM'e yönlendirilmiş Claude Code ile incelettirin.
4. **Bölüm 2:** Codex eklentisini kurun (`/codex:setup`) ve race condition'a odaklanarak
   `/codex:adversarial-review --background` başlatın.
5. Sonuçları toplayın (`/codex:status`, `/codex:result`) ve GLM bulgusuyla karşılaştırın.
6. **Değerlendirme:** GLM analizi ile Codex incelemesi içerik olarak nerede birbirinden
   ayrıldı? Bu, bağımsız ikinci görüşlerin değeri hakkında ne söylüyor?

---

## Claude AI Design'da yeniden kullanım için notlar

- Bu belge bilinçli olarak modülerdir: başlık düzeyleri (`#`, `##`, `###`) ve tablolar
  doğrudan slaytlara, bir dashboard'a veya bir handout'a aktarılabilir.
- 2.5'teki komut tabloları ve 1.4'teki alan tablosu bağımsız kopya kağıdı kartları olarak
  uygundur.
- Tartışma soruları ve uygulama görevleri ayrı çalışma yaprakları olarak
  ayrıştırılabilir.

*Kaynaklar: Claude Code entegrasyonuna dair resmi Z.ai dokümantasyonu ve
`openai/codex-plugin-cc` deposunun README dosyası. Komutlar, bayraklar ve model adları
yeni sürümlerle değişebilir — güncel referans için ilgili orijinal kaynakları kontrol
edin.*