ద్వారా Matt Connor 2026-08-05 · అప్‌డేట్ చేయబడింది 2026-08-13

OpenTag ను VPS లో హోస్ట్ చేయడం ఎలా?

Q: OpenTag రన్ చేయడానికి VPS అవసరమా, లేక ల్యాప్టాప్ సరిపోతుందా?

Slack కోసం అయితే ల్యాప్టాప్ సరిపోతుంది, ఎందుకంటే Socket Mode ఒక outbound WebSocket ను తెరుస్తుంది మరియు దీనికి ఎటువంటి inbound port అవసరం లేదు. GitHub విషయంలో ఇది భిన్నంగా ఉంటుంది. Repository webhooks ఒక inbound HTTP ద్వారా మీరు నమోదు చేసిన URLకు వస్తాయి. కాబట్టి, ఆ చిరునామా స్థిరంగా ఉండాలి మరియు మీరు లేనప్పుడు కూడా స్పందించాలి. ఉచిత ఖాతాలోని tunnel host ప్రతి restart కు మారుతుంది, కానీ GitHub పాత చిరునామాకే పంపుతూ ఉంటుంది. దీనివల్ల repository లోని Recent Deliveries ట్యాబ్లో విఫలమైన ఎంట్రీలు కనిపిస్తాయి మరియు thread లో ఎటువంటి స్పందన ఉండదు. స్థిరమైన DNS పేరు మరియు certificate ఉన్న VPS ఈ రెండు సమస్యలను తొలగిస్తుంది.

Q: OpenTag కు ఏ GitHub అనుమతులు అవసరం?

Only select repositories కు పరిమితం చేయబడిన fine-grained personal access token ఉండాలి. దీనికి Issues: Read and write మరియు Pull requests: Read and write అనుమతులు ఉండాలి. ఇది mention ను చదవడానికి మరియు thread లో సమాధానం ఇవ్వడానికి సరిపోతుంది. మీరు preparePullRequestBranch ను true గా సెట్ చేసి OpenTag బ్రాంచ్లను push చేసేలా చేస్తే తప్ప, code కు write access అవసరం లేదు. అలాగే, code-writing token ను commenting token నుండి వేరుగా ఉంచడానికి ప్రత్యేకంగా githubApplyToken ఉంటుంది. అన్ని repositories కు వర్తించే contents write టోకెన్ను వాడకండి, ఎందుకంటే ఆ repositories లో ఎవరైనా కామెంట్ చేయగలిగితే, వారు commit చేయగల agent ను నియంత్రించే అవకాశం ఉంటుంది.

Q: తప్పుగా జరుగుతున్న run ను ఎలా ఆపాలి?

Slack లో దీని కోసం ప్రత్యేకంగా /stop కమాండ్ ఉంది. సర్వర్లో, opentag status ప్రస్తుతం ఏమి రన్ అవుతుందో చూపిస్తుంది, మరియు opentag service stop డెమన్ను ఆపివేస్తుంది; ఇది ఒక run ను మాత్రమే కాకుండా మొత్తం pipeline ను ఆపివేస్తుంది. వీటి అవసరం లేకుండా ఉండాలంటే, approvalMode ను ask గా సెట్ చేయండి, తద్వారా ఏదైనా మార్పు చేసే ముందు run ఒక వ్యక్తి కోసం వేచి ఉంటుంది. అలాగే preparePullRequestBranch ను false గా ఉంచండి, దీనివల్ల తప్పుగా జరిగిన run బ్రాంచ్ను సృష్టించకుండా కేవలం ఒక కామెంట్ను మాత్రమే ఇస్తుంది.

Slack మరియు GitHub @mentions ను మీ కోడింగ్ ఏజెంట్‌కు అనుసంధానించే OpenTag సెటప్ విధానం. TLS ingress, webhook signature, మరియు token scopes కాన్ఫిగరేషన్ కోసం ఈ గైడ్ చూడండి.

ఒక ఏజెంట్‌ను పేర్కొన్నప్పుడు OpenTag ఏమి చేస్తుంది

Slack thread లేదా GitHub issueలో మీరు చేసే @mentionను OpenTag మీ సొంత మెషీన్‌లో నడిచే కోడింగ్ ఏజెంట్‌గా మారుస్తుంది. ఎవరైనా ఒక issueపై @opentag investigate this అని కామెంట్ చేసినప్పుడు, ఒక listener ఆ ప్లాట్‌ఫారమ్ ఈవెంట్‌ను స్వీకరిస్తుంది. అది దాని signatureను తనిఖీ చేసి, ఆ mentionను దానికి అనుసంధానించబడిన ప్రాజెక్ట్‌తో సరిపోల్చుతుంది. ఆ తర్వాత, స్థానికంగా ఉన్న checkoutపై కోడింగ్ ఏజెంట్‌ను ప్రారంభించి, ఫలితాన్ని తిరిగి అదే threadలో పోస్ట్ చేస్తుంది.

ఈ ప్రాజెక్ట్ MIT లైసెన్స్‌తో amplifthq/opentagలో అందుబాటులో ఉంది. ఆగస్టు 2026 నాటికి, అత్యంత కొత్త tagged release v0.9.0, ఇది 28 జూలై 2026న విడుదల చేయబడింది మరియు ఇది npm packageగా లభిస్తుంది. దీనికి అధికారిక container image లేదు, కాబట్టి మీరు pin చేసేది npm వెర్షన్‌నే. కింద ఉన్న ప్రతి కమాండ్ దీన్ని pin చేస్తుంది.

GitHub వైపు ఉన్న అవసరాల వల్ల, ఇది ల్యాప్‌టాప్ ప్రాజెక్ట్‌గా కాకుండా VPS ప్రాజెక్ట్‌గా మారుతుంది. GitHub రిపోజిటరీ ఈవెంట్‌లను పంపడానికి మీరు ఒకసారి రిజిస్టర్ చేసిన URLకి HTTP అభ్యర్థనను పంపుతుంది, కాబట్టి ఆ URL రేపు కూడా అదే చిరునామాలో స్పందించాల్సి ఉంటుంది.

