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

# Beta channel only. Tiers: inherit, sonnet, opus, fable, haiku.
# The value is shape-checked, not locked to the catalog snapshot.
ak config prefs set agent_models.cursor.sonnet claude-sonnet-4-6

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, grok, …	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.

Chỉ kênh beta — file .akignore cho privacy hook

Trên beta, file .akignore liệt kê các path (cú pháp giống .gitignore) mà privacy hook không coi là nhạy cảm nữa. Dòng bắt đầu bằng ! bảo vệ lại path đó. Stable hiện tại chưa có file này.

Vị trí: ~/.agentkit/.akignore cho cả máy, .akignore hoặc .agentkit/.akignore trong repo cho từng project. File đọc sau thắng: máy trước, rồi tới project.
File của project đến cùng repo khi clone, nên chỉ có hiệu lực sau khi bạn xác nhận tin đúng nội dung đó một lần. Sửa file thì phải xác nhận lại. File ở máy không cần xác nhận.
Chỉ áp dụng bên trong một git repo và cho path nằm trong project. File này không tắt hook; muốn tắt hẳn thì dùng privacy_block: false.

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