# opencode nasıl kullanılır? Adım adım rehber Adres: https://agentvera.dev/blog/opencode-nasil-kullanilir/ · Yayın: 2026-10-27 opencode nasıl kullanılır: kurulum, sağlayıcı bağlama, model seçme, Build ile Plan arasında geçiş; opencode.json, AGENTS.md, MCP sunucuları ve komutların ayarı. **Kısaca:** - opencode’u resmi betikle ya da npm ile kur, bir projede opencode çalıştır, /connect ile bir sağlayıcı bağla ve /models ile model seç; yerel modeller dahil her sağlayıcı çalışır. - Tab; düzenleme yapıp komut çalıştıran Build ajanı ile kodunu düzenleyemeyen ve bir değişikliği önce düşünüp tartmak için kullanılan Plan ajanı arasında geçiş yapar. - Ayarlar opencode.json’da (genel ve proje başına), proje kuralları AGENTS.md’de durur; MCP sunucuları mcp anahtarının altına, özel komutlar .opencode/commands/ içine gider. 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ı](/sozluk/kodlama-ajani/ "Kodlama ajanı nedir"). 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 | Platform | Komut | | --- | --- | | macOS, Linux | `curl -fsSL https://opencode.ai/install \| bash` | | Node.js olan her platform | `npm install -g opencode-ai` | | macOS, Linux (Homebrew, sürüm 1) | `brew install anomalyco/tap/opencode` | | Windows | `choco install opencode` ya da `scoop install opencode` | `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: ```bash 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: ```json { "$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ı](/blog/yerel-model-kodlama-ajani/ "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. | Komut | Kısayol | Ne yapar | | --- | --- | --- | | `/connect` | | Bir sağlayıcı ekler | | `/models` | `ctrl+x m` | Model seçer | | `/new` | `ctrl+x n` | Yeni bir oturum başlatır | | `/sessions` | `ctrl+x l` | Önceki bir oturumu açar | | `/compact` | `ctrl+x c` | Bağlamı boşaltmak için oturumu özetler | | `/undo` | `ctrl+x u` | Son mesajı ve dosya değişikliklerini geri alır | | `/redo` | `ctrl+x r` | Geri aldığını yineler | | `/editor` | `ctrl+x e` | Uzun bir prompt’u `$EDITOR` içinde yazdırır | | `/export` | `ctrl+x x` | Konuşmayı Markdown olarak dışa aktarır | | `/init` | | `AGENTS.md` oluşturur ya da günceller | | `/exit` | `ctrl+x q` | Çıkar | `/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 ` 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](/sozluk/alt-ajan/ "Alt ajan nedir") 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: ```json { "$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ı: ```json { "$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. ```markdown # 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](/blog/claude-md-nasil-yazilir/ "CLAUDE.md ve AGENTS.md nasıl yazılır") yazısı anlatıyor. ## 7. Adım: MCP sunucuları [MCP sunucuları](/blog/mcp-sunucusu-nedir/ "MCP sunucusu nedir") 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: ```json { "$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 ` elle giriş yapar. Bir sunucu bağlanmıyorsa `opencode mcp debug ` 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: ```markdown --- 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](/ajanlar/opencode/ "AgentVera’da opencode") şö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](/ozellikler/mcp-yoneticisi/ "MCP yöneticisi") 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ı](/ozellikler/calisma-alani/ "Çalışma alanı") ızgarasında Claude Code’un yanında çalıştır; her ajan kendi [git worktree](/sozluk/git-worktree/ "Git worktree nedir") kopyasında çalıştığı için birbirlerinin dosyalarına basmazlar. - **İnceleme ve akışlar.** opencode ajanları [otomatik kod incelemesiyle](/ozellikler/kod-incelemesi/ "Otomatik kod incelemesi") çalışır; [akışlarda](/ozellikler/akislar/ "Akışlar") (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](/indir/ "AgentVera’yı indir"). Ekibin Claude’u CI’da da çalıştırıyorsa o tarafı [Claude Code GitHub Actions](/blog/claude-code-github-actions/ "Claude Code GitHub Actions") anlatıyor; OpenAI’ın ajanı için aynı rehber de [Codex CLI nasıl kullanılır](/blog/codex-cli-nasil-kullanilir/ "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. ## Sık sorulanlar **opencode ücretsiz mi?** CLI’ı kurmak ücretsiz. Sağlayıcın üzerinden kullandığın modeller için ödersin: token başına faturalanan bir API anahtarı, GitHub Copilot ya da ChatGPT Plus/Pro gibi zaten sahip olduğun bir abonelik veya OpenCode Zen. Ollama üzerinden yerel modellerin kendi donanımın dışında bir maliyeti yok. **opencode hangi modelleri kullanabilir?** Desteklediği her sağlayıcıyı: Anthropic, OpenAI, Google, GitHub Copilot, OpenRouter, OpenCode Zen ve daha pek çoğu; ayrıca Ollama gibi OpenAI uyumlu bir sunucu üzerinden yerel modeller. Bağlı sağlayıcılarının sunduklarını listelemek için opencode models çalıştır. **Build ve Plan ajanları arasındaki fark ne?** Build varsayılan ajandır ve tüm araçlara sahiptir; dosya düzenler ve komut çalıştırır. Plan kodunu düzenleyemez; yalnızca .opencode/plans/ içine Markdown planlar yazabilir. Bir değişikliği düşünüp tartmak için Plan’ı kullan, sonra Tab’a basıp Build’e geç ve uygulat. **opencode CLAUDE.md dosyasını okur mu?** Evet, yedek olarak. Bir projede AGENTS.md yoksa opencode CLAUDE.md dosyasını okur; genel kurallar için de ~/.claude/CLAUDE.md dosyasına başvurur. Claude Code yedeklerini kapatmak için OPENCODE_DISABLE_CLAUDE_CODE=1 ayarla. **opencode ayarlarını ve girişlerini nerede saklar?** Genel ayarlar ~/.config/opencode/opencode.json dosyasında, proje ayarları proje kökündeki opencode.json dosyasında; ikisi birleştirilir. /connect ile girilen sağlayıcı kimlik bilgileri ~/.local/share/opencode/auth.json dosyasında saklanır. --- **AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/