నాలుగు ప్రధాన భాగాలు

లిజనర్ (The listener) ప్లాట్‌ఫారమ్ ఈవెంట్‌లను స్వీకరిస్తుంది, ప్రతి ప్లాట్‌ఫారమ్‌కు ప్రత్యేకమైన లిజనర్ ఉంటుంది. GitHub లిజనర్ అనేది /github/webhooks పాత్‌లో 3050 పోర్ట్ వద్ద ఉండే ఒక HTTP ఎండ్‌పాయింట్. Slack Events API లిజనర్ 3040 పోర్ట్ వద్ద /slack/events లో ఉంటుంది. Slack ను Socket Mode లో కూడా రన్ చేయవచ్చు; ఈ పద్ధతిలో యాప్ ఒక అవుట్‌బౌండ్ WebSocket ను తెరుస్తుంది, దీనికి ఇన్‌బౌండ్ పోర్ట్ అవసరం ఉండదు.

డిస్పాచర్ (The dispatcher) సమన్వయకర్తగా పనిచేస్తుంది. ఇది డిఫాల్ట్‌గా 3030 పోర్ట్ వద్ద వింటుంది, OPENTAG_DATABASE_PATH ద్వారా సెట్ చేయబడిన లోకల్ డేటాబేస్ ఫైల్‌లో రన్ స్థితిని ఉంచుతుంది మరియు ప్రతి రన్ కోసం ఆడిట్ ట్రైల్‌ను రికార్డ్ చేస్తుంది. బాహ్య నెట్‌వర్క్ నుండి ఏదీ ఈ పోర్ట్‌ను చేరుకోకూడదు.

రన్నర్ (The runner) అనేది లోకల్ డెమోన్. ఇది పని కోసం పోల్ (poll) చేస్తుంది, ఒక రన్‌ను క్లెయిమ్ చేస్తుంది, దానిపై లీజును కలిగి ఉంటుంది మరియు రన్ యాక్టివ్‌గా ఉన్నంత వరకు డిఫాల్ట్‌గా ప్రతి 15 సెకన్లకు ఒక హార్ట్‌బీట్ (heartbeat) పంపుతుంది. ఒకవేళ క్లెయిమ్ చేసిన రన్ యొక్క ప్రాజెక్ట్ టార్గెట్ అందుబాటులో లేకపోయినా లేదా దాని కాన్ఫిగరేషన్‌లోని అలోలిస్ట్ (allowlist) వెలుపల ఉన్నా, రన్నర్ దానిని తిరస్కరిస్తుంది. మీరు బైండ్ చేయని రిపోజిటరీకి GitHub ఈవెంట్ మీ ఏజెంట్‌ను పాయింట్ చేయకుండా ఈ తనిఖీ నిరోధిస్తుంది.

ఎగ్జిక్యూటర్ (The executor) అనేది కోడింగ్ ఏజెంట్. OpenTag దీనిని ACP (agent client protocol) ద్వారా లాంచ్ చేస్తుంది. ఇది స్టాండర్డ్ ఇన్‌పుట్ మరియు అవుట్‌పుట్ ద్వారా జరిగే JSON-RPC ప్రోటోకాల్. OpenTag అందించే వర్కింగ్ డైరెక్టరీలో ఏజెంట్ ఒక చైల్డ్ ప్రాసెస్‌గా రన్ అవుతుంది. అంతర్నిర్మిత పేర్లలో echo, codex, claude-code, cursor, opencode, hermes మరియు openclaw ఉన్నాయి. echo తో ప్రారంభించండి; ఇది ఉదాహరణ కాన్ఫిగరేషన్‌లో ఉండే ఎగ్జిక్యూటర్. మోడల్ మీ కోడ్‌ను తాకడానికి ముందే మొత్తం పాత్ సరిగ్గా పనిచేస్తుందని ఇది నిర్ధారిస్తుంది.

ఈ క్రమం ఎప్పటికీ మారదు: ప్లాట్‌ఫారమ్ ఈవెంట్, సిగ్నేచర్ చెక్, రన్ రికార్డ్, క్లెయిమ్, ఏజెంట్, మరియు థ్రెడ్‌లో రిప్లై.

ల్యాప్‌టాప్ మరియు టన్నెల్ ఎందుకు సరిపోవు

GitHub సెటప్ గైడ్ మిమ్మల్ని ngrok http 3050 రన్ చేసి, ఆ టన్నెల్ హోస్ట్‌ను రిపోజిటరీ వెబ్‌హుక్‌లో పేస్ట్ చేయమని చెబుతుంది. ఇది మొదటి పది నిమిషాల వరకు పనిచేస్తుంది. ఉచిత టన్నెల్ హోస్ట్ ప్రతిసారి ప్రాసెస్ రీస్టార్ట్ అయినప్పుడు మారుతుంది, మరియు ల్యాప్‌టాప్ స్లీప్ మోడ్‌లోకి వెళ్ళినప్పుడు అది పనిచేయడం ఆగిపోతుంది. GitHub పాత పేలోడ్ URLనే ఉంచుకుని ప్రయత్నిస్తూనే ఉంటుంది, కాబట్టి వెబ్‌హుక్ సెట్టింగ్స్‌లోని Recent Deliveries ట్యాబ్ విఫలమైన అభ్యర్థనలతో నిండిపోతుంది, కానీ థ్రెడ్ మాత్రం నిశ్శబ్దంగా ఉంటుంది. ఒక వారం వరకు ఎవరూ దీన్ని గమనించరు, ఎందుకంటే ఏమీ చేయని వెబ్‌హుక్, ఎవరూ పట్టించుకోని బాట్ లాగే కనిపిస్తుంది.

