İçeriğe geç
OpenCode
app.header.homeapp.header.docs

Yapılandırma

opencode JSON yapılandırması kullanır.

opencode’u JSON yapılandırma dosyası kullanarak yapılandırabilirsiniz.

Format

opencode hem JSON hem de JSONC (JSON Yorumlarla birlikte) formatlarını destekler.

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  // Theme configuration
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
}

Konumlar

Yapılandırmanızı birkaç farklı konuma yerleştirebilirsiniz ve bunların farklı öncelik sırası.

Yapılandırma dosyaları değiştirilmez, birleştirilir. Aşağıdaki yapılandırma konumlarındaki ayarlar birleştirilir. Daha sonraki yapılandırmalar, yalnızca çakışan anahtarlar için önceki yapılandırmaları geçersiz kılar. Tüm yapılandırmalardaki çakışmayan ayarlar korunur.

Örneğin, genel ayarınız theme: "opencode" ve autoupdate: true’yi ayarlıyorsa ve proje ayarlarınız model: "anthropic/claude-sonnet-4-5"’yi ayarlıyorsa, son tork ayarının tümünü dikkate alır.

Precedence order

Yapılandırma kaynakları bu sırayla yüklenir (sonraki kaynaklar öncekileri geçersiz kılar):

  1. Uzaktan yapılandırma (.well-known/opencode’dan) - kurumsal varsayılanlar
  2. Global config (~/.config/opencode/opencode.json) - user preferences
  3. Custom config (OPENCODE_CONFIG env var) - custom overrides
  4. Project config (opencode.json in project) - project-specific settings
  5. .opencode dizinleri - aracılar, komutlar, eklentiler
  6. Inline config (OPENCODE_CONFIG_CONTENT env var) - runtime overrides

Bu, proje yapılandırmalarının genel varsayılanları geçersiz kılabileceği ve genel yapılandırmaların uzak organizasyonel varsayılanları geçersiz kılabileceği anlamına gelir.

Uzak

Kuruluşlar, .well-known/opencode uç noktası aracılığıyla varsayılan yapılandırmayı sağlayabilir. Bu, onu destekleyen bir sağlayıcıyla kimlik doğrulaması yaptığınızda otomatik olarak alınır.

Remote config ilk olarak yüklenir ve temel katman görevi görür. Diğer tüm yapılandırma kaynakları (genel, proje) bu varsayılanları geçersiz kılabilir.

Örneğin, kuruluşunuz varsayılan olarak devre dışı bırakılan MCP sunucuları sağlıyorsa:

Remote config from .well-known/opencode
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

Yerel yapılandırmanızda belirli sunucuları etkinleştirebilirsiniz:

opencode.json
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Global

Global opencode yapılandırmanızı ~/.config/opencode/opencode.json içine yerleştirin. Temalar, sağlayıcılar veya tuş atamaları gibi kullanıcı çapındaki tercihler için genel yapılandırmayı kullanın.

Global config overrides remote organizational defaults.

Proje başına

Proje kökünüze opencode.json ekleyin. Proje yapılandırması, standart yapılandırma dosyaları arasında en yüksek önceliğe sahiptir; hem genel hem de uzak yapılandırmaları geçersiz kılar.

opencode başlatıldığında geçerli dizinde bir yapılandırma dosyası arar veya en yakın Git dizinine gider.

Bunun Git’te kontrol edilmesi de güvenlidir ve global olanla aynı şemayı kullanır.

Özel yol

OPENCODE_CONFIG ortam değişkenini kullanarak özel bir yapılandırma dosyası yolu belirtin.

Terminal window
export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

Özel yapılandırma genel ve proje yapılandırmaları arasında öncelik sırasına göre yüklenir.

Özel dizin

OPENCODE_CONFIG_DIR kullanarak özel bir yapılandırma dizini belirtin ortam değişkeni. Bu dizin aracılar, komutlar için aranacaktır. modlar ve eklentiler tıpkı standart .opencode dizini gibi olmalıdır ve aynı yapıyı takip edin.

Terminal window
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

Özel dizin, genel yapılandırma ve .opencode dizinlerinden sonra yüklenir, böylece bunların ayarlarını geçersiz kılabilir.

Schema

Yapılandırma dosyası opencode.ai/config.json’da tanımlanan bir şemaya sahiptir.

Editörünüz şemaya göre doğrulama ve otomatik tamamlama yapabilmelidir.

TUI

TUI’ye özgü ayarları tui seçeneği aracılığıyla yapılandırabilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

Mevcut seçenekler:

  • scroll_acceleration.enabled - MacOS tarzı kaydırma hızlandırmayı etkinleştirin. scroll_speed’ye göre önceliklidir.
  • scroll_speed - Özel kaydırma hızı çarpanı (varsayılan: 3, minimum: 1). scroll_acceleration.enabled true ise dikkate alınmaz.
  • diff_style - Fark oluşturmayı kontrol edin. "auto" terminal genişliğine uyum sağlar, "stacked" her zaman tek sütunu gösterir.

TUI kullanımı hakkında daha fazla bilgi.

