پیکربندی دسترسی‌ها

این یک ترجمهٔ غیررسمی از مستندات Claude Code است که توسط مسیر تهیه شده. نسخهٔ مرجع و معتبر، مستندات رسمی انگلیسی است.

Claude Agent SDK کنترل‌های دسترسی فراهم می‌کند تا نحوه‌ی استفاده‌ی Claude از ابزارها را مدیریت کنی. از permission modeها و قواعد برای تعریفِ آنچه خودکار مجاز است استفاده کن، و callbackِ canUseTool را برای رسیدگی به بقیه‌ی موارد در زمانِ اجرا به کار ببر.

یادداشت

This page covers permission modes and rules. To build interactive approval flows where users approve or deny tool requests at runtime, see Handle approvals and user input.

دسترسی‌ها چطور ارزیابی می‌شوند

وقتی Claude یک ابزار را درخواست می‌کند، SDK دسترسی‌ها را به این ترتیب بررسی می‌کند:

هوک‌ها

اول hookها را اجرا کن. یک hook می‌تواند فراخوانی را مستقیماً deny کند یا آن را پاس بدهد. هوکی که allow برمی‌گرداند قواعدِ deny و ask پایین را دور نمی‌زند؛ آن قواعد صرف‌نظر از نتیجه‌ی hook ارزیابی می‌شوند.

قواعد Deny

قواعدِ deny را بررسی کن (از disallowed_tools و settings.json). اگر یک قاعده‌ی deny مطابقت کند، ابزار مسدود می‌شود، حتی در حالتِ bypassPermissions. قواعدِ denyِ نام‌خالی مثل Bash پیش از آغازِ این ارزیابی ابزار را از کانتکستِ Claude حذف می‌کنند، پس در این گام فقط قواعدِ scope‌دار مثل Bash(rm *) بررسی می‌شوند.

قواعد Ask

قواعدِ ask را از settings.json بررسی کن. اگر یک قاعده‌ی ask مطابقت کند، فراخوانی برای تأیید به callbackِ canUseTool سرریز می‌شود، حتی در حالتِ bypassPermissions. در حالتِ dontAsk یک قاعده‌ی askِ مطابق به‌جای آن deny می‌شود، چون آن حالت هرگز پرامپت نمی‌زند.

حالت دسترسی

permission modeِ فعال را اعمال کن. bypassPermissions هر چیزی را که به این گام برسد تأیید می‌کند. acceptEdits عملیاتِ فایل را تأیید می‌کند. plan ابزارهای ویرایشِ فایل و نوشتنِ shell را صرف‌نظر از قواعدِ allow به callbackِ canUseToolِ تو مسیریابی می‌کند، پس عملیاتِ نوشتن نمی‌توانند هنگامِ برنامه‌ریزی خودکار تأیید شوند. حالت‌های دیگر سرریز می‌کنند.

قواعد Allow

قواعدِ allow را بررسی کن (از allowed_tools و settings.json). اگر یک قاعده مطابقت کند، ابزار تأیید می‌شود.

callbackِ canUseTool

اگر با هیچ‌کدام از موارد بالا حل نشد، callbackِ canUseTool را برای یک تصمیم فراخوانی کن. در حالتِ dontAsk، این گام صرف‌نظر می‌شود و ابزار deny می‌شود.

این صفحه روی قواعدِ allow و deny و permission modeها تمرکز دارد. برای گام‌های دیگر:

• هوک‌ها: کدِ سفارشی را برای allow، deny یا تغییرِ درخواست‌های ابزار اجرا کن. کنترلِ اجرا با hookها را ببین.
• callbackِ canUseTool: کاربران را در زمانِ اجرا برای تأیید پرامپت بزن. رسیدگی به تأییدها و ورودیِ کاربر را ببین.

قواعد Allow و Deny

