Claude Code در ایران: کلود کد چیست و چطور با Claude کد بزنی

Claude Code ایجنت کدنویسی شرکت Anthropic است: داخل پوشهٔ پروژه‌ات اجرا می‌شود، کد را می‌خواند، فایل‌ها را ویرایش می‌کند، دستور اجرا می‌کند و با git کار می‌کند. اگر دنبال استفاده از Claude Code در ایران هستی، احتمالاً به یکی از این دو دیوار خورده‌ای: یا ثبت‌نام و پرداخت اشتراک ممکن نشده، یا نصب کرده‌ای و حالا نمی‌دانی به چه کلیدی وصلش کنی.

جواب کوتاه و صادقانه: Claude Code را نمی‌شود مستقیم به یوتاپن وصل کرد. ولی خود مدل‌های Claude، مثل Claude Sonnet 5 و Opus 5.5، در یوتاپن هستند و می‌توانی آن‌ها را در ایجنت‌های کدنویسی دیگری مثل opencode در ترمینال یا Cline در VS Code استفاده کنی، با پرداخت تومانی. در ادامه می‌بینی چرا Claude Code وصل نمی‌شود و راه عملی دقیقاً چیست.

کلود کد چیست

طبق مستندات رسمی Claude Code، این ابزار یک «agentic coding tool» است که کل کدبیس را می‌فهمد و روی چند فایل و چند ابزار هم‌زمان کار می‌کند. چند کاری که از آن انتظار می‌رود:

• ساخت فیچر و رفع باگ. کار را به زبان ساده می‌گویی؛ خودش برنامه می‌ریزد، کد را در چند فایل می‌نویسد و بررسی می‌کند.
• کار با git. تغییرها را stage می‌کند، پیام commit می‌نویسد، برنچ می‌سازد و pull request باز می‌کند.
• اتوماسیون از خط فرمان. با claude -p می‌شود خروجی یک دستور را به آن داد یا در CI اجرایش کرد.
• دستورالعمل پروژه. فایل CLAUDE.md در ریشهٔ پروژه را اول هر جلسه می‌خواند، و از MCP، skillها و hookها پشتیبانی می‌کند.

Claude Code روی ترمینال، افزونهٔ VS Code و JetBrains، اپ دسکتاپ و وب اجرا می‌شود. نصب ترمینالی‌اش روی macOS و Linux یک خط است:

curl -fsSL https://claude.ai/install.sh | bash

مشکل از قدم بعد شروع می‌شود. همان مستندات می‌گوید بیشتر محیط‌های اجرا به اشتراک Claude یا حساب Anthropic Console نیاز دارند و اولین اجرا از تو می‌خواهد وارد حساب شوی یا کلید ANTHROPIC_API_KEY بدهی.

چرا استفاده از Claude Code در ایران سخت است

دو مانع جدا وجود دارد:

۱. حساب و پرداخت. ایران در فهرست کشورهای پشتیبانی‌شدهٔ Anthropic نیست و طبق همان صفحه هر کشوری که در فهرست نباشد پشتیبانی نمی‌شود، چه برای Claude.ai و چه برای API. پرداخت اشتراک هم کارت بانکی بین‌المللی می‌خواهد. یعنی گرفتن اشتراک یا کلید رسمی از داخل ایران، از مسیر عادی، ممکن نیست. این یک توضیح فنی است، نه مشاورهٔ حقوقی.

۲. قالب API. فرض کن این بخش را حل کنی و دنبال یک سرویس واسط بگردی. Claude Code متغیری به نام ANTHROPIC_BASE_URL دارد که درخواست‌ها را به یک gateway دیگر می‌فرستد. ولی راهنمای سازگاری gateway صریح می‌گوید آن gateway باید یکی از قالب‌های خود Anthropic را ارائه کند: Messages API یعنی مسیر /v1/messages، یا قالب Amazon Bedrock یا Google Cloud. قالب Chat Completions اوپن‌ای‌آی در این فهرست نیست.

