opencode nasıl kullanılır? Adım adım rehber

opencode’u kullanmak için tek bir komutla kurarsın, bir proje klasöründe opencode çalıştırırsın, /connect ile bir model sağlayıcısı bağlarsın, /models ile bir model seçersin ve ne istediğini anlatırsın. Varsayılan Build ajanı kodunu okur, dosyaları düzenler ve komut çalıştırır. Hiçbir koda dokunmadan bir değişikliği düşünüp tartmak istediğinde Tab’a basıp Plan ajanına geçersin.

Temel döngü bu. Bu rehber gerisini anlatıyor: sağlayıcılar ve yerel modeller, her gün kullanacağın TUI komutları, iki yerleşik ajan, opencode.json, AGENTS.md, MCP sunucuları, özel komutlar ve opencode’u diğer ajanların yanında çalıştırmak. Buradaki her şey Ekim 2026 itibarıyla opencode’un resmi belgelerine dayanıyor.

opencode nedir?

opencode, terminal için tek bir yapay zeka şirketine bağlı olmayan bir kodlama ajanı. Claude Code Anthropic modellerini, Codex de OpenAI modellerini kullanır. opencode ise AI SDK ve Models.dev üzerine kurulu, bu yüzden düzinelerce sağlayıcıyla ve yerel modellerle çalışır. Planlama için bir model, uygulama için başka bir model kullanabilir; yeni bir araç öğrenmeden sağlayıcı değiştirebilirsin.

Sürümlerle ilgili bir not: opencode 2 kendi belgeleriyle birlikte yayımlandı. İki sürüm de opencode adında bir komut kurar ve ikisini bu adla bir arada tutamazsın. Bu rehber, npm paketi opencode-ai’ın kurduğu sürüm 1’i izliyor. Anlatılanların çoğu sürüm 2 için de geçerli. Homebrew’un çekirdek formülüyle ya da Arch’ın ana deposundan kurduysan büyük ihtimalle sürüm 2’ye sahipsin; o zaman ona karşılık gelen belgelere bak.

1. Adım: opencode’u kur

bun, pnpm ve yarn global add opencode-ai de çalışır. Windows’ta belgeler, en iyi deneyim için opencode’u WSL içinde çalıştırmayı öneriyor. WezTerm, Alacritty, Ghostty ya da Kitty gibi modern bir terminal TUI’yi en iyi şekilde gösterir.

opencode kendini asla arka planda güncellemez. Oturum içinde /update daha yeni bir sürüm 1 yayınını kurar; zaten en son sürüm 1’deysen sürüm 2’ye yükseltmeyi önerir. Kabukta opencode upgrade aynı işi yapar.

2. Adım: bir sağlayıcı bağla ve model seç

Bir projeye geç ve opencode’u başlat:

cd my-project
opencode

Ardından /connect çalıştır ve bir sağlayıcı seç. Aynısını kabuktan opencode auth login ile de yapabilirsin. Kimlik bilgileri ~/.local/share/opencode/auth.json dosyasına kaydedilir, opencode auth list de neyin bağlı olduğunu gösterir. opencode API anahtarlarını ortam değişkenlerinden ve projedeki bir .env dosyasından da alır.

Yaygın seçeneklerden bazıları:

• OpenCode Zen: opencode ekibinin ajanla test ettiği, özenle seçilmiş bir model listesi. opencode.ai/auth adresinde giriş yap, ödeme bilgisi ekle, anahtarı kopyala ve /connect içine yapıştır. Belgeler bunu yeni kullanıcılara öneriyor.
• Anthropic: Claude Console’dan aldığın bir API anahtarını yapıştır. Claude Pro ya da Max aboneliğiyle giriş seçeneği sunulmuyor. Anthropic, üçüncü taraf araçların bu planları bu şekilde kullanmasına izin vermiyor; opencode da bunu yapan eklentileri dağıtmayı bıraktı.
• OpenAI: tarayıcı üzerinden giriş yapmak için “ChatGPT Plus/Pro” seçeneğini seç ya da bir API anahtarını elle gir.
• GitHub Copilot: github.com/login/device adresinde bir cihaz koduyla giriş yap. Bazı modeller daha üst bir Copilot planı ister.
• Yerel modeller: OpenAI uyumlu bir sunucuyu gösteren özel bir sağlayıcı ekle (aşağıya bak).