allowed_tools و disallowed_tools (تایپ‌اسکریپت: allowedTools / disallowedTools) ورودی‌هایی را به فهرست‌های قاعده‌ی allow و deny در جریانِ ارزیابیِ بالا اضافه می‌کنند. قواعدِ allow فقط روی تأیید اثر می‌گذارند: ابزاری که در allowed_tools فهرست نشده باشد همچنان برای Claude در دسترس است و به permission mode سرریز می‌کند. قواعدِ deny بسته به اینکه یک ابزار را نام ببرند یا یک الگو را درونِ آن scope کنند، رفتارِ متفاوتی دارند.

گزینه	اثر
allowed_tools=["Read", "Grep"]	Read و Grep خودکار تأیید می‌شوند. ابزارهایی که اینجا فهرست نشده‌اند همچنان وجود دارند و به permission mode و canUseTool سرریز می‌کنند.
disallowed_tools=["Bash"]	تعریفِ ابزارِ Bash از درخواست حذف می‌شود. Claude ابزار را نمی‌بیند و نمی‌تواند آن را امتحان کند.
disallowed_tools=["Bash(rm *)"]	Bash در دسترس می‌ماند. فراخوانی‌های مطابقِ rm * در هر permission mode، از جمله bypassPermissions، deny می‌شوند. سایرِ فراخوانی‌های Bash به permission mode سرریز می‌کنند.
disallowed_tools=["*"]	تعریفِ هر ابزار از درخواست حذف می‌شود. globهای نام‌ابزار در قواعدِ deny پشتیبانی می‌شوند: "*" با هر ابزار و "mcp__*" با هر ابزارِ MCP در همه‌ی سرورها مطابقت می‌کند.

قواعدِ allow فقط پس از یک پیشوندِ literalِ mcp__<server>__ globهای نام‌ابزار را می‌پذیرند. بخشِ server باید بدونِ glob باشد تا قاعده یک سرورِ مشخص که پیکربندی کرده‌ای را نام ببرد: mcp__puppeteer__* با هر ابزار از سرورِ puppeteer و mcp__github__get_* با ابزارهای get_ِ آن مطابقت می‌کند. یک ورودیِ بدونِ‌لنگر مثل allowed_tools=["*"] یا allowed_tools=["mcp__*"] با یک هشدارِ راه‌اندازی نادیده گرفته می‌شود و چیزی را خودکار تأیید نمی‌کند.

برای یک ایجنتِ قفل‌شده، allowedTools را با permissionMode: "dontAsk" جفت کن. ابزارهای فهرست‌شده تأیید می‌شوند؛ هر چیزِ دیگری به‌جای پرامپت‌زدن مستقیماً deny می‌شود:

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

احتیاط

allowed_tools does not constrain bypassPermissions. allowed_tools only pre-approves the tools you list. Unlisted tools are not matched by any allow rule and fall through to the permission mode, where bypassPermissions approves them. Setting allowed_tools=["Read"] alongside permission_mode="bypassPermissions" still approves every tool, including Bash, Write, and Edit. If you need bypassPermissions but want specific tools blocked, use disallowed_tools.

همچنین می‌توانی قواعدِ allow، deny و ask را به‌صورتِ declarative در .claude/settings.json پیکربندی کنی. این قواعد وقتی خوانده می‌شوند که منبعِ تنظیماتِ project فعال باشد، که برای گزینه‌های پیش‌فرضِ query() همین‌طور است. اگر setting_sources (تایپ‌اسکریپت: settingSources) را به‌صراحت تنظیم کنی، "project" را بگنجان تا اعمال شوند. برای نحوِ قاعده، Permission settings را ببین.

Permission modeها

permission modeها کنترلِ سراسری روی نحوه‌ی استفاده‌ی Claude از ابزارها فراهم می‌کنند. می‌توانی permission mode را هنگامِ فراخوانیِ query() تنظیم کنی یا در طولِ نشست‌های استریمی پویا تغییرش بدهی.

حالت‌های موجود

