OpenCode 2 permissions: V1 से माइग्रेट करें और बाहरी एक्सेस की पुष्टि बहाल करें

OpenCode 2 में अपग्रेड करने के बाद बाहरी डायरेक्टरी के लिए पुष्टि वापस लाने हेतु external_directory नियम में effect: "ask" सेट करें। 2026-10-31 की स्थिति के अनुसार, आधिकारिक माइग्रेशन गाइड V2 का डिफ़ॉल्ट allow बताती है, जबकि V1 में यह ask था। समर्थित V1 कॉन्फ़िगरेशन तब तक बनाए रखें, जब तक आप उसके नियमों को V2 के क्रमबद्ध permissions array में बदलने के लिए तैयार न हों।

इस गाइड में इंटरैक्टिव कोडिंग के लिए एक बेसलाइन कॉन्फ़िगरेशन और OpenCode v2.2.0 पर आधारित जाँच प्रक्रिया दी गई है। अपेक्षित नतीजे दस्तावेज़ों और उस संस्करण के टैग वाले स्रोत कोड पर आधारित हैं, किसी चल रहे इंस्टॉलेशन के टेस्ट पर नहीं।

कोई नियम न मिलने पर ask लागू होता है, तो V2 बाहरी paths की अनुमति क्यों देता है?

नियमों का मिलान करते समय OpenCode अपने अंतर्निहित नियम भी देखता है। इसलिए आपका कोई नियम न होना, किसी भी नियम का मेल न मिलने के बराबर नहीं है।

आधिकारिक V2 Defaults अनुभाग के अनुसार, हर एजेंट के नियम एक सामान्य wildcard अनुमति से शुरू होते हैं। इस नियम में action: "*", resource: "*" और effect: "allow" होते हैं। इसके बाद के बेस नियम *.env और *.env.* पढ़ने से पहले पुष्टि माँगते हैं, फिर *.env.example पढ़ने देते हैं। साथ आने वाले एजेंट अतिरिक्त प्रतिबंध लगा सकते हैं।

इसलिए सामान्य फ़ाइल रीड, एडिट, shell कमांड और बाहरी डायरेक्टरी की जाँच के लिए पहले से मेल खाने वाला बेस नियम मौजूद होता है। ask का fallback निर्णय तभी लागू होता है, जब पूरे जाँचे गए नियम-समूह में कोई मेल न मिले। read या edit की अपनी सेटिंग न लिखने को पुष्टि की अनिवार्यता न मानें।

बाहरी डायरेक्टरी की अनुमति और फ़ाइल ऑपरेशन की अनुमति अलग-अलग जाँची जाती हैं। इसमें सक्रिय Location और प्रोजेक्ट का worktree शामिल होते हैं, बशर्ते worktree स्वयं filesystem की root directory न हो। दोनों से बाहर के paths पर OpenCode पहले external_directory जाँचता है, फिर read या edit। यहाँ Location का अर्थ सक्रिय कार्य-स्थान है। इसलिए बाहरी फ़ाइल डायरेक्टरी की सीमा वाली जाँच पास कर सकती है, फिर भी उसके रीड या एडिट पर प्रतिबंध लागू हो सकता है।

यह क्रम डायरेक्टरी जाँच के तंत्र से तय होता है, array में अलग-अलग action वाले नियमों की स्थिति से नहीं। external_directory का नियम read से ऊपर रखने पर इन जाँचों का क्रम तय नहीं होता।

क्या V1 कॉन्फ़िगरेशन रख सकते हैं और कौन-से नाम बदलते हैं?

हाँ। मूल V2 फ़ॉर्मैट अपनाना वैकल्पिक है। OpenCode समर्थित V1 कॉन्फ़िगरेशन को लोड करते समय अपने आंतरिक प्रारूप में बदलता है; मूल फ़ाइलों को दोबारा लिखना ज़रूरी नहीं है। माइग्रेशन निर्देश पहले मौजूदा मॉडल, credentials, एजेंट, permissions और MCP सर्वर जाँचने की सलाह देते हैं।