Bir sağlayıcı bağlandıktan sonra /models (ya da ctrl+x m) model seçiciyi açar. Kabukta opencode models sağlayıcılarının sunduğu her modeli, opencode models anthropic ise tek bir sağlayıcının modellerini listeler. Modeller sağlayıcı/model biçiminde yazılır, örneğin anthropic/claude-sonnet-5-5. Birçok modelin daha yüksek akıl yürütme eforu gibi varyantları vardır; ctrl+t bunlar arasında dolaşır.

Ollama ile yerel modeller

Yerel bir model, opencode.json içinde özel bir sağlayıcıdır:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

Yerel bir modelle araç çağrıları başarısız oluyorsa belgeler, Ollama’nın num_ctx değerini 16k–32k civarına çıkarmayı öneriyor. Genellikle sebep küçük bir bağlam penceresidir. Baştan yerel bir model seçmek için yerel model ile kodlama ajanı yazısına bak.

3. Adım: TUI temelleri

opencode ekranı, projenle yaptığın bir sohbet. Sürekli kullanacağın birkaç şey:

• @ dosyalarda bulanık arama yapar ve onları mesajına ekler.
• Satır başındaki ! bir kabuk komutu çalıştırır, örneğin !npm test, ve çıktıyı konuşmaya koyar.
• ctrl+x lider tuştur. Kısayolların çoğu ctrl+x ve ardından bir harftir.
• Görselleri eklemek için terminale sürükleyip bırakabilirsin.

/undo dosya değişikliklerini geri almak için Git’e dayanır, bu yüzden proje bir Git deposu olmalı. Kabuktan kaldığın yerden devam etmek için opencode -c son oturumu, opencode -s <id> ise belirli bir oturumu açar. Betikler ve CI için opencode run "your prompt" TUI olmadan tek bir görev çalıştırır.

4. Adım: Build ve Plan ajanları

opencode’un iki birincil ajanı var ve Tab aralarında geçiş yapar:

• Build varsayılandır. Tüm araçları açıktır: dosya düzenler, kabuk komutları çalıştırır ve MCP sunucularını çağırır.
• Plan kısıtlıdır. Kodunu düzenleyemez; yazabileceği tek dosyalar .opencode/plans/ içindeki Markdown planlardır. Sana açıklayıcı sorular sorabilir.

Basit olmayan her iş için iyi bir alışkanlık: Plan’da başla, bir yaklaşım üzerinde anlaş, sonra Tab’a bas ve Build’e uygulamasını söyle. Ayrıca @ ile çağırdığın iki alt ajan var: çok adımlı araştırma ve değişiklikler için @general, kod tabanında hızlı, salt okuma aramalar için @explore. Her biri bir alt oturumda çalışır. ctrl+x ve ardından aşağı ok bu oturuma girer, yukarı ok ana oturuma döner. Alt ajan sözlük maddesi bunun neden bağlam kazandırdığını açıklıyor.

Bir tuzak: Plan, bash aracını kendi başına sınırlamaz. Kabuk komutları izin ayarlarına uyar. Ayrıca ayarlarındaki üst düzey bir "edit": "allow" Plan için de geçerli olur, çünkü sonra eşleşen kurallar kazanır. Plan’ın kilitli kalmasını istiyorsan izinlerini doğrudan ayarla:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": "ask"
      }
    }
  }
}

Kendi ajanlarını opencode agent create ile ya da .opencode/agents/ (proje başına) veya ~/.config/opencode/agents/ (genel) içinde Markdown dosyaları olarak oluşturabilirsin. Dosya adı ajanın adı olur. Frontmatter; description, mode (primary ya da subagent), model ve permission değerlerini belirler.

5. Adım: ayar dosyası

