OpenHands

OpenHands হলো open-source AI software engineer, যে একটা sandbox-এর ভেতরে code এডিট করে, command চালায় আর browse করে। এটা model ডাকে LiteLLM দিয়ে, তাই Tokens যোগ করতে হয় OpenAI-compatible endpoint হিসেবে: openai/ দিয়ে শুরু হওয়া একটা model string, https://tokens.bd/v1 Base URL, আর আপনার Tokens key। request যায় OpenAI Chat Completions ধাঁচে।

যা যা লাগবে#

• একটা Tokens key। শুধু OpenHands-এর জন্য আলাদা key বানান, মাসিক spend cap দিয়ে (API keys)।
• /models থেকে model id। উদাহরণগুলোতে deepseek/deepseek-v4.1-flash ব্যবহার করা হয়েছে।
• OpenHands install করা। CLI আর local web UI, দুটোতেই Python 3.12 আর uv লাগে, নয়তো binary বা Docker ব্যবহার করতে পারেন। web UI-র জন্য Docker চালু থাকাও দরকার। Windows-এ OpenHands বলছে সবকিছু WSL (Ubuntu)-র ভেতরে চালাতে।
• tool calling support করে এমন model। OpenHands বলছে তার একটা শক্তিশালী model দরকার, আর open-weight model-গুলো tool কতটা ভরসা করে ডাকতে পারে তা model ভেদে আলাদা।

কোন model string লিখবেন#

LiteLLM প্রথম slash-এর আগের লেখা দেখে provider ঠিক করে। নিজস্ব OpenAI-compatible endpoint-এর জন্য ওই লেখা হতে হবে openai/, আর OpenHands বলছে Custom Model-এ এই prefix বাধ্যতামূলক। Tokens-এর id-তেই আগে থেকে একটা slash আছে (provider/model), তাই আপনি যা লিখবেন তাতে slash থাকবে দুটো:

openai/deepseek/deepseek-v4.1-flash

ধাঁচটা হলো openai/<Tokens model id>। যেসব proxy-র নিজস্ব routing prefix আছে, তাদের জন্য OpenHands একই ধাঁচ লিখেছে (openai/<proxy-prefix>/<model-name>), আর তার local LLM পাতায় LM Studio-র যে model-এর id-তে slash আছে, সেখানে openai/qwen/qwen3.6-35b-a3b লেখা। কোন অংশটা endpoint-এ যায়, তা OpenHands বা LiteLLM কেউই documentation-এ বলেনি। এই উদাহরণগুলো ধরে নিচ্ছে যে LiteLLM প্রথম openai/ শুধু provider বাছতে ব্যবহার করে, বাকিটা পাঠায়, এখানে যেটা deepseek/deepseek-v4.1-flash, আর Tokens ঠিক এই id-ই চায়। এটা উদাহরণ দেখে আমাদের বোঝা, documentation-এ দেওয়া কোনো নিশ্চয়তা নয়। request model_not_found হয়ে ফিরলে নিচের সমস্যা-সমাধান অংশ দেখুন।

Web UI-তে setup করুন#

UI চালু করুন:

uv tool install openhands --python 3.12
openhands serve

http://localhost:3000 খুলুন। তারপর:

1. Settings বাটনে (gear আইকন) ক্লিক করুন, তারপর LLM tab-এ যান।
2. Advanced toggle চালু করুন।
3. Custom Model-এ লিখুন openai/deepseek/deepseek-v4.1-flash।
4. Base URL-এ দিন https://tokens.bd/v1।
5. API Key-এ আপনার Tokens key বসান।
6. settings save করুন।

OpenHands তার সব state রাখে আপনার machine-এর ~/.openhands-এ। ওই folder গোপন রাখুন আর কখনো commit করবেন না, কারণ সেখানে আপনার settings আছে, আর key-ও থাকতে পারে।

CLI-তে setup করুন#

প্রথমবার চালালে CLI একটা LLM provider আর API key জিজ্ঞেস করে, তারপর সেগুলো ~/.openhands/-এর নিচে রেখে দেয়। আমরা যে পাতাগুলো পড়েছি, সেগুলোতে ওই প্রথম dialog-এ Base URL বা Custom Model-এর কোনো প্রশ্নের কথা নেই, তাই Tokens-এর জন্য environment variable ব্যবহার করুন:

export LLM_API_KEY="tok_live_your_key"
export LLM_MODEL="openai/deepseek/deepseek-v4.1-flash"
export LLM_BASE_URL="https://tokens.bd/v1"
openhands --override-with-envs

পরে জমানো model বদলাতে চাইলে CLI-তে Ctrl+P চেপে Settings বেছে নিন, নয়তো ~/.openhands/agent_settings.json-এর model field বদলে দিন। CLI-র docs জমানো LLM settings-এর জন্য settings.json আর agent_settings.json, দুটোরই নাম নিয়েছে, তাই আপনার version কোনটা ব্যবহার করে তা folder-এ দেখে নিন। CLI-র Settings screen-এ Base URL field আছে কি না, সেটা documentation থেকে আমরা নিশ্চিত হতে পারিনি, আর সেজন্যই ওপরের ধাপগুলোতে environment variable ব্যবহার করা হয়েছে।

Windows-এ এই command-গুলো PowerShell-এ নয়, WSL shell-এ চালান।