V1 में permission के निर्णय हर टूल के अंतर्गत रखे जाते हैं:

{
  "permission": {
    "bash": {
      "git push *": "ask"
    },
    "edit": "allow"
  },
  "tools": {
    "websearch": false
  }
}

दस्तावेज़ों में दिया गया V2 रूपांतरण इन्हीं स्पष्ट सेटिंग्स को क्रमबद्ध नियमों में लिखता है:

{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

हर नियम में तीन string फ़ील्ड चाहिए: action, resource और effect। allow बिना पूछे आगे बढ़ने देता है, deny ऑपरेशन रोकता है और ask क्लाइंट में निर्णय का इंतज़ार करता है।

यह उदाहरण सिर्फ़ दिखाई गई सेटिंग्स बदलता है; यह नीचे सुझाई गई बेसलाइन नहीं है। इसमें एडिट अब भी अनुमत हैं और बाहरी डायरेक्टरी की पुष्टि वापस नहीं आती।

Action नामों की मैपिंग है: bash → shell, task → subagent और write/patch → edit। V2 में edit, edit, write और patch ऑपरेशन के लक्ष्य paths नियंत्रित करता है। subagent का मिलान एजेंट ID से होता है; shell का मिलान स्कैनर से बनी कमांड strings से होता है। Action संदर्भ यह भी बताता है कि doom_loop और lsp अब V2 Core के वर्तमान permission actions में शामिल नहीं हैं।

शीर्ष स्तर की सेटिंग्स, एजेंट definitions और कॉन्फ़िगरेशन बनाने वाली scripts जाँचें। असंबंधित फ़ाइलों में इन शब्दों को एक साथ न बदलें। जानबूझकर रूपांतरण करने के बाद V1 और V2 की परस्पर विरोधी permission definitions न छोड़ें।

पुष्टि माँगने वाली एक V2 permissions बेसलाइन अपनाएँ

इंटरैक्टिव कोडिंग के लिए बाहरी एक्सेस, shell कमांड और एडिट से पहले पुष्टि माँगें। Git की सामान्य जाँचें अनुमति दें, मेल खाने वाली push कमांड रोकें और उदाहरण फ़ाइलों को छोड़कर environment फ़ाइलों का रीड रोकें।

किसी एक रिपॉज़िटरी की सेटिंग्स उसके root में opencode.jsonc में रखें। उपयोगकर्ता स्तर की सेटिंग्स के लिए ~/.config/opencode/opencode.jsonc इस्तेमाल करें। OpenCode .json वाले रूप भी स्वीकार करता है; समर्थित स्थान कॉन्फ़िगरेशन संदर्भ में दिए गए हैं।

इस array को मौजूदा कॉन्फ़िगरेशन में मिलाएँ। पूरी फ़ाइल बदलने के बजाय provider सेटिंग्स, एजेंट definitions और पुराने प्रतिबंध सुरक्षित रखें।

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" }
  ]
}

.env.example का अपवाद जानबूझकर दोनों रीड-प्रतिबंधों के बाद रखा गया है। यह अपवाद सिर्फ़ ऐसी उदाहरण फ़ाइलों के लिए रखें जिनमें गोपनीय मान न हों।

जिन actions का उल्लेख नहीं किया गया है, वे अपने प्रभावी डिफ़ॉल्ट नियम अपनाते रहेंगे। यह बेसलाइन हर MCP टूल को नहीं रोकती, push के हर संभावित तरीके को बंद नहीं करती और host filesystem को अलग-थलग नहीं करती। इसके read प्रतिबंध उन्हीं फ़ाइलों को shell कमांड से पढ़ने पर भी अपने आप रोक नहीं लगाते।

OpenCode की shell संबंधी चेतावनी के अनुसार, shell कमांड के पास host user के अधिकार रहते हैं। कमांड किन डायरेक्टरियों तक पहुँचेगी, इसकी पहचान पूरी होने की गारंटी नहीं है। पुष्टि देने से पहले कमांड जाँचें। फ़ाइल ऑपरेशन के नियम पर्याप्त न हों, तो shell पर अलग नियंत्रण लगाएँ।

