gaogaoGao Kaptan Docsv0.90.x
Örnekler

Paperclip: ajanlardan bir şirket, kendi modelinizle

Paperclip'i Kaptan'a kurun, ajanlarını Claude Code üzerinden kurum içindeki Qwen3.8'e bağlayın. İş atayın, ajan çalışsın, çıktıyı panodan izleyin.

Paperclip açık kaynak bir ajan orkestrasyon platformudur. Tek tek ajanları değil, onlardan kurulu bir şirketi yönetir: org şeması, roller, hedefler, bütçe, onay süreçleri ve maliyet takibi. Ajanları kendisi yazmaz — Claude Code, Codex, Cursor, Gemini CLI gibi hazır koşucuları işe alır.

Bu sayfa Paperclip'i Gao Kaptan'a kuruyor ve ajanlarını kurum içindeki Qwen3.8'e bağlıyor. İş panodan atanıyor, ajan kurumun kendi GPU'sunda düşünüyor, çıktı panoya dönüyor.

Pano (pod :3100) ── iş ata ──▶ Paperclip koşucusu ──▶ Claude Code
                                                          │
                                            LiteLLM köprüsü  /v1/messages
                                                          │
                                        Kaptan inference · Qwen3.8-27B-FP8

Tek pod yetiyor: Paperclip gömülü bir Postgres çalıştırıyor, ayrı veritabanı pod'u gerekmiyor.

Kurulum

Pod

ubuntu:24.04, web_port: 3100, dışarı açık, internet çıkışı açık.

node:24 imajını denemeyin. ~1 GB ve containerd'in çekme süresi doluyor — pod ImagePullBackOff'ta kalıyor, olaylarda DeadlineExceeded görünüyor. Ubuntu tabanı zaten düğümde önbellekte olduğu için Node'u NodeSource'tan kurmak çok daha hızlı.

Açılış betiği üç şey yapıyor: Node 24, Claude Code ve ayrıcalıksız bir dev kullanıcısı.

curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
apt-get install -y nodejs          # Paperclip Node 24.11+ istiyor

PKG=@anthropic-ai/claude-code-linux-x64
VER=$(curl -fsSL "https://registry.npmjs.org/${PKG}/latest" \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["version"])')
curl -fsSL -o /tmp/cc.tgz \
  "https://registry.npmjs.org/${PKG}/-/claude-code-linux-x64-${VER}.tgz"
mkdir -p /opt/claude-code && tar xzf /tmp/cc.tgz -C /opt/claude-code
chmod +x /opt/claude-code/package/claude
ln -sf /opt/claude-code/package/claude /usr/local/bin/claude

useradd -m -s /bin/bash dev        # Claude Code root altında izinsiz kipte çalışmaz

Ortam değişkenleri — ajanların modeli buradan geliyor:

AnahtarDeğer
ANTHROPIC_BASE_URLköprünün adresi, http://<kopru>-svc.<ns>.svc.cluster.local:4000
ANTHROPIC_AUTH_TOKENköprünün LITELLM_MASTER_KEY değeri
ANTHROPIC_MODEL / ANTHROPIC_SMALL_FAST_MODELclaude-sonnet-4-5
MAX_THINKING_TOKENS0
CLAUDE_CODE_MAX_OUTPUT_TOKENS16000 (aşağıdaki uyarıya bakın)
PAPERCLIP_COMPANY_NAME / PAPERCLIP_AGENT_NAMEilk açılışta kurulan şirket ve CEO ajanının adı
PAPERCLIP_TELEMETRY_DISABLED / DO_NOT_TRACK1

CLAUDE_CODE_MAX_OUTPUT_TOKENS bağlam penceresinden düşüyor — 64000 yazmak ajanı kırıyordu. Ölçüldü: vLLM'in sınırı isteme değil, istem + max_tokens toplamına uygulanıyor ve bu kurulumda 131 072. Claude Code bu değeri her istekte max_tokens olarak gönderdiği için 64000, kullanılabilir istemi ~67k'ya düşürüyordu. Ajanın konuşması orayı geçtiğinde yukarı akış 400 dönüyor, LiteLLM akışlı yolda o 400'ü yutup boş ve sırası bozuk bir akış yayınlıyor (content_block_stop, content_block_delta'dan önce) ve Claude Code "API Error: The response stream was malformed" deyip düşüyor — Paperclip tarafında adapter_failed, hiç token harcanmadan, ekranda sebep görünmeden.

