پرش به مطلب اصلی

اتصال OpenCode به چابکان

OpenCode چیست؟​

OpenCode یک عامل برنامه‌نویسی متن‌باز است که در terminal، برنامه دسکتاپ و افزونه IDE قابل استفاده است. این ابزار می‌تواند پروژه را تحلیل کند، با اشاره به فایل‌ها پاسخ بدهد، در Plan mode برنامه تغییر بسازد و در Build mode کد و تست را اجرا کند. پشتیبانی از provider سفارشی باعث می‌شود بتوان endpoint و مدل را مستقل از سرویس پیش‌فرض انتخاب کرد.

در اتصال OpenCode به چابکان، adapter نوع @ai-sdk/openai-compatible درخواست‌ها را به /v1/chat/completions می‌فرستد. چابکان inference و گزارش مصرف را انجام می‌دهد؛ OpenCode مسئول context پروژه، permissionها، فایل‌ها، shell و اشتراک‌گذاری نشست است.

OpenCode برای چه کسانی مناسب است؟​

  • توسعه‌دهندگانی که coding agent متن‌باز و terminal-first می‌خواهند؛
  • تیم‌هایی که config پروژه، AGENTS.md و commandهای تکرارپذیر نیاز دارند؛
  • کاربرانی که می‌خواهند بین چند مدل چابکان جابه‌جا شوند؛
  • کسانی که Plan و Build را از هم جدا و permissionها را دقیق کنترل می‌کنند.

برای اولین اجرا از یک پروژه آزمایشی بدون secret شروع کنید و پیش از Build mode، اتصال ساده و Plan mode را آزمایش کنید.

۱. نصب OpenCode​

با Node.js:

npm install -g opencode-ai
opencode --version

در ویندوز نیز همین روش قابل استفاده است، اما برای تجربه کامل‌تر استفاده از WSL پیشنهاد می‌شود.

۲. آماده‌کردن کلید​

macOS، Linux و WSL:

export CHABOKAN_AI_API_KEY="sk-chbk-کلید-واقعی-شما"

PowerShell:

$env:CHABOKAN_AI_API_KEY = "sk-chbk-کلید-واقعی-شما"

۳. تعریف provider سفارشی​

فایل سراسری ~/.config/opencode/opencode.json یا فایل opencode.json ریشه پروژه را بسازید یا ویرایش کنید. فایل پروژه می‌تواند تنظیم سراسری را override کند؛ پیش از اجرا هر دو را بررسی کنید.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "chabokan/openai/gpt-4o-mini",
  "small_model": "chabokan/openai/gpt-4o-mini",
  "share": "disabled",
  "permission": {
    "*": "ask",
    "external_directory": "deny"
  },
  "provider": {
    "chabokan": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Chabokan AI",
      "options": {
        "baseURL": "https://ai.chabokan.net/v1",
        "apiKey": "{env:CHABOKAN_AI_API_KEY}"
      },
      "models": {
        "openai/gpt-4o-mini": {
          "name": "Chabokan - GPT 4o Mini",
          "limit": {
            "context": 128000
          }
        }
      }
    }
  }
}

همه محل‌های دارای openai/gpt-4o-mini و مقدار limit.context را با شناسه و context واقعی مدل هماهنگ کنید. پیشوند chabokan/ فقط نام provider داخل OpenCode است و جزو شناسه مدل ارسالی به چابکان نیست.

small_model برای کارهای کمکی OpenCode صریح شده تا ابزار بی‌خبر به provider دیگری نرود. share: disabled از اشتراک‌گذاری نشست جلوگیری می‌کند و تنظیم permission برای عملیات ابزار تأیید می‌خواهد.

۴. ثبت امن credential به‌جای options.apiKey​

پیکربندی بالا کلید را از environment می‌خواند و برای پروژه‌های تیمی مناسب است. در نسخه‌هایی که جریان /connect را ارائه می‌کنند، می‌توانید این روش را نیز به‌کار ببرید:

  1. OpenCode را اجرا کنید.
  2. دستور /connect را بزنید.
  3. گزینه Other را انتخاب کنید.
  4. شناسه provider را دقیقاً chabokan وارد کنید.
  5. کلید چابکان را paste کنید.

در این حالت credential در ~/.local/share/opencode/auth.json نگهداری می‌شود؛ بخش options.apiKey را می‌توانید حذف کنید. از فایل auth و backupهای آن محافظت کنید.

۵. انتخاب و آزمایش مدل​

  1. OpenCode را در پوشه پروژه اجرا کنید.
  2. دستور /models را بزنید.
  3. مدل زیر مجموعه Chabokan AI را انتخاب کنید.
  4. درخواست آزمایشی زیر را بفرستید:
پروژه را بررسی کن و بدون ویرایش فایل‌ها، روش اجرای آن را توضیح بده.

سپس فقط یک ابزار کم‌خطر را آزمایش کنید:

فقط فایل README.md را بخوان و هدف پروژه را در سه مورد توضیح بده.
هیچ فایل یا تنظیمی را تغییر نده و هیچ فرمانی اجرا نکن.