opencode opencode.json (ya da yorumlara izin veren opencode.jsonc) dosyasını okur. Yaygın iki yeri var:

• Genel: varsayılanların için ~/.config/opencode/opencode.json.
• Proje: proje kökündeki, kodla birlikte commit edilen opencode.json.

Dosyalar birbirinin yerine geçmez, birleştirilir; çakıştıkları yerde proje ayarları kazanır. Pratik bir proje ayarı:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "small_model": "anthropic/claude-haiku-5-5",
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "npm test *": "allow"
    }
  },
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

• model varsayılan modeldir. small_model oturum başlıkları gibi hafif işler için kullanılır.
• permission her araç için allow, ask ya da deny alır; bash için kalıplar kullanılır. Son eşleşen kalıp kazanır, bu yüzden "*" en başa gelsin.
• instructions, AGENTS.md’nin üzerine başka kural dosyaları ekler. Glob kalıpları ve URL’ler de çalışır.

Değerler ortamdan {env:VAR} ile ya da bir dosyadan {file:path} ile gelebilir, yani anahtarların hiçbir zaman ayar dosyasında durması gerekmez. Varsayılan olarak çoğu işleme izin verilir. .env dosyalarını okumak ve proje dışındaki klasörlere dokunmak önce sorar. opencode --auto açıkça reddedilmemiş her şeyi onaylar; bu yüzden onu yalnızca ajanı başında kimse olmadan çalıştırmaktan rahatsız olmayacağın bir yerde kullan.

Tema ve tuş atamaları gibi TUI ayarları ayrı bir tui.json dosyasında durur.

6. Adım: AGENTS.md

AGENTS.md proje kurallarını tutar: nasıl build alınır, test edilir ve lint çalıştırılır, uyulacak kurallar, uzak durulacak klasörler. /init çalıştırırsan opencode projeyi tarar ve senin için bir tane yazar. Oku, kısalt ve commit et.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- API handlers live in src/api/; one file per route.
- Never edit files in src/generated/.

Her proje için geçerli genel kurallar ~/.config/opencode/AGENTS.md dosyasına gider. Claude Code’dan geliyorsan opencode, AGENTS.md olmadığında projedeki CLAUDE.md dosyasına başvurur; ayrıca ~/.claude/CLAUDE.md ve ~/.claude/skills/ içeriğini de okur. Bunu kapatmak için OPENCODE_DISABLE_CLAUDE_CODE=1 ayarla. Dosyaya neyin girmesi gerektiğini CLAUDE.md nasıl yazılır yazısı anlatıyor.

7. Adım: MCP sunucuları

MCP sunucuları opencode’a yeni araçlar verir: bir tarayıcı, bir iş takip aracı, belge araması. mcp anahtarının altına girerler. Yerel bir sunucu opencode’un başlattığı bir komuttur; uzak bir sunucu ise bir URL’dir:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    },
    "my-remote": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_MCP_TOKEN}"
      }
    }
  }
}

opencode mcp add etkileşimli olarak bir sunucu ekler, opencode mcp list ise neyin ayarlı olduğunu ve bağlanıp bağlanmadığını gösterir. OAuth kullanan uzak sunucular otomatik olarak giriş yapar; opencode mcp auth <name> elle giriş yapar. Bir sunucu bağlanmıyorsa opencode mcp debug <name> yardımcı olur.

Her sunucu araçlarını her isteğin bağlamına ekler ve GitHub MCP sunucusu gibi bazı büyük sunucular çok fazla şey ekler. Yalnızca ihtiyaç duyduğun sunucuları aç; birini ayarlı ama kapalı tutmak için "enabled": false kullan.

8. Adım: özel komutlar

Özel komut, aksi halde tekrar tekrar yazacağın bir prompt’tur. .opencode/commands/ (proje başına) ya da ~/.config/opencode/commands/ (genel) içine bir Markdown dosyası koy; dosya adı komutun adı olur:

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

