Ortam değişkenleri

Multica, ortam değişkenlerini süreç başlangıcında okur. Birini değiştirdikten sonra, etkilenen API, web veya daemon sürecini yeniden başlatın. Docker Compose'un docker compose restart komutu .env'i yeniden okumaz; değişikliklerin etkili olması için container'ları up -d ile yeniden oluşturun.

Bu sayfa yalnızca dağıtıma yönelik yapılandırmayı listeler; test değişkenleri ve iç çalıştırma değişkenleri burada ele alınmaz. Bu gruplandırılmış bir referanstır — tam dağıtım adımları için bkz. kendi sunucunuzda hızlı başlangıç.

Asgari üretim yapılandırması

DATABASE_URL=postgres://user:password@postgres:5432/multica?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://multica.example.com
MULTICA_APP_URL=https://multica.example.com
MULTICA_PUBLIC_URL=https://api.multica.example.com

Ayrıca bir e-posta hizmeti seçmeniz gerekir, aksi hâlde doğrulama kodları ve davetler yalnızca sunucu günlüğüne yazılır.

API ve veritabanı

Kubernetes'te bir kapanma bekletmesi ayarlarken, terminationGracePeriodSeconds, bekletme süresi artı gerçek kapanmanın ihtiyaç duyduğu süreyi aşmalıdır.

Birincil ve replika bağlantı sınırları birbirinden bağımsızdır; ikisinin toplamını her API süreci için PostgreSQL kümesinin bağlantı tavanına göre bütçeleyin. Replika bağlantıları, yükseltme (promotion) sonrası salt okunur doğrulamayı tazelemek için varsayılan olarak beş dakikada bir geri dönüştürülür. Replika bağlantı hataları sessizce birincile döner ve kısa, pasif bir devre kesici açar; arka planda ek bir veritabanı yoklaması eklenmez. Replika okumalarının uygulama tarafından zorlanan bir gecikme sınırı yoktur, bu yüzden gecikmeyi veritabanı katmanında izleyin ve tutarlılığa duyarlı okumaları birincilde tutun.

Herkese açık URL'ler ve tarayıcı erişimi

Ön uç ve API farklı host'larda çalıştığında ve tarayıcı doğrudan API alan adıyla konuştuğunda, COOKIE_DOMAIN'i ayarlamalısınız — aksi hâlde tarayıcı CSRF çerezini okuyamaz: okumalar sorunsuz çalışırken her yazma isteği 403 CSRF validation failed döner. Her iki host'u da kapsayan en dar üst alan adını kullanın (.example.com yerine .agent.example.com). Bu, giriş oturumu çerezini o alan adı altındaki her host'a yayar, bu yalnızca o host'ların hepsi aynı güvenilen taraf tarafından işletildiğinde kabul edilebilir. Değiştirdikten sonra, her iki host'taki eski çerezleri temizleyin ve yeniden giriş yapın. Kendi sunucunuzda hızlı başlangıç rehberindeki aynı-kaynak tarifini izliyorsanız (tarayıcı yalnızca uygulama alan adını ziyaret eder), boş bırakın. Bir IP adresi kullanmayın — tarayıcılar Domain'i bir IP olan çerezleri yok sayar.

E-posta ve giriş

Resend

SMTP

SMTP_HOST boş olmadığında SMTP, Resend'e göre önceliklidir.

Google OAuth

Kayıt kapsamı

İzin listesi değerlendirme sırasının tamamı için bkz. Giriş ve kayıt.

Ek depolama

S3_BUCKET ayarlanmadığında, Multica yerel diski kullanır.

S3 veya uyumlu depolama

Uç nokta — örneğin dahili bir MinIO — tarayıcıdan erişilebilir olmadığında ATTACHMENT_DOWNLOAD_MODE=proxy kullanın.

Yerel disk

CloudFront

Redis ve hız sınırlama

Bir ters proxy'nin arkasındaki dağıtımlar gerçek proxy aralıklarını listelemelidir. Tüm kaynaklara körü körüne güvenmeyin, aksi hâlde istemciler yönlendirilmiş IP'leri sahteleyebilir.

Kimlik doğrulama hız sınırları REDIS_URL gerektirir; olmadan, başlangıç günlüğü kimlik doğrulama hız sınırlamasının devre dışı olduğunu belirtir. Davet sınırları Redis olmadan yine işlem-yerel bellekte çalışır ve Redis yapılandırıldığında replikalar arasında paylaşılır hâle gelir. Yapılandırılmış Redis geçici olarak erişilemez hâle gelirse, kimlik doğrulama hız sınırlaması işlem-yoktur şekilde açılırken, davet oluşturma korumasız e-posta göndermek yerine yeniden denenebilir bir 503 döner.

Dış entegrasyonlar

GITHUB_APP_ID ve özel anahtar olmadan, PR'lar yine de normal şekilde bağlanır, yansıtılır ve birleştirmede-bitir'i tetikler, ama kartlar CI veya birleştirilebilirlik durumu göstermez ve "GitHub'dan seç" depo girişi devre dışıdır.

Kurulum adımları için bkz. GitHub entegrasyonu, Lark bot, Slack bot ve Telegram bot.

Sunucu tarafı LLM

Bu grup, konuşma başlıkları gibi sunucu tarafı yardım üretimini yapılandırır; agent'ların çalıştırmaları yürütmek için kullandığı yapay zekâ kodlama aracı kimlik bilgileri değildir.