दूसरे क्लाइंट के लिए Claude Code में secrets और Git के permissions की गाइड देखें। वहाँ OpenCode के कॉन्फ़िगरेशन syntax का दोबारा इस्तेमाल न करें।

अपवाद उन नियमों के बाद रखें जिन्हें वे बदलते हैं

क्रम उन नियमों के बीच मायने रखता है जो उसी action और resource से मेल खाते हैं। बाद में मेल खाने वाला नियम पुराने निर्णय की जगह लेता है। Action का wildcard कई action नामों से मेल खा सकता है।

बेसलाइन में पहले shell: "*" पुष्टि माँगता है। उसके बाद के git status * और git diff * नियम इन कमांड की अनुमति देते हैं। git push * नियम मेल खाने वाली push कमांड रोकता है।

* पर खत्म होने वाला shell pattern बिना arguments वाली कमांड से भी मेल खाता है। इसलिए git status *, git status और git status --short दोनों को शामिल करता है।

मिलान संदर्भ के अनुसार, wildcard पूरे resource मान से मिलाए जाते हैं। * शून्य या अधिक characters से मेल खाता है, जिनमें / भी शामिल है; ? एक character से मेल खाता है। Paths के separators को forward slash में बदला जाता है। Windows में मिलान के दौरान अक्षरों का बड़ा या छोटा होना मायने नहीं रखता।

कई resources वाले ऑपरेशन के लिए एक और चरण होता है। पहले हर resource का अंतिम मेल खाने वाला नियम तय करें। किसी भी resource का अंतिम निर्णय प्रतिबंध हो, तो ऑपरेशन रुकता है। अन्यथा, किसी भी resource को पुष्टि चाहिए तो अनुमति माँगी जाती है। संयुक्त shell कमांड कई resources बना सकती है। एक Git कमांड की अनुमति पूरी संयुक्त कमांड को अनुमति नहीं देती।

भरोसेमंद बाहरी डायरेक्टरी सावधानी से जोड़ें

भरोसेमंद डायरेक्टरी की सीमा पार करने की अनुमति और उसकी फ़ाइलों के ऑपरेशन अलग-अलग सेट करें। ये वैकल्पिक नियम बेसलाइन में जोड़ने के लिए हैं, पूरे कॉन्फ़िगरेशन की जगह लेने के लिए नहीं:

[
  { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "edit", "resource": "~/projects/reference/*", "effect": "deny" }
]

डायरेक्टरी की अनुमति सामान्य external_directory वाले ask के बाद रखें। रीड की अनुमति environment फ़ाइलों के प्रतिबंधों से पहले रखें, ताकि वे प्रतिबंध लागू रहें। एडिट का प्रतिबंध सामान्य एडिट पुष्टि के बाद रखें।

इन path actions के लिए डायरेक्टरी नियम शुरुआत में home directory के संकेत, जैसे ~/, स्वीकार करते हैं। Shell resources मूल कमांड text ही रहते हैं; कॉन्फ़िगरेशन लोड करते समय उन पर यह विस्तार लागू नहीं होता।

एडिट का प्रतिबंध edit से नियंत्रित ऑपरेशन रोकता है, जिनमें write और patch टूल शामिल हैं। यह उस डायरेक्टरी में shell से किए जाने वाले बदलाव नहीं रोकता। Shell के प्रतिबंध अलग रखें और फ़ाइलें बदल सकने वाले हर अनुमति अनुरोध को जाँचें।

माइग्रेट करें, फिर सुरक्षित टेस्ट फ़ाइलों से जाँचें

इस्तेमाल हो रही फ़ाइलों का backup लें, प्रस्तावित diff माँगें और स्वीकार की गई कॉन्फ़िगरेशन अलग टेस्ट प्रोजेक्ट में जाँचें। शुरू करने से पहले V2 क्लाइंट इंस्टॉल होना चाहिए और provider/model कनेक्शन काम करना चाहिए।

प्रस्तावित माइग्रेशन लागू करने से पहले उसकी समीक्षा करें