یوتاپن یک دروازهٔ سازگار با OpenAI است و مسیرهایی مثل /v1/chat/completions و /v1/embeddings را دارد، ولی /v1/messages را ندارد. پس اگر ANTHROPIC_BASE_URL را روی آدرس یوتاپن بگذاری، Claude Code کار نمی‌کند. این را در صفحهٔ Claude Code در مستندات هم نوشته‌ایم.

نکتهٔ مهم این است که محدودیت مال برنامهٔ Claude Code است، نه مدل. مدل Claude از مسیر Chat Completions در یوتاپن در دسترس است. پس کافی است ایجنتی را انتخاب کنی که با همین قالب حرف می‌زند.

واسط‌های مترجم: LiteLLM و claude-code-router

پروژه‌های متن‌بازی هستند که روی سیستم خودت اجرا می‌شوند، درخواست قالب Messages را از Claude Code می‌گیرند و به Chat Completions ترجمه می‌کنند، مثل پروکسی LiteLLM یا claude-code-router. از نظر فنی می‌توانند Claude Code را به هر سرویس سازگار با OpenAI وصل کنند. پیش از رفتن سراغشان این‌ها را بدان:

• ما این مسیر را تست نکرده‌ایم و پشتیبانی نمی‌کنیم.
• Claude Code با هر نسخه قابلیت تازه‌ای اضافه می‌کند که از طریق هدرها و فیلدهای مخصوص قالب Anthropic فرستاده می‌شود. مترجمی که آن‌ها را نشناسد ممکن است درخواست را خراب کند یا قابلیت را بی‌صدا خاموش کند.
• خود Anthropic در مستندات Claude Code می‌گوید gatewayهای شخص ثالث را تأیید، نگهداری یا بررسی نمی‌کند.
• کلیدت از یک لایهٔ اضافه رد می‌شود. اگر امتحانش می‌کنی، فقط روی ماشین خودت و با کلیدی که سقف ماهانهٔ کوچک دارد.

برای کار روزمره، راه کم‌دردسرتر این است که ایجنتی را انتخاب کنی که از اول برای سرویس‌های سازگار با OpenAI ساخته شده.

راه عملی: ایجنت کدنویسی سازگار با OpenAI + مدل Claude

این ایجنت‌ها با یوتاپن کار می‌کنند و راهنمای تنظیم هرکدام در مستندات هست:

• ترمینال: opencode، Crush، Aider، Qwen Code
• ویرایشگر: Cline و Kilo Code در VS Code

یک استثنا: Codex CLI در نسخه‌های فعلی فقط با Responses API کار می‌کند و با یوتاپن وصل نمی‌شود (توضیح کامل). فهرست کامل ابزارها در صفحهٔ یکپارچه‌سازی است.

اول کلید را جدا تست کن

از داشبورد ← کلیدها یک کلید بساز و در متغیر محیطی بگذار. پیش از تنظیم هر ایجنتی، مطمئن شو کلید و مدل جواب می‌دهند:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.uttapen.ir/v1",
    api_key=os.environ["UTTAPEN_API_KEY"],   # sk-up-...
)

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    max_tokens=200,
    messages=[{"role": "user", "content": "یک تابع پایتون بنویس که ایمیل را اعتبارسنجی کند."}],
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

یا با curl:

curl https://api.uttapen.ir/v1/chat/completions \
  -H "Authorization: Bearer $UTTAPEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-sonnet-5","max_tokens":50,"messages":[{"role":"user","content":"ping"}]}'

opencode در ترمینال

opencode نزدیک‌ترین تجربه به Claude Code است: ایجنتی ترمینالی که در پوشهٔ پروژه اجرا می‌شود. یوتاپن را به‌عنوان یک provider سفارشی در opencode.json (ریشهٔ پروژه یا ~/.config/opencode/opencode.json) تعریف کن:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "uttapen": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "uttapen",
      "options": {
        "baseURL": "https://api.uttapen.ir/v1",
        "apiKey": "{env:UTTAPEN_API_KEY}"
      },
      "models": {
        "anthropic/claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "limit": { "context": 200000, "output": 8192 }
        },
        "openai/gpt-5-nano": {
          "name": "GPT-5 nano",
          "limit": { "context": 400000, "output": 1024 }
        }
      }
    }
  },
  "model": "uttapen/anthropic/claude-sonnet-5",
  "small_model": "uttapen/openai/gpt-5-nano"
}