MULTICA_LLM_MAX_RETRIES, yeniden deneme ilkesi için tek kaynaktır. Varsayılan olan 2 için ayarsız bırakın, her çağrıda tam olarak bir istek göndermek için 0 yapın, veya yeniden denemeleri o kadarla sınırlamak için 1–5 ayarlayın. Bu bir kota değil, bir tavandır: yalnızca yeniden denenebilir başarısızlıklar onu tüketir, bir başarı veya çağıranın kendi son tarihi çağrıyı daha erken bitirebilir. Başka herhangi bir değer — negatif, sayısal olmayan veya 5'in üzerinde — sessizce düzeltilmek yerine başlangıcı başarısız kılar. Tavan bir gecikme bütçesidir: geri çekilme 0.5s'de başlar ve 8s tavanına kadar ikiye katlanır, bu yüzden daha büyük bir bütçe çağıranların kendi son tarihlerini aşar ve yeniden denenebilir bir başarısızlığı bir zaman aşımına çevirir. Yeniden denemeler bağlantı hatalarını ve HTTP 408, 409, 429 ve 5xx'i kapsar; diğer tüm 4xx yanıtları olduğu gibi döner. Sunucu, başlangıçta etkin ilkeyi llm retry policy olarak günlükler, satırda hiçbir kimlik bilgisi olmadan.

Bu katmanı iki özellik kullanır ve her biri sohbet içeriğini yapılandırdığınız uç noktaya gönderir:

• Sohbet otomatik başlıklandırma — yeni bir sohbet oturumunun ilk kullanıcı mesajı, olduğu gibi gönderilir. Ekler asla dahil edilmez.
• Takip soruları (bir agent yanıtının altındaki öneri düğmeleri) — konuşmanın kuyruğu: en fazla 6 mesaj, yanıtlanan mesaj 3000 karakterle, her eski mesaj 800 karakterle sınırlı.

Hem API anahtarı hem de taban URL boş olduğunda, bu katman devre dışı kalır ve hiçbir üst akış isteği yapmaz — yukarıdaki iki özellik de hiçbir şey göndermez. İlkeniz bu katmanın sohbet içeriğini dağıtımın dışına göndermesine izin vermediğinde desteklenen yapılandırma budur: sohbet oturumları istemcinin ilk mesajdan türettiği başlığı korur, takip sorusu düğmeleri görünmez ve geri kalan her şey etkilenmez.

Daemon yapılandırması

Aşağıdaki değişkenler, agent'larınızı çalıştıran bilgisayarda okunur, API container'ında değil.

Daemon'ın agent çalıştırmalarına enjekte ettiği iç bağlam için bkz. Çalıştırma runtime ortamı.

Her yapay zekâ kodlama aracı, komut yolunu ve varsayılan modeli geçersiz kılmak için MULTICA_<SAĞLAYICI>_PATH ve MULTICA_<SAĞLAYICI>_MODEL'i kabul eder. QwenPaw ve MiniMax Code'un model değişkeni yoktur çünkü Multica onlara asla bir model göndermez; MiniMax Code'un yol değişkeni MULTICA_MCODE_PATH'tir — bkz. Yapay zekâ kodlama araçları karşılaştırması. DeepSeek Harness, MULTICA_DSH_PATH ve MULTICA_DSH_MODEL'i destekler (dsh kataloğundan bir model kimliği, örn. deepseek-official/deepseek-chat). Dim, MULTICA_DIM_PATH ve MULTICA_DIM_MODEL'i destekler (dim kataloğundan bir model kimliği). ZeroClaw, MULTICA_ZEROCLAW_PATH'i destekler ama model değişkeni yoktur; model seçimi agent profiline aittir. MULTICA_<SAĞLAYICI>_ARGS üzerinden makine çapında varsayılan argümanlar şu anda beş araç için desteklenir: Claude Code, Codex, CodeBuddy, Qwen Code ve QwenPaw. Değişkenler MULTICA_CLAUDE_ARGS, MULTICA_CODEX_ARGS, MULTICA_CODEBUDDY_ARGS, MULTICA_QWEN_ARGS ve MULTICA_QWENPAW_ARGS'tır. Örneğin:

MULTICA_CLAUDE_PATH=/opt/bin/claude
MULTICA_CLAUDE_ARGS=--max-turns 40

Öncelik sırası komut satırı bayrağı → ortam değişkeni → ~/.multica/config.json → yerleşik varsayılandır. İzleyici davranışı için bkz. Daemon ve runtime'lar.

Daemon yapılandırmasını kalıcı hale getirme

Yaygın daemon tarafı ayarlar, kabuk ortam değişkenlerine güvenmek yerine ~/.multica/config.json'a da yazılabilir; adlandırılmış profiller kendilerinkini ~/.multica/profiles/<name>/config.json'da tutar:

multica config set poll_interval 10s
multica config show

Desteklenen anahtarlar:

Birkaç değer kuralı:

• Süre anahtarları pozitif Go süreleri kabul eder (10s, 2h gibi); 0s ve negatif değerler reddedilir. Tek istisna agent_timeout'tur: 0s geçerlidir ve çalıştırma zaman sınırını açıkça devre dışı bırakır.
• Boş bir dize geçmek, kalıcı bir değeri temizler ve ortam değişkenine veya yerleşik varsayılana döner, örneğin multica config set poll_interval "".
• max_concurrent_tasks, negatif olmayan bir tamsayı gerektirir.
• Göreli workspaces_root değerleri kaydedilirken mutlak yollara dönüştürülür.

Gözlemlenebilirlik ve analitik

Sırada

• Giriş ve kayıt — giriş yöntemleri ve kayıt kısıtlamaları.
• Sorun Giderme — dağıtım sorunlarının belirtiye dayalı teşhisi.
• Daemon ve runtime'lar — bu yapılandırmanın daemon tarafındaki karşılıkları.