Aynı 112 017 token'lık istemle, yalnızca max_tokens değiştirilerek ölçüldü:

max_tokensakışcevap
64 000start → stop → delta (bozuk)boş
32 000start → stop → delta (bozuk)boş
16 000doğru sıragerçek cevap
8 000doğru sıragerçek cevap

16 000 ile kullanılabilir istem ~67k'dan ~115k'ya çıkıyor. Şablon bu değeri kendisi veriyor. Bunu yükseltmek istiyorsanız pencereden düştüğünü hesaba katın; köprüde max_tokens kırpmayı denedik, işe yaramadı — LiteLLM onu üst sınır değil varsayılan sayıyor, istemcinin gönderdiği daha büyük değer geçiyor.

LiteLLM köprüsü

Köprü gerekli, ve bu ölçülerek doğrulandı — Claude Code'u doğrudan Gao Kaptan inference'a bağlamayı denerseniz üç ayrı duvara çarparsınız:

  1. Biçim. Claude Code Anthropic biçimini konuşur ve /v1/messages çağırır; Gao Kaptan inference OpenAI-uyumludur ve o uç yoktur — 404.
  2. Model adı. Qwen/Qwen3.8-27B-FP8 gönderildiğinde Claude Code "is not a model this version of Claude Code recognizes" deyip "There's an issue with the selected model" ile düşer.
  3. Düşünme blokları. Aşağıdaki config'in extra_body satırı süs değil. O satır olmadan Qwen'in düşünme çıkışı Anthropic akışında imzasız bir thinking bloğu olarak yayınlanıyor — akışta birebir content_block_start → {"type":"thinking","signature":""} görünüyor — ve Claude Code imzasız thinking'i kabul etmiyor: "API Error: The response stream was malformed". Paperclip tarafında koşum adapter_failed ile düşer, hiç token harcanmaz ve ekranda sebep görünmez. Düşünme kapatılınca akış tek bir text bloğuna iniyor ve koşum başarıyla bitiyor.

Köprü üçünü de çözer: Anthropic biçimini sunar, tanınan bir ad yayınlar ve düşünmeyi kapatır.

model_list:
  - model_name: claude-sonnet-4-5      # Claude Code'un tanidigi bir ad
    litellm_params:
      model: hosted_vllm/Qwen/Qwen3.8-27B-FP8
      api_base: https://kaptan.isnet.net.tr/api/v1/inference/v1
      api_key: <Kaptan inference anahtarınız>
      max_parallel_requests: 4
      max_tokens: 64000
      extra_body: {"chat_template_kwargs": {"enable_thinking": false}}

litellm_settings:
  drop_params: true
  request_timeout: 600
  json_logs: true

Aynı köprü başka kılıklar da yayınlayabilir; ayrıntı için Plane örneği.

Panoyu açın

Başka adım yok: panelden Aç deyin.

Eskiden burada dört adım vardı — Paperclip'i --bind lan ile kurmak, 403 veren relay adını izinli listeye eklemek, kayıt dosyasından davet bağlantısını okuyup hesap açmak ve koşucuyu Paperclip'in formunda elle ayarlamak. Dördü de kalktı. Şablon artık Paperclip'i local_trusted kipinde (yalnızca loopback) başlatıyor, önüne nginx koyuyor ve ilk açılışta bir şirket ile bir CEO ajanı kuruyor; ajanın modeli ve kimlik bilgisi köprüye bağlı olarak geliyor.

İlk açılış birkaç dakika sürer — Node 24, Claude Code ikilisi ve Paperclip indirilir. İlerlemeyi pod kaydından izleyebilirsiniz; sunucunun kendi kaydı /home/dev/paperclip-server.log dosyasındadır.