Global और project कॉन्फ़िगरेशन का backup लें। .opencode/agents/ में मौजूद एजेंट definitions भी शामिल करें। आधिकारिक एजेंट फ़ाइलों के स्थान उपयोगकर्ता स्तर की definitions के लिए ~/.config/opencode/agents/ भी बताते हैं।

Plugins, server API integrations और terminal सेटिंग्स को अलग संभालें। माइग्रेशन गाइड इन क्षेत्रों में compatibility तोड़ने वाले बदलाव बताती है।

OpenCode को यह prompt दें। इसमें पहले समीक्षा करने और पुष्टि मिलने तक फ़ाइलें न बदलने को कहा गया है:

Read the official OpenCode V1 migration and V2 permissions documentation.

Inspect my global, project, and agent permission configuration.
Do not modify any files yet.

Propose native V2 permissions rules.
Preserve unrelated settings and existing restrictions.
Map bash to shell, task to subagent, and write and patch to edit where applicable.
Identify unsupported fields and competing V1/V2 definitions.
Restore external_directory approval without weakening existing deny rules.
Use the baseline's shell and edit approval rules unless existing rules are stricter.
Put environment-file denies before the .env.example exception.
Show the complete proposed diff and explain every behavior change.
Wait for approval before applying it.

सिर्फ़ project फ़ाइल नहीं, मिलाने के बाद की प्रभावी कॉन्फ़िगरेशन जाँचें। एजेंट-विशिष्ट permissions शीर्ष स्तर के संयुक्त नियमों के बाद आते हैं। इसलिए एजेंट का बाद वाला अनुमति-नियम शीर्ष स्तर के सामान्य प्रतिबंध को बदल सकता है।

संगठन के स्तर पर अनिवार्य प्रतिबंधों के लिए OpenCode policies देखें। Policies एजेंट permissions और सहेजी गई अनुमतियों के बाद भी किसी action को पूरी तरह रोक सकती हैं। सामान्य permission array, administrator द्वारा लागू प्रतिबंध का विकल्प नहीं है।

Diff स्वीकार करने के बाद opencode reload से कॉन्फ़िगरेशन दोबारा लोड करें। यह कमांड CLI संदर्भ में दर्ज है। आगे बढ़ने से पहले कॉन्फ़िगरेशन संबंधी चेतावनियाँ जाँचें।

एक बार पूरी जाँच प्रक्रिया चलाएँ

नीचे दिए अपेक्षित नतीजों के लिए v2.2.0 और अंतर्निहित build एजेंट को संदर्भ मानें। तालिका मानती है कि बेसलाइन प्रभावी है और उससे टकराने वाले एजेंट नियम, सहेजी गई अनुमतियाँ या अतिरिक्त policies नहीं हैं।

Bash में सुरक्षित टेस्ट फ़ाइलें बनाएँ:

lab=$(mktemp -d)
mkdir -p "$lab/project" "$lab/outside"
git -C "$lab/project" init -q
printf 'ordinary fixture\n' > "$lab/project/README.md"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env.example"
printf 'outside fixture\n' > "$lab/outside/fixture.txt"
cd "$lab/project"

बेसलाइन इस प्रोजेक्ट की opencode.jsonc फ़ाइल में सहेजें, फिर opencode चलाएँ। Terminal interface गाइड के अनुसार, /agents से build चुनें।

एजेंट से हर ऑपरेशन अलग-अलग, दिए गए टूल के ज़रिए करने को कहें। Terminal में खुद चलाए गए कमांड, एजेंट permissions की जाँच की जगह नहीं लेते।

एजेंट का ऑपरेशन	अपेक्षित permission निर्णय
read से README.md पढ़ना	बेस रीड नियम के अनुसार अनुमति
read से ../outside/fixture.txt पढ़ना	बाहरी डायरेक्टरी की पुष्टि माँगी जाएगी; पुष्टि के बाद सामान्य रीड अनुमत
read से .env पढ़ना	प्रतिबंधित
read से .env.example पढ़ना	अनुमत
edit, write या patch से README.md बदलना	edit के ज़रिए पुष्टि माँगी जाएगी
shell से git status, git status --short या git diff चलाना	अनुमत
shell से git push चलाना	मेल खाने वाला shell नियम रोकेगा
shell से pwd चलाना	पुष्टि माँगी जाएगी