پاسخ متنی فقط اتصال مدل را ثابت می‌کند؛ خواندن موفق فایل، مسیر جداگانه tool calling و permission را نیز آزمایش می‌کند.

۶. تعریف چند مدل​

برای مدل سریع و مدل agentic می‌توانید چند entry زیر یک provider داشته باشید:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "chabokan/provider/agent-model-id",
  "small_model": "chabokan/provider/fast-model-id",
  "provider": {
    "chabokan": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Chabokan AI",
      "options": {
        "baseURL": "https://ai.chabokan.net/v1",
        "apiKey": "{env:CHABOKAN_AI_API_KEY}"
      },
      "models": {
        "provider/agent-model-id": {
          "name": "Chabokan Agent Model",
          "limit": { "context": 128000 }
        },
        "provider/fast-model-id": {
          "name": "Chabokan Fast Model",
          "limit": { "context": 64000 }
        }
      }
    }
  }
}

شناسه‌ها و limitهای بالا placeholder هستند و نباید عیناً استفاده شوند. مقدارهای واقعی را از /v1/models بردارید. برای تغییر مدل داخل TUI از /models استفاده کنید.

۷. اجرای یک‌باره از CLI​

برای بررسی بدون ورود به رابط تعاملی:

opencode run --model chabokan/openai/gpt-4o-mini \
  "بدون تغییر فایل‌ها، ساختار این پروژه را توضیح بده"

قبل از استفاده در CI، خروجی، exit code، permissionها و سقف مصرف را در یک repository آزمایشی بررسی کنید.

۸. سناریوی عملی: توضیح، اصلاح، تست و بازبینی​

این تمرین را ابتدا روی پروژه disposable انجام دهید.

مرحله اول: توضیح بدون تغییر​

فایل totals.py و تست‌های آن را بخوان.
باگ را توضیح بده اما هنوز چیزی را تغییر نده.

مرحله دوم: برنامه اصلاح​

یک برنامه کوتاه برای اصلاح بنویس.
فایل‌هایی که تغییر می‌کنند و دستور تست را دقیقاً نام ببر.
منتظر تأیید من بمان.

مرحله سوم: تغییر محدود​

فقط تغییر تأییدشده را اعمال کن.
فایل دیگری را تغییر نده و dependency تازه نصب نکن.

مرحله چهارم: آزمون و بازبینی​

تست مرتبط را اجرا کن، سپس diff را خلاصه کن.
اگر تست شکست خورد، علت را گزارش کن و بدون تأیید تغییر تازه نده.

پس از پایان، خودتان git diff و تست‌ها را مستقل اجرا کنید. پاسخ agent جایگزین acceptance test نیست.

۹. فرمان‌های سفارشی پروژه​

برای کار تکراری، بخش command را به config اضافه کنید:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "review-safe": {
      "description": "بازبینی فقط‌خواندنی تغییرات",
      "agent": "plan",
      "model": "chabokan/openai/gpt-4o-mini",
      "template": "فقط git diff را بررسی کن. فایل تغییر نده، فرمان مخرب اجرا نکن و یافته‌ها را با نام فایل گزارش بده."
    },
    "test-target": {
      "description": "اجرای تست مشخص‌شده",
      "agent": "build",
      "template": "فقط تست مربوط به $ARGUMENTS را اجرا کن، خطا را خلاصه کن و پیش از هر ویرایش منتظر تأیید بمان."
    }
  }
}

در TUI می‌توانید /review-safe یا /test-target نام-تست را اجرا کنید. این بخش را با provider موجود merge کنید و کل فایل config را جایگزین نکنید.

۱۰. تنظیم دقیق مجوزها​

برای شروع امن:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": "allow",
    "edit": "ask",
    "bash": "ask",
    "external_directory": "deny"
  }
}

مقادیر allow، ask و deny را OpenCode اجرا می‌کند، نه چابکان. استفاده از --auto درخواست‌های تأیید را تغییر می‌دهد؛ در repository واقعی آن را بدون deny ruleهای صریح فعال نکنید.

۱۱. عیب‌یابی OpenCode​

نشانهبررسی
provider در /models نیستکلید provider.chabokan.models و یکسان‌بودن ID در /connect و config
401opencode auth list، کلید فعال و environment همان process
404baseURL دقیقاً یک /v1 داشته باشد و adapter برابر @ai-sdk/openai-compatible باشد
مدل اشتباه اجرا می‌شودconfig محلی پروژه، model و small_model را بررسی کنید
tool call به‌شکل متن برمی‌گرددمدل دارای tools، adapter و یک read-only tool ساده را جدا آزمایش کنید
context errorlimit.context را با /v1/models یکسان و نشست را محدود کنید
مصرف زیادloop عامل، کارهای small model و retryها را در گزارش درخواست‌ها بررسی کنید

مرز اعتبارسنجی​

این راهنما config را با قرارداد فعلی OpenCode و endpoint چابکان تطبیق می‌دهد، اما سازگاری end-to-end همه نسخه‌ها، مدل‌ها و pluginها را تضمین نمی‌کند. پیش از استفاده روی repository سازمانی، یک pilot کم‌خطر انجام دهید.

منابع: نصب OpenCode، Custom provider، Permissions، Config و commandها