Giriş neden sorulmuyor. Paperclip iki dağıtım kipi taşıyor. authenticated kipi hesap, davet ve izinli adres listesi ister; local_trusted kipi bunların hiçbirini istemez ama zorunlu olarak yalnızca loopback'e bağlanır — kütüphanenin kendi ifadesi local_trusted requires server.bind=loopback. Şablon bu ikinci kipi seçip Paperclip'i 127.0.0.1:3101'de tutuyor, dışarıya nginx :3100 bakıyor ve yukarı akışa Host: localhost yazıyor. Bunun ikinci faydası daha büyük: Paperclip artık kendisine söylenmemiş bir adres hiç görmediği için 403 "This hostname is not allowed" sorunu tümüyle ortadan kalktı. Proxy'nin ÜÇ başlığı birden sabitlemesi şart (Host, X-Forwarded-Host, X-Forwarded-Server): kontrol server/middleware/private-hostname-guard.js içinde forwardedHost || hostHeader sırasıyla çalışıyor, yani önce forward edilen adrese bakıyor ve ingress-nginx o başlığı gerçek adla ekliyor. Yalnızca Host'u düzeltmek yetmez — üstelik pod içinden atılan düz bir curl'de o başlık olmadığı için test 200 verir ve kusuru gizler. Kimlik denetimi Gao Kaptan'ın katmanında kalıyor: pod'a erişim relay üzerinden ve namespace'in tenant-isolation ağ politikası altında olduğu için pano başka bir müşterinin pod'undan görünmez.

İş verin

Assign Task ile bir görev yazın. Ajan işi devralır, panoda Live görünür ve adımlarını gerçek zamanlı yazar — Paperclip'in kendi beceri dosyalarını okuyup çıktıyı nasıl teslim edeceğine karar verdiği görülebilir:

Ajanın koşu kaydı

Pano: CEO ajanı çalışıyor

Tuzaklar

1 — Ajanın çalışma dizini /workspace değil. Her ajan kendi izole dizininde çalışır:

~/.paperclip/instances/default/workspaces/<agentId>/

Ajan "dosyayı yazdım" dediğinde /workspace'e bakıp boş bulmak yanıltıcıdır; dosya oradadır. Ajanın kendisi de bunu bilir ve çıktıyı panoya artifact olarak yüklemeye çalışır, çünkü kendi dizinine pano kullanıcıları erişemez.

2 — Gao Kaptan'ın pod erişim jetonu kendiliğinden düşebiliyor. Çalışan bir bağlantı bir süre sonra 401 Authorization Required vermeye başlıyor; pod'a dokunmasanız bile. POST /api/v1/pods/<id>/access-token/regenerate ile yeni jeton alıp bağlantıyı yeniden kurmak çözüyor. Aynı davranış Plane kurulumunda da görüldü.

3 — Koşum adapter_failed diyor ve sebebini yazmıyor. Panoda görünen tek şey başarısız bir koşum; model tarafındaki gerçek hata koşum kaydında. Pod terminalinden:

su - dev
paperclipai run list -C <sirket-id>     # koşumlar ve durumları
paperclipai run log <kosum-id>          # o koşumun ham akışı

Bu sayfadaki enable_thinking duvarı da tam böyle bulundu — panoda sebep yok, ham akışta "The response stream was malformed" var.

Ne zaman bu, ne zaman MCP? Paperclip işi organize eder — roller, bütçe, onay, maliyet. Yalnızca "ajanım şu iş takip sistemini yönetsin" istiyorsanız daha ucuz yol Plane MCP sunucusudur: tek ajan, tek jeton, ek pano yok.

Bu sayfa yardımcı oldu mu?

Plane: self-hosted proje yönetimi + kendi modeliniz

Plane'i Kaptan'a kurun, AI'ını kurum içindeki Qwen'e bağlayın. Relay'in arkasında CSRF, imajın kendi ortam değişkenlerini ezmesi ve model beyaz listesi — üçünün de çözümü.

Ajan ekibine gerçek iş yaptırmak: GitHub'dan Kaptan'a

Paperclip ekibi GitHub'daki issue'ları alsın, kodu yazsın, PR'ı incelesin, birleştirsin ve sonucu Kaptan'da pod olarak yayına alsın — siz yalnızca issue açın.

On this page

KurulumPodLiteLLM köprüsüPanoyu açınİş verinTuzaklar