ঠিকমতো চলছে কি না দেখুন#

আগে OpenHands-কে বাদ দিয়ে পরীক্ষা করুন, id দিন Tokens যেভাবে চায় সেভাবে (openai/ prefix ছাড়া):

curl https://tokens.bd/v1/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4.1-flash", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'

তারপর OpenHands-এ ছোট একটা কিছু চান ("List the files in the workspace and tell me what the project does")। agent উত্তর দেবে আর একটা command চালাবে, এমনটাই আশা, আর request-টা আপনার Dashboard-এর usage analytics-এ দেখা যাবে। কোনো action ছাড়া শুধু উত্তর এলে সাধারণত বুঝবেন model tool ডাকছে না।

Model বাছাই#

OpenHands লম্বা লম্বা tool call-এর loop-এ কাজ করে, তাই এমন model নিন যার tool calling জোরালো আর context লম্বা। তুলনা পাবেন Choosing a model-এ, আর /models-এ প্রতিটা model-এর context ও output সীমা আছে। লম্বা বা ঝুঁকির কাজে সাধ্যের মধ্যে সবচেয়ে শক্তিশালী model নিতে OpenHands নিজেই পরামর্শ দেয়।

আমরা যে পাতাগুলো পড়েছি, সেগুলোতে context window বা max output-এর জন্য কোনো field-এর কথা নেই। model-এর native tool calling-এর switch থাকলে OpenHands বলছে model customization-এর নিচে সেটা চালু-বন্ধ করা যায়। malformed JSON error বা খারাপ output পেলে OpenHands সবার আগে আরও শক্তিশালী model বা বড় context window নিতে বলে।

সীমা আর যা জানা দরকার#

• খরচ। OpenHands ব্যর্থ call আবার চেষ্টা করে (LLM_NUM_RETRIES, ডিফল্ট 4), আর কাজ শেষ না হওয়া পর্যন্ত loop চালায়। একটা task থেকেই শয়ে শয়ে request যেতে পারে, প্রতিটায় বাড়তে থাকা পুরো conversation। spend cap দেওয়া key ব্যবহার করুন (API keys) আর Dashboard দেখে রাখুন। OpenHands নিজেও spending limit দিয়ে রাখতে সতর্ক করে।
• LiteLLM-এর খরচ। OpenHands যে খরচ দেখায়, সেটা LiteLLM-এর নিজের দামের তালিকা থেকে আন্দাজ করা, আর ওই তালিকায় Tokens-এর id নাও থাকতে পারে। আপনার আসল খরচ Dashboard-এ।
• অন্যান্য LLM setting। কয়েকটা option (LLM_API_VERSION, LLM_DROP_PARAMS, LLM_DISABLE_VISION, LLM_CACHING_PROMPT) শুধু environment variable বা config.toml-এর entry, UI-র field নয়।
• Version বদল। OpenHands version 1.0.0-এ তার settings format বদলেছে। পুরোনো install থেকে upgrade করলে setup আবার করে নিন।

সমস্যা হলে#

404 model_not_found। model string Tokens-এ ভুল আকারে পৌঁছেছে। Custom Model-এর মান হতে হবে openai/ আর তার পরে Tokens-এর হুবহু id (openai/deepseek/deepseek-v4.1-flash)। openai/ prefix না থাকলে LiteLLM id-র প্রথম অংশকে provider-এর নাম ভেবে বসতে পারে। prefix থাকার পরেও না চললে /models থেকে নেওয়া id দিয়ে ওপরের curl চালান, id-টাই ঠিক কি না নিশ্চিত হতে।

LiteLLM বলছে provider দেওয়া নেই বা চেনা যাচ্ছে না। Custom Model-এর মানে openai/ prefix নেই। যোগ করুন।

401 missing_api_key বা invalid_api_key। API Key field বা LLM_API_KEY ফাঁকা, নয়তো অন্য provider-এর key বসে আছে। Tokens key শুরু হয় tok_live_ দিয়ে।

প্রতিটা request-এ 404। Base URL হতে হবে শুধু https://tokens.bd/v1, তার বেশি কিছু নয়। path LiteLLM নিজেই জুড়ে নেয়, তাই /chat/completions যোগ করবেন না।

CLI আমার settings মানছে না। LLM_* variable-এর সাথে --override-with-envs লাগে। ছাড়া জমানো settings-ই জেতে।

403 monthly_spend_cap_exceeded, 402 insufficient_credits বা 429 rate_limited। key-র cap, আপনার ব্যালান্স অথবা rate limit agent-কে থামিয়েছে। cap বাড়ান, নয়তো billing-এ গিয়ে টাকা যোগ করুন, কিংবা Retry-After পর্যন্ত অপেক্ষা করুন। OpenHands-এর retry loop-এর কারণে ব্যস্ত session-এ 429 আসার সম্ভাবনা বেড়ে যায়।

Web UI-র container থেকে endpoint-এ পৌঁছানো যাচ্ছে না। Tokens একটা public address, তাই সাধারণত এটা আপনার দিকের Docker network বা proxy-র সমস্যা। আগে একই machine থেকে curl চালিয়ে দেখুন।

সব code-এর জন্য Errors; অন্য সমস্যার জন্য Troubleshooting।