.opencode/commands/test.md olarak kaydedilince bu /test olur. Komutlar argüman alır: $ARGUMENTS komut adından sonraki her şeydir, $1, $2 ve devamı tek tek argümanlardır, !`git diff --staged` bir kabuk komutunun çıktısını ekler, @src/file.ts ise bir dosyayı dahil eder. Komutları opencode.json içinde command anahtarının altında bir template ile de tanımlayabilirsin. Özel bir komut yerleşik bir komutla aynı adı taşıyorsa yerleşik olan kazanır.

Sık yapılan hatalar

• İlk çalıştırmada “No provider”. Henüz hiçbir şey bağlı değil. /connect çalıştır.
• Plan modunda düzenlemeler. Genel bir "edit": "allow" Plan’a da ulaşır. agent.plan.permission değerini açıkça ayarla.
• /undo dosyaları geri almıyor. Klasör bir Git deposu değil.
• İki opencode sürümü çakışıyor. Homebrew çekirdeği sürüm 2’yi, npm ise sürüm 1’i aynı komut adıyla kurar. opencode --version ile kontrol et ve birini tut.
• Yavaş, pahalı oturumlar. Çok fazla MCP sunucusu ya da uzun bir oturum. Sunucuları kapat ve /compact ya da /new kullan.

opencode’u AgentVera bölmelerinde çalıştırmak

Tek bir opencode oturumunu takip etmek kolay. Bir kısmı opencode’da, bir kısmı Claude Code ya da Codex’te olan birkaç ajan aynı anda çalıştığında terminal sekmeleri ayak bağı olmaya başlar. AgentVera bu CLI’ları kendi kurulumların ve girişlerinle, gerçek terminallerde yan yana çalıştıran bir masaüstü uygulaması. opencode desteği şöyle çalışır:

• Senin sağlayıcıların, senin girişin. Sağlayıcılara opencode’un kendi içinden giriş yaparsın (/connect ya da opencode auth login); bağladığın her sağlayıcı, yerel modeller dahil, AgentVera’nın model listesinde sağlayıcıya göre gruplanmış olarak görünür. Model varyantları efor seçenekleri olarak çıkar. opencode kurulu değilse AgentVera onu npm i -g opencode-ai ile kurar.
• Her ajana bir oturum. Her opencode ajanının kendi oturumu olur; bu yüzden bir ajanı çoğaltmak konuşmasını paylaşmak yerine ondan dal açar. /compact her zamanki gibi çalışır.
• opencode.json dosyana dokunulmaz. Ajanın rolü, AgentVera’nın MCP yöneticisinde eklediğin MCP sunucuları ve AgentVera’nın tarayıcısı ek ayar olarak verilir ve seninkiyle birleştirilir.
• Bölmeler ve worktree’ler. opencode’u çalışma alanı ızgarasında Claude Code’un yanında çalıştır; her ajan kendi git worktree kopyasında çalıştığı için birbirlerinin dosyalarına basmazlar.
• İnceleme ve akışlar. opencode ajanları otomatik kod incelemesiyle çalışır; akışlarda (Pro ve Team) bir ajanın yanıtı otomatik olarak diğerine gidebilir. Örneğin ucuz bir model planlar, daha güçlü bir model uygular.

Izgara, worktree’ler, kod incelemesi ve MCP yöneticisi ücretsiz planda. Denemek için AgentVera’yı indir. Ekibin Claude’u CI’da da çalıştırıyorsa o tarafı Claude Code GitHub Actions anlatıyor; OpenAI’ın ajanı için aynı rehber de Codex CLI nasıl kullanılır.

Toparlarsak

opencode’u kullanmak için kur, bir projede opencode çalıştır, /connect ile bir sağlayıcı bağla ve /models ile bir model seç. Düşünmek için Plan’ı, kodu değiştirmek için Build’i kullan ve aralarında Tab ile geç. Varsayılanlarını opencode.json’a, proje kurallarını AGENTS.md’ye, araçlarını mcp altına ve tekrar eden prompt’larını .opencode/commands/ içine koy. Bundan sonra opencode’da iş, çoğunlukla her görev için doğru modeli seçmekten ibaret; istediğin an değiştirmene de izin veriyor.