VPS ఈ రెండు సమస్యలను పరిష్కరిస్తుంది. DNS పేరు మారదు, కాబట్టి మీరు ఒకసారి పేస్ట్ చేసిన పేలోడ్ URL అలాగే సరైనదిగా ఉంటుంది. మెషిన్ స్లీప్ మోడ్‌లోకి వెళ్ళదు, కాబట్టి 02:00 గంటలకు వచ్చే కామెంట్ కూడా వెంటనే సమాధానాన్ని అందుకుంటుంది. ముందుగా సర్వర్‌ను సరిగ్గా సెటప్ చేయండి: కొత్త VPSలో మొదటి పది నిమిషాలు గైడ్, ఈ గైడ్‌కు అవసరమైన లాగిన్ యూజర్ మరియు ఫైర్‌వాల్ సెట్టింగ్‌లను వివరిస్తుంది.

Slack దీనికి మినహాయింపు. Socket Modeలో ఇది బయటకు కనెక్ట్ అవుతుంది, కాబట్టి దీనికి పబ్లిక్ URL అవసరం లేదు; కేవలం Slack మాత్రమే వాడే డిప్లాయ్‌మెంట్ సురక్షితంగా ఉండగలదు. GitHubలో ఇలాంటి సదుపాయం లేదు. రిపోజిటరీ వెబ్‌హుక్‌లు ఇన్‌బౌండ్ HTTP అభ్యర్థనలు, అంటే వీటికి పబ్లిక్ ఎండ్‌పాయింట్ అవసరం, అంటే TLS (transport layer security) మరియు సిగ్నేచర్ చెక్ తప్పనిసరి.

Ubuntu లో pinned release నుండి OpenTag ను self-host చేయడం

OpenTag v0.9.0 కి Node.js 22 లేదా అంతకంటే కొత్త వెర్షన్ అవసరం. Ubuntu 24.04 దాని స్వంత రిపోజిటరీలో Node 18ని కలిగి ఉంటుంది, కాబట్టి NodeSource నుండి ఇన్‌స్టాల్ చేయండి.

curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install -y nodejs
node -v

node -v కమాండ్ v22 లేదా అంతకంటే ఎక్కువ వెర్షన్‌ను చూపాలి. Node 20లో ఇన్‌స్టాల్ చేసినప్పుడు EBADENGINE హెచ్చరిక వస్తుంది మరియు CLI ప్రారంభమైన తర్వాత విఫలం కావచ్చు.

ఈ సేవకు ప్రత్యేకమైన ఖాతాను కేటాయించండి. ఏజెంట్ ఈ యూజర్ అనుమతులతో నడుస్తుంది, కాబట్టి ఇది మీ లాగిన్ యూజర్ కాకూడదు మరియు root కూడా కాకూడదు. VPS పై కనీస అధికారాలు కలిగిన యూజర్లు అనే విభాగం ఈ విభజన ఎందుకు ముఖ్యమో వివరిస్తుంది.

sudo adduser --disabled-password --gecos "" opentag
sudo loginctl enable-linger opentag
sudo npm install -g @opentag/cli@0.9.0
command -v opentag

command -v opentag కమాండ్ /usr/bin/opentag వంటి పాత్‌ను చూపాలి. Linux లో linger సెట్టింగ్ ముఖ్యం: OpenTag తన బ్యాక్‌గ్రౌండ్ సేవను systemd ద్వారా ఇన్‌స్టాల్ చేస్తుంది, linger లేని యూజర్ సర్వీస్ మీ SSH సెషన్ ముగియగానే ఆగిపోతుంది.

ఆ యూజర్‌గా సెటప్‌ను రన్ చేయండి.

sudo -iu opentag opentag setup

సెటప్ ఆరు విషయాలను అడుగుతుంది: CLI భాష, లోకల్ లిజనింగ్ అడ్రస్, కోడింగ్ ఏజెంట్, పని చేయాల్సిన లోకల్ ప్రాజెక్ట్, సేవ్ చేయాల్సిన ప్లాట్‌ఫారమ్ క్రెడెన్షియల్స్ మరియు రన్ చేయాల్సిన విధానం. లిజనింగ్ అడ్రస్‌ను 127.0.0.1 వద్దే ఉంచండి, ఎందుకంటే nginx TLS ను టెర్మినేట్ చేసి దీనికి ఫార్వర్డ్ చేస్తుంది, కాబట్టి లిజనర్లు బయటి నుండి అందుబాటులో ఉండాల్సిన అవసరం లేదు. GitHub కోసం ఇది owner/repo ఫార్మాట్‌లో రిపోజిటరీని, pull requests ఓపెన్ చేయవచ్చా లేదా అని, వెబ్‌హుక్ పోర్ట్ (డిఫాల్ట్‌గా 3050) మరియు టోకెన్‌ను అడుగుతుంది. చివరగా బ్యాక్‌గ్రౌండ్ సర్వీస్ మోడ్‌ను ఎంచుకోండి. మీ దగ్గర ఇప్పటికే కాన్ఫిగరేషన్ ఉండి, ప్రాంప్ట్‌లు లేకుండా సర్వీస్ ఇన్‌స్టాల్ చేయాలనుకుంటే, opentag setup --service కమాండ్ ఉపయోగించండి.

కాన్ఫిగరేషన్ /home/opentag/.config/opentag/config.json లో మరియు రన్‌టైమ్ స్టేట్ /home/opentag/.local/state/opentag లో సేవ్ అవుతాయి. సెటప్ ఫైల్‌ను రాసిన తర్వాత ఈ కీలను మాన్యువల్‌గా తనిఖీ చేయడం మంచిది.

{
  "runnerId": "runner_local",
  "dispatcherUrl": "http://localhost:3030",
  "runnerToken": "...",
  "approvalMode": "ask",
  "repositories": []
}

