Configuration¶
AgenticX uses layered configuration:
- Global — the platform-standard
AgenticXapp directory (~/.config/AgenticXon Linux;AGENTICX_HOMEoverrides it on any platform): per-provider API key slots, voice/TTS settings, shared across projects. - Workspace —
./.agenticx/config.toml: provider, model, platform capabilities, MCP services, username.
Priority: workspace config > global config > environment variables
(fill empty slots only) > interactive input. AGENTICX_PROVIDER and
AGENTICX_MODEL always force-override. The same resolution is exposed
programmatically as Config.load().
Workspace config¶
# ./.agenticx/config.toml
user_name = "agenticx"
provider = "tongyi"
model = "qwen3.8-flash"
fallback_providers = "openai,anthropic" # tried in order on primary failure
enabled_capabilities = "bailian.mcp,bailian.cli"
max_turns = 100 # tool-call turns per conversation (default 50)
session_persist = true # cross-session history persistence
tui = false # false = inline CLI REPL instead of TUI
user_directives = ["Don't push after each commit"] # written by /rule
delegation = { max_concurrent = 5, default_timeout = 120 }
[[mcp_servers]]
service = "time"
The full field list with types and defaults is in the Config reference.
Global config & API keys¶
Each provider has an independent key slot, so switching providers never
overwrites another key. New secrets are stored in the OS keyring under
the dashscope-agenticx service; TOML holds only references:
# ~/.config/AgenticX/config.toml
tongyi_api_key = "KEYRING:v1:..."
anthropic_api_key = "KEYRING:v1:..."
openai_api_key = "KEYRING:v1:..."
The /provider wizard enters keys without terminal echo and offers
three sources: OS keyring, environment variable, or configure later.
Legacy single api_key lines are migrated to the current provider's
slot on first launch; legacy ENC: values remain readable for
migration but are never written for new secrets.
Environment variables¶
API-key variables only fill empty slots; AGENTICX_PROVIDER /
AGENTICX_MODEL always override.
| Variable | Description |
|---|---|
DASHSCOPE_API_KEY |
Tongyi / Bailian API key |
ANTHROPIC_API_KEY |
Claude API key |
OPENAI_API_KEY |
OpenAI API key |
OPENAI_BASE_URL |
Custom OpenAI-compatible endpoint (highest priority) |
AGENTICX_PROVIDER |
Force the provider |
AGENTICX_MODEL |
Force the model |
AGENTICX_MCP_SERVERS |
Pre-connect MCP services (comma-separated) |
AGENTICX_MEMORY_USER_ID |
User identifier for profile isolation |
AGENTICX_MEMORY_LIBRARY_ID |
Bailian profile library ID |
AGENTICX_COMMAND_TIMEOUT |
run_command timeout seconds (default 600) |
AGENTICX_HOME |
Override the global config directory |
Built-in providers¶
| Provider | Protocol | Default model |
|---|---|---|
tongyi |
DashScope native | qwen3.8-flash |
anthropic |
Anthropic Messages | claude-sonnet-4-20250514 |
openai |
OpenAI | gpt-4o |
Switch with /provider (wizard) or /model <name> (model-only).
Reasoning models (reasoning_content) are supported; the reasoning
content is passed back on the next request to avoid provider 400s.
Custom providers¶
DeepSeek, Kimi, Ollama, and any OpenAI/Anthropic-compatible endpoint are
declared in custom-extensions.toml (workspace overrides global by
name) — no code required:
# ./.agenticx/custom-extensions.toml
[[providers]]
name = "moonshot"
base_url = "https://api.moonshot.cn/v1"
api_key_env = "MOONSHOT_API_KEY" # env var name; no plaintext on disk
default_model = "kimi-k2"
protocol = "openai" # openai / anthropic / dashscope
[[providers]]
name = "ollama"
base_url = "http://localhost:11434/v1"
default_model = "llama3"
protocol = "openai"
auth = false # local, no key needed
Plaintext api_key = "sk-..." is rejected by the loader; use
api_key_env or a KEYRING:v1: reference. /dev provider add writes
these blocks interactively. See
Tools, Skills & Experts
for HTTP tool groups, shell tools, and skills in the same file.
base_url precedence (primary provider): OPENAI_BASE_URL env >
base_url in config.toml > matching [[providers]] entry > built-in
default. Fallback providers always use their own declared endpoint.
Workspace file map¶
| File | Purpose |
|---|---|
.agenticx/config.toml |
Models, capabilities, interaction settings |
.agenticx/system-prompt.md |
Domain role and behavioral instructions |
.agenticx/skills/ |
Markdown skills and skill packages |
.agenticx/custom-extensions.toml |
Declarative providers and HTTP/shell tools |
.agenticx/permissions.toml |
Tool/command allow-deny-confirm policy |
.agenticx/hooks.toml |
Event hooks under trust and permission controls |
.agenticx/session/ |
Persistent conversations and run records |