Sunucu

opencode serve ve opencode web komutları için sunucu ayarlarını server seçeneği aracılığıyla yapılandırabilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

Mevcut seçenekler:

  • port - Dinlenecek port.
  • hostname - Dinlenecek ana bilgisayar adı. mdns etkinleştirildiğinde ve hiçbir ana bilgisayar adı ayarlanmadığında, varsayılan değer 0.0.0.0 olur.
  • mdns - mDNS hizmet bulmayı etkinleştirin. Bu, ağdaki diğer cihazların opencode sunucunuzu keşfetmesine olanak tanır.
  • mdnsDomain - mDNS hizmeti için özel alan adı. Varsayılan olarak opencode.local şeklindedir. Aynı ağda birden fazla örneği çalıştırmak için kullanışlıdır.
  • cors - Tarayıcı tabanlı bir istemciden HTTP sunucusunu kullanırken CORS’ye izin verecek ek kaynaklar. Değerler tam kaynaklar olmalıdır (şema + ana bilgisayar + isteğe bağlı bağlantı noktası), örneğin https://app.example.com.

Sunucu hakkında daha fazla bilgi.

Araçlar

Bir LLM’nin kullanabileceği araçları tools seçeneği aracılığıyla yönetebilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Araçlar hakkında daha fazla bilgi.

Modeller

opencode yapılandırmanızda kullanmak istediğiniz sağlayıcıları ve modelleri provider, model ve small_model seçenekleri aracılığıyla yapılandırabilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

small_model seçeneği, başlık oluşturma gibi hafif görevler için ayrı bir model yapılandırır. Varsayılan olarak opencode, sağlayıcınızda mevcutsa daha ucuz bir model kullanmaya çalışır, aksi takdirde ana modelinize geri döner.

Sağlayıcı seçenekleri timeout ve setCacheKey içerebilir:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}
  • timeout - Milisaniye cinsinden istek zaman aşımı (varsayılan: 300000). Devre dışı bırakmak için false olarak ayarlayın.
  • setCacheKey - Belirlenen sağlayıcı için her zaman bir önbellek anahtarının ayarlandığından emin olun.

Ayrıca local models ayarlayabilirsiniz. Daha fazla bilgi.

Sağlayıcıya Özel Seçenekler

Bazı sağlayıcılar genel timeout ve apiKey ayarlarının ötesinde ek yapılandırma seçeneklerini destekler.

Amazon Ana Kayası

Amazon Bedrock, AWS’a özgü yapılandırmayı destekler:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}
  • region - Bedrock için AWS bölgesi (varsayılanı AWS_REGION env var veya us-east-1’dir)
  • profile - ~/.aws/credentials’den AWS adlı profil (varsayılanı AWS_PROFILE env var’dır)
  • endpoint - VPC uç noktaları için özel uç nokta URL. Bu, AWS’e özgü terminolojiyi kullanan genel baseURL seçeneğinin takma adıdır. Her ikisi de belirtilirse endpoint öncelikli olur.

Amazon Bedrock yapılandırması hakkında daha fazla bilgi.

Temalar

opencode yapılandırmanızda kullanmak istediğiniz temayı theme seçeneği aracılığıyla yapılandırabilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "theme": ""
}

Daha fazla bilgi.

Temsilciler

agent seçeneği aracılığıyla özel görevlere yönelik özel aracıları yapılandırabilirsiniz.

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

Agent’ları ~/.config/opencode/agents/ veya .opencode/agents/ içindeki Markdown dosyalarıyla da tanımlayabilirsiniz. Daha fazla bilgi.

Varsayılan temsilci

default_agent seçeneğini kullanarak varsayılan aracıyı ayarlayabilirsiniz. Bu, hiçbiri açıkça belirtilmediğinde hangi aracının kullanılacağını belirler.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

Varsayılan aracı, birincil aracı olmalıdır (alt aracı değil). Bu, "build" veya "plan" gibi yerleşik bir aracı ya da tanımladığınız bir custom agent olabilir. Belirtilen aracı mevcut değilse veya bir alt aracı ise, opencode bir uyarıyla birlikte "build"’ye geri döner.

Bu ayar tüm arayüzler için geçerlidir: TUI, CLI (opencode run), masaüstü uygulaması ve GitHub Action.

Paylaşma

share özelliği share seçeneğini aracılığıyla yapılandırabilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

Bu şunları gerektirir:

  • "manual" - Komutlar aracılığıyla manuel paylaşıma izin ver (varsayılan)
  • "auto" - Yeni konuşmaları otomatik olarak paylaş
  • "disabled" - Paylaşımı tamamen devre dışı bırak

Varsayılan olarak paylaşım, /share yoğunluğu kullanılarak konuşmaları açıkça paylaşmanız gereken manuel moda ayarlanmıştır.

Komutlar

command seçeneği aracılığıyla tekrarlanan görevler için özel komutlar yapılandırabilirsiniz.

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component",
    },
  },
}

Komutları ~/.config/opencode/commands/ veya .opencode/commands/ içindeki Markdown dosyalarıyla da tanımlayabilirsiniz. Daha fazla bilgi.