పాత షేర్డ్ pairingToken కంటే, రన్నర్-స్కోప్డ్ బేరర్ టోకెన్ అయిన runnerToken ని ఉపయోగించండి. మీరు క్రెడెన్షియల్స్‌ను సీక్రెట్ రిఫరెన్స్‌తో భర్తీ చేయకపోతే, కాన్ఫిగరేషన్ ఫైల్ వాటిని ప్లెయిన్ టెక్స్ట్‌గా ఉంచుతుంది; సీక్రెట్ రిఫరెన్స్ స్టార్టప్ సమయంలో ఎన్విరాన్‌మెంట్ నుండి లేదా డిస్క్‌లోని ఫైల్ నుండి విలువను చదువుతుంది. ఏది ఏమైనా, ఈ ఫైల్ సర్వర్‌లో అత్యంత సున్నితమైనది: దీనికి 600 మోడ్ ఉండాలి, opentag యాజమాన్యంలో ఉండాలి మరియు ఎట్టి పరిస్థితుల్లోనూ git రిపోజిటరీలో ఉండకూడదు. దీనికి సంబంధించిన పూర్తి వివరణ AI ఏజెంట్ల నుండి రహస్యాలను దూరంగా ఉంచడం లో ఉంది.

ఏదైనా ఎక్స్‌పోజ్ చేసే ముందు ఇన్‌స్టాలేషన్‌ను తనిఖీ చేయండి.

sudo -iu opentag opentag doctor
sudo -iu opentag opentag status

opentag doctor కమాండ్ డిస్పాచర్, బైండింగ్స్, చెకౌట్స్ మరియు ఎగ్జిక్యూటర్లను తనిఖీ చేస్తుంది. opentag status కాన్ఫిగరేషన్ మరియు రన్‌టైమ్ స్టేట్‌ను ప్రింట్ చేస్తుంది, రన్స్ ఉన్నప్పుడు ఇది ఒకే రన్‌కు పరిమితం చేయవచ్చు. మీరు ఈ బాక్స్‌ను ప్లాట్‌ఫారమ్‌కు అనుసంధానించే ముందు doctor రిపోర్ట్ చేసే అన్ని సమస్యలను పరిష్కరించండి.

TLS ను ముందు ఉంచి కేవలం రెండు మార్గాలను మాత్రమే తెరవండి

Nginx TLS ను terminate చేసి, ఖచ్చితంగా రెండు మార్గాలను మాత్రమే forward చేస్తుంది. మిగిలినవన్నీ 404 error ను ఇస్తాయి, కాబట్టి వెనుక ఏ సేవలు నడుస్తున్నాయో స్కాన్ చేసే వారికి ఏమీ తెలియదు.

/etc/nginx/sites-available/opentag వద్ద ఒక సాధారణ port 80 server block ను రాయండి, అందులో కింద పేర్కొన్న రెండు locations ఉండాలి. ఆ తర్వాత Certbot ను ఉపయోగించి TLS ను జోడించండి.

sudo apt install -y nginx certbot python3-certbot-nginx
sudo ln -s /etc/nginx/sites-available/opentag /etc/nginx/sites-enabled/opentag
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d opentag.example.com

nginx -t కమాండ్ syntax is ok మరియు test is successful లను ప్రింట్ చేస్తుంది. టైపింగ్ పొరపాట్లు జరిగి సైట్ డౌన్ అవ్వకుండా ఇది రక్షణగా ఉంటుంది. Ubuntu 24.04 లో nginx తో Certbot అనే విభాగం certificate renewal గురించి మరియు ACME (automatic certificate management environment) challenge ఎందుకు విఫలమవుతుందో వివరిస్తుంది. పూర్తయిన block ఇలా కనిపిస్తుంది.