این SDK از این permission modeها پشتیبانی می‌کند:

حالت	توضیح	رفتارِ ابزار
default	رفتارِ استانداردِ دسترسی	بدونِ تأییدِ خودکار؛ ابزارهای بدونِ‌مطابقت callbackِ canUseToolِ تو را فعال می‌کنند
dontAsk	به‌جای پرامپت، deny	هر چیزی که با allowed_tools یا قواعد از پیش تأیید نشده باشد deny می‌شود؛ canUseTool هرگز فراخوانی نمی‌شود
acceptEdits	پذیرشِ خودکارِ ویرایش‌های فایل	ویرایش‌های فایل و عملیاتِ فایل‌سیستم (mkdir, rm, mv و غیره) خودکار تأیید می‌شوند
bypassPermissions	دور زدنِ بررسی‌های دسترسی	ابزارها بدونِ پرامپتِ دسترسی اجرا می‌شوند، مگر اینکه یک قاعده‌ی askِ صریح مطابقت کند (با احتیاط استفاده کن)
plan	حالتِ برنامه‌ریزی	Claude بدونِ ویرایشِ فایل‌های منبعِ تو کاوش و برنامه‌ریزی می‌کند؛ ویرایش‌های فایل هرگز خودکار تأیید نمی‌شوند و از طریقِ callbackِ canUseToolِ تو پرامپت می‌خورند
auto (فقط تایپ‌اسکریپت)	تأییدهای طبقه‌بندی‌شده با مدل	یک طبقه‌بندِ مدل هر فراخوانیِ ابزار را تأیید یا deny می‌کند. برای در دسترس‌بودن Auto mode را ببین

احتیاط

Subagent inheritance: When the parent uses bypassPermissions, acceptEdits, or auto, all subagents inherit that mode and it cannot be overridden per subagent. Subagents may have different system prompts and less constrained behavior than your main agent, so inheriting bypassPermissions grants them full, autonomous system access. An explicit ask rule still forces a prompt.

تنظیمِ permission mode

می‌توانی permission mode را یک‌بار هنگامِ شروعِ یک query تنظیم کنی، یا در حالی که نشست فعال است پویا تغییرش بدهی.

هنگام query

هنگامِ ساختِ یک query، permission_mode (پایتون) یا permissionMode (تایپ‌اسکریپت) را پاس بده. این حالت برای کلِ نشست اعمال می‌شود مگر اینکه پویا تغییر کند.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Help me refactor this code",
        options=ClaudeAgentOptions(
            permission_mode="default",  # Set the mode here
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  for await (const message of query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Set the mode here
    }
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

در حین استریم

برای تغییرِ حالت در میانه‌ی نشست، set_permission_mode() (پایتون) یا setPermissionMode() (تایپ‌اسکریپت) را فراخوانی کن. حالتِ جدید بلافاصله برای همه‌ی درخواست‌های ابزارِ بعدی اثر می‌گذارد. این به تو امکان می‌دهد محدود شروع کنی و با ساخته‌شدنِ اعتماد دسترسی‌ها را شل کنی، مثلاً پس از مرورِ رویکردِ اولیه‌ی Claude به acceptEdits سوییچ کنی.

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    async with ClaudeSDKClient(
        options=ClaudeAgentOptions(
            permission_mode="default",  # Start in default mode
        )
    ) as client:
        await client.query("Help me refactor this code")

        # Change mode dynamically mid-session
        await client.set_permission_mode("acceptEdits")

        # Process messages with the new permission mode
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  const q = query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Start in default mode
    }
  });

  // Change mode dynamically mid-session
  await q.setPermissionMode("acceptEdits");

  // Process messages with the new permission mode
  for await (const message of q) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

جزئیاتِ حالت‌ها

حالتِ پذیرشِ ویرایش‌ها (acceptEdits)

