# OpenHands

> OpenHands-কে Tokens-এর সাথে OpenAI-compatible endpoint হিসেবে জুড়ুন, web UI বা CLI-তে, আর যেসব model id-তে আগে থেকেই slash আছে তার জন্য ঠিক model string-টা দিন।

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 ধাঁচে।

:::note[Documentation দেখে যাচাই করা]
docs.openhands.dev-এর OpenHands documentation (OpenAI, local LLM, LLM overview আর CLI পাতা) দেখে লেখা, October 2026-এ যাচাই করা। ওই পাতাগুলোতে CLI-র কোনো version লেখা নেই; আমরা যে install পাতা পড়েছি সেখানে agent server image পিন করা `1.26.0-python`-এ। OpenHands-কে Tokens-এর সাথে শুরু থেকে শেষ পর্যন্ত চালিয়ে আমরা দেখিনি।
:::

## যা যা লাগবে

- একটা Tokens key। শুধু OpenHands-এর জন্য আলাদা key বানান, মাসিক spend cap দিয়ে ([API keys](/docs/api-keys))।
- [/models](/models) থেকে model id। উদাহরণগুলোতে `deepseek/deepseek-v4.1-flash` ব্যবহার করা হয়েছে।
- OpenHands install করা। CLI আর local web UI, দুটোতেই Python 3.12 আর [uv](https://docs.astral.sh/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 থাকবে দুটো:

```text
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 চালু করুন:

```bash
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 ব্যবহার করুন:

```bash
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
```

:::warning[Flag ছাড়া environment variable ধরা হয় না]
`--override-with-envs` দিয়ে CLI চালু না করলে OpenHands `LLM_*` variable-গুলো পাত্তাই দেয় না। আর এই override save হয় না: পরের দিন শুধু `openhands` চালালে `~/.openhands/`-এ যা জমানো আছে, সেটাই ফিরে আসে। প্রতিবার Tokens ব্যবহার করলে ওই চার লাইন একটা ছোট shell script বা alias-এ রেখে দিন।
:::

পরে জমানো 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 ছাড়া):

```bash
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](/docs/choosing-a-model)-এ, আর [/models](/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](/docs/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](/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](/dashboard/billing)-এ গিয়ে টাকা যোগ করুন, কিংবা `Retry-After` পর্যন্ত অপেক্ষা করুন। OpenHands-এর retry loop-এর কারণে ব্যস্ত session-এ 429 আসার সম্ভাবনা বেড়ে যায়।

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

সব code-এর জন্য [Errors](/docs/errors); অন্য সমস্যার জন্য [Troubleshooting](/docs/troubleshooting)।

---
Page: https://tokens.bd/bn/docs/openhands