مرجع تنظیمات

فایل‌های پیکربندی، متغیرهای محیطی و مسیرهای مهم اکوان.

پیکربندی Akvan از چند منبع خوانده می‌شود: متغیرهای محیطی، فایل‌های .env و فایل‌های YAML. محل دقیق بعضی تنظیمات در نسخهٔ فعلی یکدست نیست، بنابراین هنگام عیب‌یابی هم ~/.akvan و هم project_root را بررسی کنید.

فایل‌ها و مسیرهای مهم

مسیر	کاربرد
`~/.akvan/.env`	secretها و تنظیمات global provider
`project_root/.env`	override محلی برای همان پروژه؛ بعد از `~/.akvan/.env` خوانده می‌شود
`~/.akvan/config.yaml`	تنظیمات ذخیره‌شده توسط setupهای CLI مثل logging و web tools
`project_root/config.yaml`	در session فعلی برای memory، skills و web tool discovery هم بررسی می‌شود
`~/.akvan/state.db`	sessions، FTS search و تنظیمات ماندگار gateway
`~/.akvan/memories/`	`MEMORY.md` و `USER.md`
`~/.akvan/skills/`	skills کاربر
`project_root/.akvan/skills/`	skills مخصوص پروژه؛ در برخورد نام، نسبت به user skill اولویت دارد
`~/.akvan/logs/`	لاگ‌های چرخشی CLI و gateway

ترتیب خواندن .env

هنگام اجرای session، Akvan ابتدا متغیرهای محیطی process را در نظر می‌گیرد، سپس ~/.akvan/.env و بعد .env داخل project_root را می‌خواند. مقدارهای project .env می‌توانند تنظیمات global را override کنند.

فایل‌های .env حاوی secret هستند. آن‌ها را commit نکنید و در گفتگو یا issue عمومی منتشر نکنید.

تنظیمات YAML

نمونهٔ پایه:

yaml

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  nudge_interval: 10

skills:
  creation_nudge_interval: 10

display:
  review_notifications: on

logging:
  level: INFO
  max_size_mb: 5
  backup_count: 3
  console: false

اگر تغییری در ~/.akvan/config.yaml اثر نکرد، بررسی کنید که پروژهٔ فعلی project_root/config.yaml نداشته باشد یا تنظیم مشابهی در .env/environment override نشده باشد.

متغیرهای اصلی محیطی

متغیر	توضیح
`AKVAN_PROVIDER`	`akvan`، `openrouter`، `openai-codex` یا `deepseek`
`AKVAN_MODEL`	شناسهٔ مدل پیش‌فرض برای provider فعال
`AKVAN_APPROVAL_MODE`	یکی از `ask`، `deny` یا `off`
`AKVAN_APPROVAL_TIMEOUT`	زمان انتظار approval بر حسب ثانیه؛ حداقل ۱
`AKVAN_TERMINAL_TIMEOUT`	timeout اجرای commandهای terminal؛ بین ۱ تا ۶۰۰ ثانیه
`AKVAN_LOG_LEVEL`	سطح log مانند `DEBUG` یا `INFO`؛ روی YAML اولویت دارد
`AKVAN_HOME`	تغییر مسیر پیش‌فرض `~/.akvan`

متغیرهای provider Akvan

متغیر	توضیح
`AKVAN_API_KEY`	کلید حساب Akvan (`akv_...`)؛ پس از ورود OTP ذخیره می‌شود
`AKVAN_BACKEND_URL`	آدرس سرویس Akvan؛ معمولاً نیازی به تغییر دستی ندارد

برای provider akvan نیازی به OPENROUTER_API_KEY، OPENAI_API_KEY یا DEEPSEEK_API_KEY نیست.

متغیرهای سایر providerها

provider	متغیرهای اصلی
`openrouter`	`OPENROUTER_API_KEY`
`openai-codex`	`AKVAN_CODEX_AUTH_MODE`، یا `OPENAI_API_KEY` در حالت API key
`deepseek`	`DEEPSEEK_API_KEY`، `AKVAN_DEEPSEEK_THINKING`، `AKVAN_DEEPSEEK_REASONING_EFFORT`

web tools

برای web search و web extract، akvan tools تنظیمات را ذخیره می‌کند. runtime هم متغیرهایی مثل AKVAN_WEB_SEARCH_BACKEND، AKVAN_WEB_EXTRACT_BACKEND، SEARXNG_URL، FIRECRAWL_API_URL و FIRECRAWL_API_KEY را از environment و فایل‌های .env می‌خواند.

/learn برای موضوعات عمومی (مثلاً /learn tailwind css) به web_search و web_extract نیاز دارد. /learn با اشاره به session قبلی به ~/.akvan/state.db (session persistence) نیاز دارد. جزئیات → learn.

گزارش مشکل مستندات