عملیاتِ فایل را خودکار تأیید می‌کند تا Claude بتواند بدونِ پرامپت کد را ویرایش کند. ابزارهای دیگر (مثل فرمان‌های Bash که عملیاتِ فایل‌سیستم نیستند) همچنان به دسترسیِ عادی نیاز دارند.

عملیاتِ خودکارتأییدشده:

• ویرایش‌های فایل (ابزارهای Edit، Write)
• فرمان‌های فایل‌سیستم: mkdir, touch, rm, rmdir, mv, cp, sed

هر دو فقط برای مسیرهای درونِ دایرکتوریِ کاری یا additionalDirectories اعمال می‌شوند. مسیرهای بیرونِ آن scope و نوشتن روی مسیرهای محافظت‌شده همچنان پرامپت می‌خورند.

کِی استفاده کن: وقتی به ویرایش‌های Claude اعتماد داری و تکرارِ سریع‌تر می‌خواهی، مثلاً هنگامِ نمونه‌سازی یا کار در یک دایرکتوریِ ایزوله.

حالتِ بدونِ پرسش (dontAsk)

هر پرامپتِ دسترسی را به یک deny تبدیل می‌کند. ابزارهایی که با allowed_tools، قواعدِ allowِ settings.json یا یک hook از پیش تأیید شده‌اند طبقِ معمول اجرا می‌شوند. هر چیزِ دیگری بدونِ فراخوانیِ canUseTool deny می‌شود.

کِی استفاده کن: وقتی برای یک ایجنتِ headless یک سطحِ ابزارِ ثابت و صریح می‌خواهی و denyِ سفت را به اتکای خاموش بر غیابِ canUseTool ترجیح می‌دهی.

حالتِ دور زدنِ دسترسی‌ها (bypassPermissions)

همه‌ی استفاده‌های ابزار را بدونِ پرامپت خودکار تأیید می‌کند. hookها همچنان اجرا می‌شوند و در صورتِ نیاز می‌توانند عملیات را مسدود کنند.

احتیاط

Use with extreme caution. Claude has full system access in this mode. Only use in controlled environments where you trust all possible operations.

allowed_tools does not constrain this mode. Every tool is approved, not just the ones you listed. Deny rules (disallowed_tools), explicit ask rules, and hooks are evaluated before the mode check and can still block a tool.

حالتِ برنامه‌ریزی (plan)

Claude کدبیس را کاوش می‌کند و بدونِ ویرایشِ فایل‌های منبعِ تو یک برنامه تولید می‌کند. ابزارهای فقط‌خواندنی مثلِ حالتِ default اجرا می‌شوند. ویرایش‌های فایل در حالتِ plan هرگز خودکار تأیید نمی‌شوند، حتی وقتی یک قاعده‌ی allow مطابقت کند. آن‌ها به‌جای آن از طریقِ callbackِ canUseToolِ تو پرامپت می‌خورند. Claude ممکن است پیش از نهایی‌کردنِ برنامه از AskUserQuestion برای شفاف‌سازیِ نیازمندی‌ها استفاده کند. برای رسیدگی به این پرامپت‌ها رسیدگی به تأییدها و ورودیِ کاربر را ببین.

کِی استفاده کن: وقتی می‌خواهی Claude تغییرات را بدونِ اجراکردن پیشنهاد بدهد، مثلاً هنگامِ بازبینیِ کد یا وقتی پیش از اعمالِ تغییرات باید آن‌ها را تأیید کنی.

منابعِ مرتبط

برای گام‌های دیگرِ جریانِ ارزیابیِ دسترسی:

• رسیدگی به تأییدها و ورودیِ کاربر: پرامپت‌های تأییدِ تعاملی و پرسش‌های شفاف‌سازی
• راهنمای Hooks: اجرای کدِ سفارشی در نقاطِ کلیدیِ چرخه‌ی حیاتِ ایجنت
• قواعدِ دسترسی: قواعدِ declarativeِ allow/deny در settings.json