Vị trí

Hai scope, một schema

User

~/.agentkit/config.yaml (hoặc $AGENTKIT_HOME/config.yaml). Máy cá nhân: keys, updates, adapters, telemetry…

Project

.agentkit/config.yaml trong repo. Deep-merge đè user cho repo này: coding_level, paths, hooks…

Field names là snake_case. Schema: https://releases.agentkit.best/schemas/config/v1.json — validate bằng ak config prefs validate.

CLI

Xem và chỉnh

shell

# Dashboard / visual config
ak config

# Preferences (hook toggles, resolve effective config)
ak config prefs resolve
ak config prefs validate
ak config prefs set hooks.simplify-gate false --scope project
ak config prefs unset hooks.simplify-gate --scope project

Setup-owned

Phần ak setup / lifecycle thường ghi

Các key do CLI setup model trực tiếp. Giá trị “—” nghĩa là omit/empty cho đến khi setup ghi.

Path	Type	Mặc định	Options	Ý nghĩa
keys.anthropic	string	—	—	API key Anthropic do ak setup ghi. Chỉ user config — không commit project config chứa key.
keys.openai	string	—	—	API key OpenAI do ak setup ghi. Chỉ user config.
provider.default	string	—	—	Provider mặc định (vd anthropic).
provider.model	string	—	—	Model text mặc định.
provider.image	string	—	—	Model dùng cho image generation.
kit.default	string	—	—	Kit mặc định (vd engineer) khi cài/setup.
telemetry.enabled	boolean	false*	—	Gửi telemetry ẩn danh. *fixture setup thường false; bật chỉ khi bạn chọn.
api.token	string	—	—	Bearer token cho local API / dashboard khi bind ngoài loopback. Không commit.
adapters.enabled	string	—	claude-code, codex, cursor, …	Danh sách adapter bật, phân tách bằng dấu phẩy (vd claude-code,codex).
codex.api_key_env_var	string	—	—	Tên env var Codex đọc API key (vd OPENAI_API_KEY).
codex.default_model	string	—	—	Model ghi vào cấu hình Codex.
codex.provider	string	—	openai \| azure \| bedrock	Backend provider cho Codex.
updates.enabled	boolean	—	—	Opt-in auto-update Desktop / paired update.
updates.channel	string	—	stable \| beta	Kênh binary update. Rỗng có thể mặc định theo binary.
updates.registry_url	string	—	—	Override root metadata update (staging).
updates.cli_path	string	—	—	Đường dẫn ak CLI đã verify ghép với Desktop auto-update.
backups.scope	string	full	full \| lean	Phạm vi snapshot user-home.
backups.keep_last	integer	20	—	Số snapshot giữ lại. 0 = tắt prune.

Preferences

Preference workflow / kit (thường project)

Template project và schema v1. Phù hợp commit để team dùng chung coding_level, paths, hooks.

Path	Type	Mặc định	Options	Ý nghĩa
coding_level	integer	-1	-1…5	-1 tắt · 0 eli5 · 1 junior · 2 mid · 3 senior · 4 tech-lead · 5 architect/god-mode. Độ sâu giải thích.
privacy_block	boolean	true	—	Bật hook chặn đọc file nhạy cảm (.env, credentials, keys…).
paths.docs	string	docs	—	Thư mục docs (relative project root hoặc absolute).
paths.plans	string	plans	—	Thư mục plans.
docs.max_loc	integer	800	100–5000	Giới hạn LOC gợi ý cho file docs.
locale.response_language	string\|null	null	—	Ngôn ngữ output cho user (null = theo user / English).
locale.thinking_language	string\|null	null	—	Ngôn ngữ suy luận nội bộ (null = English).
plan.naming_format	string	"{date}-{issue}-{slug}"	—	Mẫu tên thư mục plan. Token: {date}, {issue}, {slug}.
plan.date_format	string	YYMMDD-HHmm	—	Format cho token {date}.
plan.issue_prefix	string	GH-	—	Tiền tố issue (vd GH-, JIRA-).
plan.reports_dir	string	reports	—	Subdir reports trong plan.
plan.resolution.order	string[]	["session","branch"]	session, branch, directory	Thứ tự resolve plan active.
plan.validation.mode	string	prompt	prompt \| auto \| strict \| none	Khi nào chạy validation interview cho plan.
plan.validation.min_questions	integer	3	—	Số câu hỏi validation tối thiểu.
plan.validation.max_questions	integer	8	—	Số câu hỏi validation tối đa.
hooks.<name>	boolean	absent = on	true \| false	Tắt từng hook theo basename script. Key vắng = hook bật.
project.type	string	auto	auto \| library \| application \| monorepo \| cli \| api \| web \| mobile	Ghi đè detect loại project.
gemini.model	string	gemini-3-flash-preview	gemini-2.5-flash \| gemini-2.5-pro \| …	Model Gemini CLI khi skill dùng Gemini.

Ví dụ

Mẫu tối thiểu

User (máy local)

config.yaml

# ~/.agentkit/config.yaml  (user scope)
telemetry:
  enabled: false
adapters:
  enabled: claude-code,codex
updates:
  enabled: false
  channel: stable
backups:
  scope: full
  keep_last: 20
coding_level: 2
privacy_block: true
locale:
  response_language: vi
  thinking_language: en

Project (commit được)

.agentkit/config.yaml

# .agentkit/config.yaml  (project — safe to commit)
# yaml-language-server: $schema=https://releases.agentkit.best/schemas/config/v1.json
coding_level: 3
paths:
  docs: docs
  plans: plans
privacy_block: true
hooks:
  simplify-gate: false
plan:
  naming_format: "{date}-{slug}"
  validation:
    mode: prompt

Cấu Hình AgentKit