Tuş bağlantıları

Tuş atamalarınızı keybinds seçeneği aracılığıyla özelleştirebilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {}
}

Daha fazla bilgi.

Autoupdate

opencode başlatıldığında yeni güncellemeleri otomatik olarak indirecektir. Bunu autoupdate seçeneğiyle devre dışı bırakabilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false
}

Güncelleme istemiyor ancak yeni bir sürüm mevcut olduğunda bilgilendirilmek istiyorsanız autoupdate öğesini "notify" olarak ayarlayın. Bunun yalnızca Homebrew gibi bir paket yöneticisi kullanılarak yüklenmemişse işe yaradığına dikkat edin.

Biçimlendiriciler

Kod formatlayıcılarını formatter seçeneği aracılığıyla yapılandırabilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Formatter’lar hakkında daha fazla bilgi.

Permissions

Varsayılan olarak, opencode açık bir onay gerektirmeden tüm işlemlere izin verir. permission seçeneğini kullanarak bunu değiştirebilirsiniz.

Örneğin, edit ve bash araçlarının kullanıcı onayı gerektirdiğinden emin olmak için:

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

İzinler hakkında daha fazla bilgi.

Sıkıştırma

Bağlam sıkıştırma davranışını compaction seçeneği aracılığıyla kontrol edebilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}
  • auto - Bağlam dolduğunda oturumu otomatik olarak sıkıştırır (varsayılan: true).
  • prune - Belirteçleri kaydetmek için eski araç çıktılarını kaldırın (varsayılan: true).

Watcher

Dosya izleyicinin yok sayma kalıplarını watcher seçeneği aracılığıyla yapılandırabilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Desenler glob sözdizimini takip eder. Gürültülü dizinleri dosya izlemenin dışında bırakmak için bunu kullanın.

MCP sunucuları

Kullanmak istediğiniz MCP sunucularını mcp seçeneği aracılığıyla yapılandırabilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

Daha fazla bilgi.

Plugins

Plugins opencode’u özel araçlar, kancalar ve entegrasyonlarla genişletin.

Eklenti dosyalarını .opencode/plugins/ veya ~/.config/opencode/plugins/ içine yerleştirin. Ayrıca eklentileri plugin seçeneği aracılığıyla npm’den de yükleyebilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Daha fazla bilgi.

Talimatlar

Kullandığınız modele ilişkin talimatları instructions seçeneği aracılığıyla yapılandırabilirsiniz.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

Bu, talimat dosyalarına giden bir dizi yolu ve glob desenini alır. Daha fazla bilgi edin kurallar hakkında burada.

Disabled providers

disabled_providers seçeneği aracılığıyla otomatik olarak yüklenen sağlayıcıları devre dışı bırakabilirsiniz. Bu, belirli sağlayıcıların kimlik bilgileri mevcut olsa bile yüklenmesini engellemek istediğinizde kullanışlıdır.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

disabled_providers seçeneği bir dizi sağlayıcı kimliğini kabul eder. Bir sağlayıcı devre dışı bırakıldığında:

  • It won’t be loaded even if environment variables are set.
  • API anahtarları /connect komutu aracılığıyla yapılandırılsa bile yüklenmeyecektir.
  • Sağlayıcının modelleri, model seçim listesinde görünmez.

Etkin sağlayıcılar

enabled_providers seçeneğini kullanarak sağlayıcıların izin verilenler listesini belirtebilirsiniz. Ayarlandığında yalnızca belirtilen sağlayıcılar etkinleştirilecek ve diğerleri göz ardı edilecektir.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

Bu, opencode’u tek tek devre dışı bırakmak yerine yalnızca belirli sağlayıcıları kullanacak şekilde kısıtlamak istediğinizde kullanışlıdır.

Bir sağlayıcı hem enabled_providers hem de disabled_providers’de görünüyorsa, geriye dönük uyumluluk için disabled_providers önceliğe sahiptir.

Experimental

experimental anahtarı aktif olarak geliştirilmekte olan seçenekleri içerir.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {}
}

Değişkenler

Ortam değişkenlerine ve dosya içeriklerine referans vermek için yapılandırma dosyalarınızda değişken değiştirmeyi kullanabilirsiniz.

Env vars

Ortam değişkenlerini değiştirmek için {env:VARIABLE_NAME} kullanın:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Ortam değişkeni ayarlanmamışsa boş bir dizeyle değiştirilecektir.

Dosyalar

Bir dosyanın biçimini değiştirmek için {file:path/to/file} kullanın:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Dosya yolları şunlar olabilir:

  • Yapılandırma dosyası dizinine göre
  • Veya / veya ~ ile başlayan mutlak yollar

Bunlar aşağıdakiler için faydalıdır:

  • API anahtarları gibi hassas verileri ayrı dosyalarda tutmak.
  • Yapılandırmanızı karmaşıklaştırmadan büyük talimat dosyaları içerir.
  • Birden fazla yapılandırma dosyasında ortak yapılandırma parçacıklarının paylaşılması.