Push जाँचने से पहले खुद git remote चलाएँ और पुष्टि करें कि कोई नाम नहीं दिखता। कोई remote न जोड़ें। Remote न होने की Git error इस बात का प्रमाण नहीं है कि permission नियम ने कमांड रोकी।

पुष्टि वाले टेस्ट में Allow always के बजाय Allow once चुनें, यानी केवल एक बार अनुमति दें। सहेजी गई अनुमतियाँ प्रोजेक्ट के लिए बनी रहती हैं और आगे के prompts रोक सकती हैं। वे कॉन्फ़िगर किए प्रतिबंधों को नहीं बदलतीं। Automatic approval बंद रखें।

असली tool request, permission निर्णय और फ़ाइलों में बदलाव जाँचें। मॉडल का यह कहना कि वह push नहीं करेगा या फ़ाइल नहीं पढ़ेगा, permission engine द्वारा रोके जाने का प्रमाण नहीं है।

नियम ढीला करने से पहले अंतर का कारण खोजें

पहले लोड हुई कॉन्फ़िगरेशन और चुना गया एजेंट जाँचें। CLI debugging कमांड में opencode debug config और opencode debug agents शामिल हैं। उनका output स्थानीय रूप से देखें; credentials या संवेदनशील कॉन्फ़िगरेशन साझा न करें।

बाहरी path के लिए prompt न आए, तो पुष्टि करें कि लक्ष्य Location और उसके project worktree, दोनों से बाहर है। फिर सहेजी गई अनुमतियाँ और automatic approval जाँचें। फ़ाइल रीड का नतीजा अप्रत्याशित हो, तो देखें कि एजेंट ने read इस्तेमाल किया था, shell नहीं।

Git कमांड रुक जाए, तो स्कैनर से बना resource और अतिरिक्त subcommands जाँचें। .env.example रुकने पर देखें कि बाद का *.env.* नियम या अतिरिक्त policy उसके अपवाद को बदल तो नहीं रही।

मौजूदा provider, model ID, authentication और Base URL अलग से जाँचें। BetterToken के OpenCode integration निर्देश https://www.bettertoken.ai/v1 के साथ custom OpenAI-compatible कनेक्शन बताते हैं। यह कनेक्शन OpenCode की permission कॉन्फ़िगरेशन की जगह नहीं लेता।

माइग्रेशन में टूल चुनने का निर्णय भी शामिल हो, तो Cursor और OpenCode की कॉन्फ़िगरेशन तथा एक्सेस के तरीकों की तुलना करें। दूसरे terminal workflow को परखने के लिए वही टेस्ट कार्य Git प्रोजेक्ट में Aider या OpenCode के साथ चलाएँ।

v2.2.0 का filesystem fix क्या बदलता है?

यह fix बाहरी डायरेक्टरी की जाँच में प्रोजेक्ट फ़ाइलों को पहचानने का तरीका बदलता है। स्पष्ट पुष्टि-नियम सेट करने की सलाह नहीं बदलती।

v2.2.0 release notes में प्रोजेक्ट की filesystem इस्तेमाल करने वाला बदलाव दर्ज है। PR #59089 बताता है कि remote और in-memory प्रोजेक्ट के लिए पहले host मशीन की disk जाँची जाती थी। इसके लेखक के अनुसार, सामान्य local प्रोजेक्ट इससे प्रभावित नहीं हैं।

Remote प्रोजेक्ट में उसी प्रोजेक्ट की वास्तविक filesystem पर बाहरी डायरेक्टरी की जाँच दोहराएँ। 2026-10-31 को दर्ज V2 डिफ़ॉल्ट के अनुसार, ऐसी सीमा चाहिए तो external_directory का स्पष्ट ask या deny नियम अब भी आवश्यक है।