server {
    listen 443 ssl;
    server_name opentag.example.com;

    ssl_certificate     /etc/letsencrypt/live/opentag.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/opentag.example.com/privkey.pem;

    client_max_body_size 2m;

    location = /github/webhooks {
        proxy_pass http://127.0.0.1:3050;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }

    location = /slack/events {
        proxy_pass http://127.0.0.1:3040;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }

    location / {
        return 404;
    }
}

location = /github/webhooks లోని = ఖచ్చితమైన match కోసం, మరియు పోర్ట్ తర్వాత ఏమీ లేని proxy_pass అసలు URI ని మార్చకుండా పంపుతుంది. = ను తొలగిస్తే /github/webhooks/ కింద ఉన్న ప్రతి మార్గం forward అవుతుంది, ఇది అవసరమైన దానికంటే ఎక్కువ attack surface ను సృష్టిస్తుంది.

Firewall నిబంధనలు కఠినంగా ఉండాలి.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status

Port 3030, 3040 మరియు 3050 లను ఎప్పుడూ తెరవకండి. ఇవి అన్ని interface లపై కాకుండా, కేవలం loopback పై మాత్రమే bound అయ్యాయని నిర్ధారించుకోండి.

sudo ss -tlnp

ప్రతి OpenTag లైన్ 127.0.0.1:3030 లేదా దానిని పోలి ఉండాలి. ఒక లైన్ 0.0.0.0:3050 అని ఉంటే, ఆ listener మొత్తం ఇంటర్నెట్‌కు అందుబాటులో ఉందని అర్థం. కేవలం ufw మాత్రమే దానిని ఆపుతోంది, కాబట్టి firewall లో చిన్న పొరపాటు జరిగినా అది ప్రమాదకరం. ufw firewall ప్రాథమికాంశాలు అనే విభాగం default deny ఎలా పనిచేస్తుందో వివరిస్తుంది.

రెండు పరీక్షలు ప్రధాన ద్వారం భద్రతను నిరూపిస్తాయి. curl -I https://opentag.example.com/ కమాండ్ nginx నుండి 404 ను తిరిగి ఇస్తుంది, ఇది certificate చెల్లుబాటు అవుతుందని మరియు catch-all మూసివేయబడిందని చూపిస్తుంది. ఎటువంటి signature లేని /slack/events లేదా /github/webhooks అభ్యర్థనలు ఎప్పుడూ 200 status code ను ఇవ్వకూడదు.

ప్రతి సంతకాన్ని ధృవీకరించండి, ఎందుకంటే URL పబ్లిక్‌గా ఉంటుంది

ఎవరైనా సరే payload URLను కనుగొనగలరు. ఇది మీ రిపోజిటరీ సెట్టింగ్‌లలో, బ్రౌజర్ హిస్టరీలో, లేదా టికెట్‌లో పేస్ట్ చేసిన స్క్రీన్‌షాట్‌లో ఉంటుంది. GitHub పంపిన అసలైన డెలివరీకి మరియు ఎవరైనా స్వయంగా టైప్ చేసిన అభ్యర్థనకు మధ్య ఉన్న ఏకైక వ్యత్యాసం ఈ సంతకం మాత్రమే.

GitHub ప్రతి డెలివరీని webhook secret తో సంతకం చేసి, ఆ ఫలితాన్ని x-hub-signature-256 హెడర్‌లో పంపుతుంది. OpenTag ఆ హెడర్‌ను platforms.github.webhookSecret తో సరిపోల్చి ధృవీకరిస్తుంది. ప్రాజెక్ట్ యొక్క హార్డెనింగ్ నోట్స్ ఈ నియమాన్ని నేరుగా చెబుతున్నాయి: /github/webhooks పై సంతకం లేని సోర్స్ ఈవెంట్‌లను అంగీకరించవద్దు. Slack ప్రతి అభ్యర్థనను SLACK_SIGNING_SECRET తో సంతకం చేసి, ఒక టైమ్‌స్టాంప్‌ను జత చేస్తుంది, తద్వారా పట్టుబడిన బాడీని గంటల తర్వాత మళ్ళీ రీప్లే (replay) చేయడం సాధ్యం కాదు.

దీనిని విస్మరించడం చిన్న ప్రమాదం కాదు. ధృవీకరించని ఎండ్‌పాయింట్, @opentag కలిగిన ఒక హ్యాండ్-రిటన్ issue_comment పేలోడ్‌ను అంగీకరిస్తుంది, అప్పుడు OpenTag మీ టోకెన్‌తో, మీ చెకౌట్‌లో, అపరిచితుడి సూచనల మేరకు ఒక కోడింగ్ ఏజెంట్‌ను రన్ చేస్తుంది. ఆ సమాధానం నకిలీ పేలోడ్ పేర్కొన్న ఏదైనా థ్రెడ్‌కు వెళ్తుంది.

OpenTag దీనిపై అదనంగా రెండు పొరలను జోడిస్తుంది. సోర్స్ డెలివరీలు డెలివరీ ID ద్వారా ట్రాక్ చేయబడతాయి, కాబట్టి ఒకే ఈవెంట్‌ను మళ్ళీ డెలివరీ చేసినా రెండోసారి రన్ ప్రారంభం కాదు. రన్నర్ కాల్‌లు ఐడెంపోటెన్సీ కీలను (idempotency keys) అంగీకరిస్తాయి, కాబట్టి ఒకదాన్ని రీప్లే చేసినా, మరొక ఆడిట్ ఈవెంట్‌ను జోడించకుండానే సక్సెస్ అని తిరిగి వస్తుంది.

రేట్ లిమిట్‌లు కాన్ఫిగర్ చేయదగినవి మరియు వాటిని తప్పనిసరిగా ఆన్ చేయాలి. OPENTAG_RATE_LIMIT_WINDOW_MS మరియు OPENTAG_RATE_LIMIT_MAX_REQUESTS అభ్యర్థన రేటును నియంత్రిస్తాయి, OPENTAG_MAX_REQUEST_BODY_BYTES బాడీ పరిమాణాన్ని నియంత్రిస్తుంది, మరియు పరిమితికి మించిన పేలోడ్ 413 request_body_too_large తో తిరస్కరించబడుతుంది. OPENTAG_RATE_LIMIT_DISABLED=true స్థానిక డెవలప్‌మెంట్ కోసం మాత్రమే, పబ్లిక్ బాక్స్‌పై దీనికి చోటు లేదు. అదే నోట్స్ నుండి మరొక నియమం: పబ్లిక్ రిలే URL తప్పనిసరిగా HTTPSని ఉపయోగించాలి, మరియు CLI కేవలం localhost కోసం మాత్రమే plain HTTPని అనుమతిస్తుంది.

బోట్‌కు వాస్తవానికి ఏ టోకెన్ స్కోప్‌లు అవసరం?

GitHubలో, OpenTag అనేది GitHub Appకు బదులుగా fine-grained personal access tokenను ఉపయోగిస్తుంది. App మార్గం ప్రణాళికలో ఉందని, ప్రస్తుత CLI సెటప్‌లో ఇది డిఫాల్ట్ కాదని డాక్యుమెంటేషన్ చెబుతోంది. దీనివల్ల ఒక ముఖ్యమైన పరిణామం ఉంది: టోకెన్‌ను సృష్టించిన వ్యక్తి పేరుతోనే బోట్ కామెంట్ చేస్తుంది. ప్రతి triage సమాధానంలో ఏ ఖాతా పేరు కనిపించినా మీకు ఇబ్బంది లేదో, ఆ ఖాతా కిందనే దీనిని సృష్టించండి.

సెటప్ గైడ్‌లో సూచించిన విధంగానే స్కోప్‌ను పరిమితం చేయండి. Only select repositories ఎంచుకుని, ఒక రిపోజిటరీని ఎంచుకోండి. Issues: Read and write మరియు Pull requests: Read and write అనుమతులను ఇవ్వండి. ఒక మెన్షన్‌ను చదవడానికి మరియు థ్రెడ్‌లో సమాధానం ఇవ్వడానికి ఇది సరిపోతుంది.

ఏమి లేదో గమనించండి: కోడ్‌కు write access లేదు. preparePullRequestBranch అనేది true అని సెట్ చేయకపోతే OpenTag బ్రాంచ్‌లను పుష్ చేయదు. అలాగే, కోడ్‌ను రాసే టోకెన్ మరియు కామెంట్లను రాసే టోకెన్ వేర్వేరుగా ఉండటానికి githubApplyToken అందుబాటులో ఉంది. వీటిని వేరుగా ఉంచండి. read-and-comment ప్రక్రియ కొన్ని వారాల పాటు సజావుగా సాగే వరకు write టోకెన్‌ను ఉపయోగించకండి.

All repositories అంతటా Contents: Read and write ఉన్న టోకెన్‌ను ఉపయోగించడం ప్రమాదకరం. అటువంటి రిపోజిటరీలలో కామెంట్ చేయగల ఎవరైనా, commit హక్కులు ఉన్న ఏజెంట్‌ను నియంత్రించగలరు. ఆడిట్ ట్రైల్‌లో టోకెన్ యజమాని చేసినట్లుగానే కనిపిస్తుంది. ఏజెంట్ విశ్వసనీయతను నిరూపించుకున్న తర్వాత, ఒక్కో రిపోజిటరీకి స్కోప్‌ను పెంచుకుంటూ వెళ్లండి.

Slackలో బోట్ స్కోప్‌లు app_mentions:read, chat:write, reactions:write మరియు channels:history. ప్రైవేట్ ఛానెల్‌లకు groups:history మరియు message.groups ఈవెంట్‌కు సబ్‌స్క్రిప్షన్ కూడా అవసరం. Socket Mode కోసం connections:write ఉన్న app-level టోకెన్ అవసరం, ఇది xapp- తో ప్రారంభమవుతుంది. channels:history అనేది బోట్‌ను చేర్చిన పబ్లిక్ ఛానెల్‌లలో మెసేజ్ హిస్టరీని చదువుతుంది, కాబట్టి బోట్‌ను అన్ని చోట్లా కాకుండా, అవసరమైన ఛానెల్‌లలో మాత్రమే చేర్చండి.

ఒక issue ను end-to-end రూట్ చేయడం

ముందుగా webhook ను సెటప్ చేయాలి. రిపోజిటరీలో Settings ఓపెన్ చేసి, Webhooks కు వెళ్లి, Add webhook క్లిక్ చేయండి. Payload URL గా https://opentag.example.com/github/webhooks, content type గా application/json ఇవ్వండి, మరియు సెటప్ సమయంలో జనరేట్ అయిన secret ను ఎంటర్ చేయండి. Issue comments మరియు Pull request review comments లకు మాత్రమే సబ్‌స్క్రయిబ్ అవ్వండి, వేరే దేనికీ వద్దు.

మీరు సేవ్ చేసిన వెంటనే GitHub ఒక ping delivery ని పంపుతుంది. Recent Deliveries ఓపెన్ చేసి, అభ్యర్థన సర్వర్‌కు చేరిందో లేదో తనిఖీ చేయండి. అక్కడ 502 error కనిపిస్తే, అది listener ను చేరుకోలేకపోయానని nginx చెబుతున్నట్లు అర్థం; ఇది GitHub సమస్య కాదు, మీ లోకల్ సమస్య.

ఇప్పుడు దీన్ని ఉపయోగించండి. ఒక బగ్‌ను వివరించే issue ను ఓపెన్ చేసి ఇలా కామెంట్ చేయండి:

@opentag triage this. Reproduce the report against the current main branch, then reply with the file and function most likely responsible, plus the test you would write first.

ఏమి జరగాలి, వరుసగా చూద్దాం. Recent Deliveries లో issue_comment డెలివరీ 2xx రెస్పాన్స్‌తో రికార్డ్ అవుతుంది. డిస్పాచర్ ఒక రన్‌ను రికార్డ్ చేస్తుంది. రన్నర్ దాన్ని క్లెయిమ్ చేసి heartbeating ప్రారంభిస్తుంది. ఎగ్జిక్యూటర్ చెకౌట్‌ను ఓపెన్ చేసి పని మొదలుపెడుతుంది. సమాధానం అదే issue థ్రెడ్‌లో కామెంట్‌గా వస్తుంది. sudo -iu opentag opentag status రన్ జరుగుతున్నప్పుడు దాన్ని చూపిస్తుంది, కాబట్టి మీరు ఊహించాల్సిన అవసరం లేకుండా నేరుగా పర్యవేక్షించవచ్చు.

మొదటి నిజమైన రన్‌కు ముందు approvalMode ను ask కి సెట్ చేయండి. ask మోడ్‌లో, రన్ ఏదైనా స్టేట్ మార్పు చేసే ముందు ఆగిపోయి మనిషి కోసం వేచి ఉంటుంది. auto మరియు autonomous మోడ్‌లు కూడా ఉన్నాయి, మీరు ఒక నెల రోజుల ట్రాన్స్‌క్రిప్ట్‌లను చదివిన తర్వాత, రిపోజిటరీపై వీటిని ఉపయోగించడం సమంజసంగా ఉంటుంది.

Slack వైపు, అదే రన్ ఛానెల్‌లో /bind owner/repo తో మొదలై, ఆపై ఒక మెన్షన్ వస్తుంది. బాట్ /help, /status, /doctor, /stop మరియు /unbind confirm లకు కూడా సమాధానం ఇస్తుంది. బైండింగ్స్‌ను ఎవరు మార్చవచ్చో OPENTAG_SLACK_BINDING_ADMIN_USER_IDS ద్వారా నియంత్రించండి; ఇది Slack యూజర్ IDల కామా-సెపరేటెడ్ జాబితా. ఎందుకంటే బైండింగ్ అనేది పబ్లిక్ ఛానెల్ నుండి మీ సర్వర్‌లోని చెకౌట్‌కు ఉండే మ్యాపింగ్.

Triage అనేది మొదటి మంచి మార్గం, ఎందుకంటే ఇది కేవలం చదువుతుంది, ఏమీ రాయదు, మరియు సమాధానాన్ని అంచనా వేయడం సులభం. తదుపరి దశ Review, ఇక్కడ ఏజెంట్ issue కి బదులుగా diff పై కామెంట్ చేస్తుంది: a self-hosted pull request review agent అనేది pull requests కోసం ఇదే ఆర్కిటెక్చర్‌ను ఉపయోగిస్తుంది. ఏజెంట్ పనిచేస్తున్నప్పుడు మీ స్వంత సిస్టమ్‌లను చేరుకోవాలని మీరు కోరుకుంటే, అది MCP servers on a VPS పని. Web search అనేది triage అడిగే మరొక సామర్థ్యం, మరియు wiring the agent to your own SearXNG instance ద్వారా ఆ సెర్చ్‌లను మీరు రన్ చేసే హార్డ్‌వేర్‌లోనే ఉంచుకోవచ్చు, అయితే దీనివల్ల అపరిచితుల టెక్స్ట్ ఏజెంట్‌కు చేరే మరొక ఛానెల్ పెరుగుతుంది.

అందరి ముందు ఏజెంట్ తప్పుగా సమాధానం ఇస్తే ఏమవుతుంది?

అది తప్పుగా ఉంటుంది. అసలు ప్రశ్న ఏమిటంటే, దాని వల్ల కలిగే నష్టం ఎంత అనేది.

ప్రజాక్షేత్రంలో ఉన్న ఒక issue పై తప్పు సమాధానం ఇస్తే, అది మీ బృందానికి తెలిసిన పేరుతో వచ్చే వ్యాఖ్య అవుతుంది. అది పోస్ట్ అయిన వెంటనే GitHub దానికి సబ్‌స్క్రైబ్ అయిన ప్రతి ఒక్కరికీ ఈమెయిల్ పంపుతుంది. వ్యాఖ్యను తొలగించినంత మాత్రాన ఆ ఈమెయిల్ వెనక్కి రాదు. Slack నోటిఫికేషన్ విషయంలో కూడా ఇదే వర్తిస్తుంది. సమాధానం ప్రైవేట్‌గా సరైనదిగా ఉండటం కంటే, బహిరంగంగా తప్పుగా ఉండవచ్చని ముందుగానే ఊహించి ప్రణాళిక సిద్ధం చేసుకోండి.

నష్టాన్ని తగ్గించే నాలుగు మార్గాలు ఉన్నాయి, మీరు రాసే ఏ prompt కంటే ఇవే ముఖ్యమైనవి.

ask మోడ్‌లో రన్ చేయండి. దీనివల్ల ఏజెంట్ ఒక ప్రతిపాదనను ఇస్తుంది, ఒక వ్యక్తి దానిని ఆమోదిస్తారు. తద్వారా తప్పుడు ప్రణాళిక వల్ల కేవలం ఒక క్లిక్ నష్టం మాత్రమే జరుగుతుంది.
preparePullRequestBranch ను దాని డిఫాల్ట్ విలువ అయిన false వద్దే ఉంచండి. దీనివల్ల ఒక తప్పుడు రన్ జరిగినప్పుడు, తప్పుడు బ్రాంచ్ క్రియేట్ అవ్వడానికి బదులుగా కేవలం ఒక తప్పుడు వ్యాఖ్య మాత్రమే వస్తుంది.
ప్రారంభంలో ఒక repository మరియు ఒక channel ను మాత్రమే అనుసంధానించండి. runner తన local allowlist లో లేని ప్రాజెక్ట్ లక్ష్యానికి సంబంధించిన ఏ రన్‌నైనా తిరస్కరిస్తుంది, కాబట్టి అనుసంధానించని repository ఏజెంట్‌ను తనలోకి లాక్కోలేదు.
వ్యాఖ్యలు చేసే token ను, apply చేసే token నుండి వేరుగా ఉంచండి. దీనివల్ల write access ను రద్దు చేసినా, triage ప్రక్రియ ఆగిపోదు.

తప్పుగా జరుగుతున్న రన్‌ను ఆపడానికి Slack లో /stop కమాండ్ ఉంది. ప్రతి రన్ కూడా ఒక audit record ను వదిలివేస్తుంది. అందులో దేనివల్ల ఆ రన్ మొదలైంది, ఏజెంట్ ఏమి చేసింది అనే వివరాలు ఉంటాయి. రన్ ఎక్కడ తప్పు జరిగిందో తెలుసుకోవడానికి మీరు తర్వాత వీటిని చదవవచ్చు.

సాంకేతికతతో పాటు సామాజిక కోణం కూడా అంతే ముఖ్యం. బాట్‌ను ఒకే channel లో ఉంచండి, అక్కడ ప్రజలు అది ఒక యంత్రమని, అది తప్పు చేయగలదని ముందుగానే ఊహిస్తారు. నలభై మంది ఉన్న channel లో, ఒక మనిషి సమీక్షించాడని భావించే చోట, ఆత్మవిశ్వాసంతో కూడిన తప్పుడు సమాధానం ఇస్తే, అది triage ద్వారా ఆదా చేసిన సమయం కంటే ఎక్కువ నష్టాన్ని కలిగిస్తుంది. బాట్‌కు యజమాని ఎవరు, దాని అవుట్‌పుట్‌ను ఎవరు తనిఖీ చేస్తారో channel వివరణలో స్పష్టంగా రాయండి.

బ్యాకప్‌లు, అప్‌గ్రేడ్‌లు మరియు పిన్ చేయడం

ప్రతిదీ రెండు పాత్‌లలో ఉంటుంది: /home/opentag/.config/opentag/config.json మరియు /home/opentag/.local/state/opentag. మొదటి దానిలో మీ క్రెడెన్షియల్స్ ఉంటాయి, రెండవ దానిలో రన్ హిస్టరీ మరియు డేటాబేస్ ఫైల్ ఉంటాయి. రెండింటినీ 600 మోడ్‌తో బ్యాకప్ తీసి, సర్వర్ వెలుపల భద్రపరచండి. వీటిని కోల్పోతే టోకెన్లు మరియు బైండింగ్‌లను మళ్లీ సృష్టించాల్సి ఉంటుంది, సర్వర్‌ను పూర్తిగా రీబిల్డ్ చేయాల్సిన అవసరం లేదు.

అప్‌గ్రేడ్‌లు అంటే వెర్షన్ మార్పు మరియు రీస్టార్ట్ మాత్రమే.

sudo npm install -g @opentag/cli@0.9.0
sudo -iu opentag opentag service stop
sudo -iu opentag opentag service start
sudo -iu opentag opentag doctor

@latestని ట్రాక్ చేయడానికి బదులుగా వెర్షన్‌ను పిన్ చేయండి. ఈ సాఫ్ట్‌వేర్ మీ రిపోజిటరీపై లైవ్ టోకెన్‌తో కోడింగ్ ఏజెంట్‌ను రన్ చేస్తుంది, కాబట్టి రాత్రికి రాత్రే విడుదలయ్యే కొత్త వెర్షన్ మీరు సమీక్షించని మార్పులను కలిగి ఉండవచ్చు. సెక్యూరిటీ పాలసీ పాత వెర్షన్లకు ఎటువంటి అప్‌డేట్‌లను అందించదు, కేవలం కొత్త వెర్షన్‌లోనే పరిష్కారాలు అందుబాటులో ఉంటాయి. కాబట్టి పిన్ చేయడం అంటే మీరు చేంజ్‌లాగ్‌ను చదివి, ఉద్దేశపూర్వకంగా అప్‌డేట్ చేయడం అని అర్థం. దీని అర్థం ఎప్పటికీ v0.9.0 వెర్షన్‌లోనే ఉండాలని కాదు. జూలై 2026 వరకు ఉన్న చరిత్రను చూస్తే, నెలకు అనేక విడుదలలు వస్తున్నాయి. కాబట్టి ప్రతి అప్‌డేట్‌కు ముందు రిలీజ్ నోట్స్‌ను చదవడం చాలా ముఖ్యం.

FAQ

OpenTag రన్ చేయడానికి VPS అవసరమా, లేక ల్యాప్‌టాప్ సరిపోతుందా?

Slack కోసం అయితే ల్యాప్‌టాప్ సరిపోతుంది, ఎందుకంటే Socket Mode ఒక outbound WebSocket ను తెరుస్తుంది మరియు దీనికి ఎటువంటి inbound port అవసరం లేదు. GitHub విషయంలో ఇది భిన్నంగా ఉంటుంది. Repository webhooks ఒక inbound HTTP ద్వారా మీరు నమోదు చేసిన URLకు వస్తాయి. కాబట్టి, ఆ చిరునామా స్థిరంగా ఉండాలి మరియు మీరు లేనప్పుడు కూడా స్పందించాలి. ఉచిత ఖాతాలోని tunnel host ప్రతి restart కు మారుతుంది, కానీ GitHub పాత చిరునామాకే పంపుతూ ఉంటుంది. దీనివల్ల repository లోని Recent Deliveries ట్యాబ్‌లో విఫలమైన ఎంట్రీలు కనిపిస్తాయి మరియు thread లో ఎటువంటి స్పందన ఉండదు. స్థిరమైన DNS పేరు మరియు certificate ఉన్న VPS ఈ రెండు సమస్యలను తొలగిస్తుంది.

OpenTag కు ఏ GitHub అనుమతులు అవసరం?

Only select repositories కు పరిమితం చేయబడిన fine-grained personal access token ఉండాలి. దీనికి Issues: Read and write మరియు Pull requests: Read and write అనుమతులు ఉండాలి. ఇది mention ను చదవడానికి మరియు thread లో సమాధానం ఇవ్వడానికి సరిపోతుంది. మీరు preparePullRequestBranch ను true గా సెట్ చేసి OpenTag బ్రాంచ్‌లను push చేసేలా చేస్తే తప్ప, code కు write access అవసరం లేదు. అలాగే, code-writing token ను commenting token నుండి వేరుగా ఉంచడానికి ప్రత్యేకంగా githubApplyToken ఉంటుంది. అన్ని repositories కు వర్తించే contents write టోకెన్‌ను వాడకండి, ఎందుకంటే ఆ repositories లో ఎవరైనా కామెంట్ చేయగలిగితే, వారు commit చేయగల agent ను నియంత్రించే అవకాశం ఉంటుంది.

తప్పుగా జరుగుతున్న run ను ఎలా ఆపాలి?

Slack లో దీని కోసం ప్రత్యేకంగా /stop కమాండ్ ఉంది. సర్వర్‌లో, opentag status ప్రస్తుతం ఏమి రన్ అవుతుందో చూపిస్తుంది, మరియు opentag service stop డెమన్‌ను ఆపివేస్తుంది; ఇది ఒక run ను మాత్రమే కాకుండా మొత్తం pipeline ను ఆపివేస్తుంది. వీటి అవసరం లేకుండా ఉండాలంటే, approvalMode ను ask గా సెట్ చేయండి, తద్వారా ఏదైనా మార్పు చేసే ముందు run ఒక వ్యక్తి కోసం వేచి ఉంటుంది. అలాగే preparePullRequestBranch ను false గా ఉంచండి, దీనివల్ల తప్పుగా జరిగిన run బ్రాంచ్‌ను సృష్టించకుండా కేవలం ఒక కామెంట్‌ను మాత్రమే ఇస్తుంది.

thread నిశ్శబ్దంగా ఉన్నప్పుడు నా webhook ఎందుకు 502 ఎర్రర్‌ను ఇస్తుంది?

502 ఎర్రర్ OpenTag నుండి కాకుండా nginx నుండి వస్తుంది, అంటే proxy ఆ listener ను చేరుకోలేకపోతోందని అర్థం. /var/log/nginx/error.log ద్వారా connect() failed (111: Connection refused) while connecting to upstream కనిపిస్తుంది. listener ఆగిపోయి ఉండవచ్చు, లేదా అది proxy_pass లైన్‌లో పేర్కొన్న దానికంటే భిన్నమైన port లో ఉండవచ్చు. sudo ss -tlnp రన్ చేసి, GitHub కోసం 127.0.0.1:3050 మరియు Slack కోసం 127.0.0.1:3040 లో ఏదైనా service వింటుందో లేదో నిర్ధారించుకోండి. ఆ తర్వాత bindings మరియు executors కోసం opentag doctor రన్ చేయండి.

#opentag#ai-agents#slack#github#webhooks#self-hosting