سه نکته که جای اشتباه دارد:

• npm باید @ai-sdk/openai-compatible باشد. پکیج @ai-sdk/openai سراغ /v1/responses می‌رود و 404 می‌گیری.
• limit.output را حتماً بگذار. اگر نگذاری، opencode روی هر درخواست max_tokens: 32000 می‌فرستد و مبلغ بزرگی از موجودی رزرو می‌شود.
• small_model را روی یک مدل ارزان بگذار. وگرنه opencode عنوان گفتگو را هم با Claude Sonnet می‌سازد.

بعد تست کن:

opencode run -m uttapen/anthropic/claude-sonnet-5 "فایل‌های این پروژه را خلاصه کن"

اگر opencode در شروع گیر کرد و جوابی نداد، معمولاً تماس‌های پس‌زمینهٔ خود opencode به سرویس‌هایش است، نه یوتاپن. راه‌حل و بقیهٔ جزئیات در راهنمای کامل opencode آمده.

Cline در VS Code

اگر ترجیح می‌دهی داخل ویرایشگر کار کنی، Cline را نصب کن، روی چرخ‌دندهٔ تنظیماتش بزن و:

1. در API Provider گزینهٔ OpenAI Compatible را انتخاب کن، نه OpenAI. گزینهٔ OpenAI سراغ Responses API می‌رود.
2. Base URL را https://api.uttapen.ir/v1 بگذار و کلید sk-up-… را در فیلد API Key بچسبان.
3. Model ID را anthropic/claude-sonnet-5 بنویس یا از فهرست انتخاب کن. Cline فهرست را از /v1/models می‌گیرد.
4. در بخش Model Configuration، فیلد Max Output Tokens را حدود 8192 بگذار تا رزرو هر درخواست معقول بماند.

Cline گزینهٔ Use different models for Plan and Act هم دارد: Claude Sonnet برای برنامه‌ریزی و یک مدل ارزان‌تر برای اجرا. جدول خطاها در راهنمای Cline است.

کدام مدل Claude برای کدنویسی

شناسه‌ها را عیناً از کاتالوگ بردار، با پیشوند anthropic/:

• anthropic/claude-sonnet-5: انتخاب پیش‌فرض برای ایجنت کدنویسی. ورودی ۶۹۲٬۴۳۹ و خروجی ۳٬۴۶۲٬۱۹۴ تومان به‌ازای هر میلیون توکن.
• anthropic/claude-sonnet-5.5: نسخهٔ جانشین Sonnet 5. ورودی ۶۹۲٬۴۳۹ و خروجی ۳٬۴۶۲٬۱۹۴ تومان.
• anthropic/claude-opus-5.5: برای تغییرهای بزرگ و چندمرحله‌ای در کدبیس بزرگ، با هزینهٔ بیشتر.
• anthropic/claude-haiku-4.5: سریع و ارزان، برای کارهای سبک یا مرحلهٔ Act در Cline.

اگر نمی‌دانی کدام مدل برای کد خودت بهتر است، مقایسهٔ مدل‌ها روی ۵ وظیفهٔ واقعی برنامه‌نویسی یک harness باز می‌دهد که روی پروژهٔ خودت اجرا کنی. جزئیات قیمت همهٔ نسخه‌های Claude و کش پرامپت در راهنمای API Claude در ایران آمده.

هزینه را از اول مهار کن

ایجنت کدنویسی پرمصرف است: هر گام، کل گفتگو به‌علاوهٔ تکه‌هایی از فایل‌ها را دوباره می‌فرستد و context زود بزرگ می‌شود. برای حس عدد: یک گام با ۳۰ هزار توکن ورودی و ۲ هزار توکن خروجی روی Claude Sonnet 5 امروز حدود ۲۸٬۰۰۰ تومان است، و یک کار متوسط ممکن است ده‌ها گام داشته باشد. هزینهٔ واقعی هر درخواست را در داشبورد ← مصرف ببین.

سه تنظیم جلوی غافلگیری را می‌گیرد:

1. کلید جدا برای ایجنت، با سقف ماهانه. در تنظیمات کلید، monthly_limit_toman را بگذار. اگر مصرف این کلید در ماه از آن بگذرد، درخواست بعدی 429 key_monthly_limit_reached می‌گیرد و بقیهٔ موجودی‌ات دست نمی‌خورد.
2. محدود کردن مدل‌ها. با allowed_models فقط مدل‌هایی را مجاز کن که در opencode یا Cline تعریف کرده‌ای. اگر ایجنت به اشتباه مدل گران‌تری را صدا بزند، 403 model_not_allowed می‌گیرد.
3. سقف خروجی معقول. limit.output در opencode یا Max Output Tokens در Cline را حدود 8192 بگذار. یوتاپن پیش از هر درخواست هزینهٔ بیشترین خروجی ممکن را رزرو می‌کند و بعد فقط مصرف واقعی را کم می‌کند. سقف بزرگ پول بیشتری نمی‌گیرد، ولی موجودی بیشتری را موقتاً قفل می‌کند و چند درخواست هم‌زمان رزروهایشان جمع می‌شود.

یک عادت ساده هم کمک می‌کند: برای هر کار جدید گفتگوی تازه شروع کن تا context کار قبلی همراه هر درخواست فرستاده نشود. توضیح کلی قیمت‌گذاری در صفحهٔ قیمت‌ها است.

سؤال‌های رایج

آیا Claude Code در ایران کار می‌کند؟

حتی اگر نصبش کنی، برای استفاده به اشتراک Claude یا حساب Anthropic Console نیاز دارد و ایران در فهرست کشورهای پشتیبانی‌شدهٔ Anthropic نیست. یوتاپن هم مسیر /v1/messages را که Claude Code لازم دارد ندارد. راه عملی، استفاده از مدل Claude در ایجنتی مثل opencode یا Cline است.

می‌شود ANTHROPIC_BASE_URL را روی یوتاپن گذاشت؟

نه. این متغیر فقط وقتی کار می‌کند که مقصد قالب Messages API خود Anthropic را ارائه کند. یوتاپن قالب OpenAI را ارائه می‌کند، پس درخواست‌های Claude Code جواب درست نمی‌گیرند. اگر روزی این مسیر اضافه شود، صفحهٔ Claude Code در مستندات به‌روز می‌شود.

کلود کد رایگان است؟

خود نرم‌افزار را رایگان نصب می‌کنی، ولی طرح رایگان Claude شامل Claude Code نیست. برای کار کردن یا یکی از اشتراک‌های پولی Claude لازم است یا حساب Console که هزینه‌اش بر اساس توکن مصرفی حساب می‌شود. در یوتاپن هم طرح رایگان نداریم. هزینه بر اساس مصرف واقعی از کیف پول تومانی کم می‌شود.

بهترین جایگزین Claude Code برای کار با مدل Claude چیست؟

اگر در ترمینال کار می‌کنی، opencode نزدیک‌ترین تجربه است. اگر در VS Code کار می‌کنی، Cline یا Kilo Code. هر سه با شناسه‌هایی مثل anthropic/claude-sonnet-5 از یوتاپن کار می‌کنند. Aider و Crush هم گزینه‌های ترمینالی‌اند.

کیفیت Claude در opencode با Claude Code یکی است؟

مدل همان مدل است، ولی ایجنت فرق دارد. پرامپت سیستمی، ابزارها، نحوهٔ ویرایش فایل و مدیریت context در هر ایجنت متفاوت است، پس نتیجه هم می‌تواند فرق کند. قابلیت‌های مخصوص Claude Code، مثل skillها، hookها و subagentهایش، در ابزار دیگر به همان شکل وجود ندارند.

چطور مطمئن شوم ایجنت کیف پولم را خالی نمی‌کند؟

یک کلید جدا برای ایجنت بساز، سقف ماهانه و فهرست مدل‌های مجاز بگذار و سقف خروجی را محدود کن. اگر کلید لو رفت، از داشبورد لغوش کن. لغو فوری است و درخواست بعدی با آن کلید رد می‌شود.