⚙️ config.toml 配置教程

零配置可启动 · 一行切换模型 · 精细控制安全与上下文

1. 配置文件位置与优先级

YouCoder 的配置来自多个层级，后加载的覆盖先加载的：

优先级	位置	说明
1（最高）	~/.youcoder/web-config.toml	桌面端 / Web Dashboard 设置面板写入；空文件 = 全部回退到下层
2	环境变量 YOUCODER_*	覆盖配置文件中的对应项
3	~/.youcoder/config.toml	用户级全局配置（手工编辑的主战场）
4	./.youcoder/config.toml	项目级配置，可随仓库分发（如团队统一模型）
5（最低）	内置默认值	零配置即可启动

本章其余内容默认针对 ~/.youcoder/config.toml。所有字段均为可选——未设置的字段自动回退到默认值，因此配置文件可以只写你关心的几行。

2. 最小配置

只需一行 api_key 即可开始使用（provider = "auto" 时会按已知提供商顺序自动探测）：

# ~/.youcoder/config.toml
api_key = "sk-your-api-key"

也可以显式指定提供商并切换模型：

provider = "deepseek"
api_key = "sk-deepseek-key"
primary_models = ["deepseek-v4-flash"]

3. 模型提供商

字段	类型	默认	说明
provider	string	"auto"	提供商 ID：anthropic / openai / deepseek / gemini / zhipu / minimax / xiaomi / auto
api_key	string	空	提供商 API Key（也可用环境变量，见第 9 节）
base_url	string	无	Base URL 覆盖（如自托管网关 / 兼容端点）
max_tokens	integer	8192	单次响应最大 token 数
primary_models	array	["claude-sonnet-4-20250514"]	主模型池（同提供商），第一项为默认模型
secondary_model	string	无	备用模型名（同提供商）
secondary_provider	string	无	跨提供商备用（如主 DeepSeek、备 OpenAI）
secondary_api_key	string	无	备用提供商 API Key
secondary_base_url	string	无	备用 Base URL
secondary_max_tokens	integer	无	备用模型 max tokens

跨提供商备用模型示例：

provider = "deepseek"
api_key = "sk-deepseek"
primary_models = ["deepseek-v4-flash"]

secondary_provider = "openai"
secondary_api_key = "sk-openai"
secondary_model = "gpt-4o"

4. 高级选项

字段	类型	默认	说明
system_prompt	string	无	自定义系统提示词，预置到每次请求
context_compact_threshold	float	0.80	上下文窗口使用率阈值（0.0–1.0），达到后自动压缩
context_young_rounds	integer	2	始终完整保留的最近对话轮数
context_window_override	integer	无	手动覆盖上下文窗口 token 数（覆盖提供商自动探测）
search_provider	string	"duckduckgo"	搜索提供商：duckduckgo / bing
search_base_url	string	无	自定义搜索 API Base URL（自托管 / 替代端点）
proxy_url	string	无	HTTP 代理，如 "http://127.0.0.1:7890"
no_proxy	string	无	绕过代理的主机列表（逗号分隔，遵循 NO_PROXY 约定）
browser_path	string	无	浏览器可执行文件路径（不设置 = 自动探测 Chromium 系浏览器）
chrome_headless	bool	true	browser_fetch 是否无头模式
max_file_backups	integer	10	每个文件保留的最大备份数（undo_file 可回滚）

代理与上下文示例：

proxy_url = "http://127.0.0.1:7890"
no_proxy = "localhost,127.0.0.1,.internal"

context_compact_threshold = 0.75
context_young_rounds = 3
max_tokens = 16384

5. 向量检索 [embedding]

可选第三检索通道，为代码库提供语义搜索。支持 Ollama（本地）与 OpenAI 兼容端点：

[embedding]
enabled = true
provider = "ollama"          # "ollama" | "openai"
model = "nomic-embed-text"   # 例如 ollama 的 nomic-embed-text
base_url = "http://localhost:11434"
# api_key = "sk-..."         # OpenAI 兼容端点时需要
dimension = 768              # nomic-embed-text 为 768
batch_size = 10              # 后台批量生成嵌入的批大小

字段	类型	默认	说明
enabled	bool	false	是否启用向量搜索
provider	string	空	"ollama" / "openai"
model	string	空	嵌入模型名
base_url	string	空	API 地址，如 "http://localhost:11434"
api_key	string	无	OpenAI 兼容端点的 Key（可选）
dimension	integer	768	嵌入向量维度
batch_size	integer	10	嵌入批大小

6. 命令执行安全 [tools.exec]

控制 exec_shell 等命令执行工具的安全策略：

[tools.exec]
# 安全等级：relaxed（宽松，默认）| allowlist（白名单）| deny（禁止）
security = "allowlist"

# 审批触发：on-denied（仅拒绝时，默认）| on-every-command（每次执行都确认）
ask = "on-denied"

# 白名单 — 匹配到的命令自动放行，不匹配的需终端确认
allowlist = [
    "cargo",          # 前缀匹配：cargo build / cargo test ...
    "npm run *",      # 通配匹配：npm run build / npm run test ...
    "git",            # git status / git add / git commit ...
    "python", "python3", "pip", "pip3",
    "ls", "cat", "echo", "grep", "find",
    "cp", "mv", "mkdir", "touch", "chmod",
    "rm",             # 注意：rm -rf / 仍会被危险模式独立拦截
]

字段	类型	默认	说明
security	string	"relaxed"	"deny"（禁止）\| "allowlist"（白名单）\| "relaxed"（宽松）
ask	string	"on-denied"	"on-denied"（仅拒绝时）\| "on-every-command"（每次确认）
allowlist	array	空	免审批命令白名单，支持前缀匹配与通配（npm run *）

7. MCP 服务器 [[mcp_servers]]

通过 Model Context Protocol 连接外部工具与数据源（数据库、文件系统、Web API）：

[[mcp_servers]]
name = "everything"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]
max_result_size = 50000
# daily_disabled = false   # true 时该 MCP 仅在治理模式可见

字段	类型	默认	说明
name	string	必填	MCP 服务器名称
command	string	必填	启动命令
args	array	[]	命令参数
max_result_size	integer	50000	工具结果最大字符数，0 = 不限
daily_disabled	bool	false	为 true 时该 MCP 工具仅在治理模式可见，日常模式被过滤

8. 完整配置示例

一份覆盖常用场景的完整示例：

# ===== 模型 =====
provider = "deepseek"
api_key = "sk-deepseek-key"
base_url = "https://api.deepseek.com"   # 可选，DeepSeek 默认值
max_tokens = 8192
primary_models = ["deepseek-v4-flash"]

secondary_provider = "openai"
secondary_api_key = "sk-openai-key"
secondary_model = "gpt-4o"

# ===== 上下文与高级 =====
system_prompt = "你是一个严谨的 Rust 工程师。"
context_compact_threshold = 0.80
context_young_rounds = 2

# ===== 网络 =====
# proxy_url = "http://127.0.0.1:7890"
# no_proxy = "localhost,127.0.0.1"
search_provider = "duckduckgo"

# ===== 向量检索（可选）=====
[embedding]
enabled = false
provider = "ollama"
model = "nomic-embed-text"
base_url = "http://localhost:11434"

# ===== 命令执行安全 =====
[tools.exec]
security = "allowlist"
ask = "on-denied"
allowlist = ["cargo", "git", "npm run *", "python3", "ls", "cat", "echo"]

# ===== MCP 服务器（可选）=====
[[mcp_servers]]
name = "everything"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]

9. 环境变量对照

所有配置项都可以用 YOUCODER_* 环境变量覆盖（优先级高于配置文件）。API Key 另有各提供商的专有变量：

环境变量	对应配置项
YOUCODER_API_KEY（或 ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY / GEMINI_API_KEY / ZHIPU_API_KEY / MINIMAX_API_KEY / XIAOMI_API_KEY）	api_key（设置时 provider 自动切换为对应提供商）
YOUCODER_PROVIDER	provider
YOUCODER_BASE_URL	base_url
YOUCODER_MAX_TOKENS	max_tokens
YOUCODER_CONTEXT_COMPACT_THRESHOLD	context_compact_threshold
YOUCODER_CONTEXT_YOUNG_ROUNDS	context_young_rounds
YOUCODER_CONTEXT_WINDOW	context_window_override
YOUCODER_SEARCH_PROVIDER / YOUCODER_SEARCH_BASE_URL	search_provider / search_base_url
YOUCODER_PROXY_URL / YOUCODER_NO_PROXY	proxy_url / no_proxy
YOUCODER_BROWSER_PATH / YOUCODER_CHROME_HEADLESS	browser_path / chrome_headless
YOUCODER_PRIMARY_MODELS（逗号分隔）	primary_models
YOUCODER_SECONDARY_MODEL / YOUCODER_SECONDARY_PROVIDER / YOUCODER_SECONDARY_API_KEY / YOUCODER_SECONDARY_BASE_URL / YOUCODER_SECONDARY_MAX_TOKENS	secondary_* 备用模型
YOUCODER_EMBEDDING_PROVIDER / YOUCODER_EMBEDDING_MODEL / YOUCODER_EMBEDDING_BASE_URL / YOUCODER_EMBEDDING_API_KEY	[embedding]（前两者会同时置 enabled = true）
YOUCODER_LICENSE_KEY	license key（许可激活）

10. 常见问题

问题	解决方案
写了 model = "..." 但没生效	model 字段已过时（会被静默忽略），改用 primary_models = ["..."] 数组
配置文件改了没生效	确认写入的是 ~/.youcoder/config.toml（用户级）而非项目级；重启会话 / 应用让配置重新加载；注意 GUI 设置面板写入的 web-config.toml 优先级最高，会覆盖同名项
提示 "No API key configured"	检查 api_key 字段与位置，或用环境变量方式（见第 9 节）
工具执行被拒绝	检查 [tools.exec] 的 security / allowlist 配置，以及感知域范围
如何回滚被改坏的文件	用 undo_file 工具恢复备份（备份数量由 max_file_backups 控制）

⚙️ config.toml Configuration Guide

Zero-config startup · switch models in one line · fine-grained control over safety and context

1. File Locations & Precedence

YouCoder reads configuration from several layers — later layers override earlier ones:

Priority	Location	Description
1 (highest)	~/.youcoder/web-config.toml	Written by the Desktop / Web Dashboard settings panel; an empty file falls back to lower layers entirely
2	Environment variables YOUCODER_*	Override the matching config-file entries
3	~/.youcoder/config.toml	User-level global config (the main file you edit by hand)
4	./.youcoder/config.toml	Project-level config, shipped with the repo (e.g. team-wide model)
5 (lowest)	Built-in defaults	Zero-config startup works out of the box

The rest of this page targets ~/.youcoder/config.toml. Every field is optional — unset fields fall back to defaults, so you only need to write the lines you care about.

2. Minimal Configuration

A single api_key line is enough to get started (with provider = "auto", providers are auto-detected):

# ~/.youcoder/config.toml
api_key = "sk-your-api-key"

Or explicitly pick a provider and switch models:

provider = "deepseek"
api_key = "sk-deepseek-key"
primary_models = ["deepseek-v4-flash"]

3. Model Providers

Field	Type	Default	Description
provider	string	"auto"	Provider ID: anthropic / openai / deepseek / gemini / zhipu / minimax / xiaomi / auto
api_key	string	empty	Provider API key (env vars also work, see §9)
base_url	string	none	Base URL override (self-hosted gateway / compatible endpoint)
max_tokens	integer	8192	Max tokens per response
primary_models	array	["claude-sonnet-4-20250514"]	Primary model pool (same provider); first entry is the default
secondary_model	string	none	Fallback model (same provider)
secondary_provider	string	none	Cross-provider fallback (e.g. DeepSeek primary, OpenAI backup)
secondary_api_key	string	none	Fallback provider API key
secondary_base_url	string	none	Fallback base URL
secondary_max_tokens	integer	none	Fallback max tokens

Cross-provider fallback example:

provider = "deepseek"
api_key = "sk-deepseek"
primary_models = ["deepseek-v4-flash"]

secondary_provider = "openai"
secondary_api_key = "sk-openai"
secondary_model = "gpt-4o"

4. Advanced Options

Field	Type	Default	Description
system_prompt	string	none	Custom system prompt prepended to every request
context_compact_threshold	float	0.80	Context-window usage ratio (0.0–1.0) that triggers auto-compaction
context_young_rounds	integer	2	Recent conversation rounds always kept in full
context_window_override	integer	none	Manually override the context window size (overrides provider auto-detection)
search_provider	string	"duckduckgo"	Search provider: duckduckgo / bing
search_base_url	string	none	Custom search API base URL (self-hosted / alternative endpoint)
proxy_url	string	none	HTTP proxy, e.g. "http://127.0.0.1:7890"
no_proxy	string	none	Comma-separated hosts bypassing the proxy (NO_PROXY convention)
browser_path	string	none	Browser executable path (unset = auto-detect Chromium-based browsers)
chrome_headless	bool	true	Run browser_fetch in headless mode
max_file_backups	integer	10	Max backups kept per file (recoverable via undo_file)

Proxy and context example:

proxy_url = "http://127.0.0.1:7890"
no_proxy = "localhost,127.0.0.1,.internal"

context_compact_threshold = 0.75
context_young_rounds = 3
max_tokens = 16384

5. Embedding

Optional third retrieval channel for semantic code search. Supports Ollama (local) and OpenAI-compatible endpoints:

[embedding]
enabled = true
provider = "ollama"          # "ollama" | "openai"
model = "nomic-embed-text"   # e.g. ollama's nomic-embed-text
base_url = "http://localhost:11434"
# api_key = "sk-..."         # required for OpenAI-compatible endpoints
dimension = 768              # nomic-embed-text is 768
batch_size = 10              # batch size for background embedding

Field	Type	Default	Description
enabled	bool	false	Enable vector search
provider	string	empty	"ollama" / "openai"
model	string	empty	Embedding model name
base_url	string	empty	API address, e.g. "http://localhost:11434"
api_key	string	none	Key for OpenAI-compatible endpoints (optional)
dimension	integer	768	Embedding vector dimension
batch_size	integer	10	Embedding batch size

6. Command Execution Safety

Controls the safety policy for command-execution tools like exec_shell:

[tools.exec]
# security: relaxed (default) | allowlist | deny
security = "allowlist"

# ask: on-denied (default) | on-every-command
ask = "on-denied"

# allowlist — matching commands run without approval, others need confirmation
allowlist = [
    "cargo",          # prefix match: cargo build / cargo test ...
    "npm run *",      # wildcard match: npm run build / npm run test ...
    "git",            # git status / git add / git commit ...
    "python", "python3", "pip", "pip3",
    "ls", "cat", "echo", "grep", "find",
    "cp", "mv", "mkdir", "touch", "chmod",
    "rm",             # note: rm -rf / is still blocked independently as dangerous
]

Field	Type	Default	Description
security	string	"relaxed"	"deny" (disabled) | "allowlist" (whitelist) | "relaxed" (permissive)
ask	string	"on-denied"	"on-denied" (confirm only when denied) | "on-every-command" (confirm every run)
allowlist	array	empty	Commands exempt from approval; supports prefix and wildcard (npm run *) matching

7. MCP Servers

Connect external tools and data sources (databases, file systems, web APIs) via the Model Context Protocol:

[[mcp_servers]]
name = "everything"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]
max_result_size = 50000
# daily_disabled = false   # true → this MCP is only visible in governance mode

Field	Type	Default	Description
name	string	required	MCP server name
command	string	required	Launch command
args	array	[]	Command arguments
max_result_size	integer	50000	Max characters of a tool result; 0 = unlimited
daily_disabled	bool	false	When true, this MCP's tools are only visible in governance mode

8. Full Example

A complete example covering common scenarios:

# ===== Model =====
provider = "deepseek"
api_key = "sk-deepseek-key"
base_url = "https://api.deepseek.com"   # optional, DeepSeek default
max_tokens = 8192
primary_models = ["deepseek-v4-flash"]

secondary_provider = "openai"
secondary_api_key = "sk-openai-key"
secondary_model = "gpt-4o"

# ===== Context & advanced =====
system_prompt = "You are a rigorous Rust engineer."
context_compact_threshold = 0.80
context_young_rounds = 2

# ===== Network =====
# proxy_url = "http://127.0.0.1:7890"
# no_proxy = "localhost,127.0.0.1"
search_provider = "duckduckgo"

# ===== Embedding (optional) =====
[embedding]
enabled = false
provider = "ollama"
model = "nomic-embed-text"
base_url = "http://localhost:11434"

# ===== Command execution safety =====
[tools.exec]
security = "allowlist"
ask = "on-denied"
allowlist = ["cargo", "git", "npm run *", "python3", "ls", "cat", "echo"]

# ===== MCP servers (optional) =====
[[mcp_servers]]
name = "everything"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]

9. Environment Variables

Every config option can be overridden with YOUCODER_* env vars (higher priority than config files). API keys also accept provider-specific variables:

Environment variable	Config option
YOUCODER_API_KEY (or ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY / GEMINI_API_KEY / ZHIPU_API_KEY / MINIMAX_API_KEY / XIAOMI_API_KEY)	api_key (setting one auto-switches provider)
YOUCODER_PROVIDER	provider
YOUCODER_BASE_URL	base_url
YOUCODER_MAX_TOKENS	max_tokens
YOUCODER_CONTEXT_COMPACT_THRESHOLD	context_compact_threshold
YOUCODER_CONTEXT_YOUNG_ROUNDS	context_young_rounds
YOUCODER_CONTEXT_WINDOW	context_window_override
YOUCODER_SEARCH_PROVIDER / YOUCODER_SEARCH_BASE_URL	search_provider / search_base_url
YOUCODER_PROXY_URL / YOUCODER_NO_PROXY	proxy_url / no_proxy
YOUCODER_BROWSER_PATH / YOUCODER_CHROME_HEADLESS	browser_path / chrome_headless
YOUCODER_PRIMARY_MODELS (comma-separated)	primary_models
YOUCODER_SECONDARY_MODEL / YOUCODER_SECONDARY_PROVIDER / YOUCODER_SECONDARY_API_KEY / YOUCODER_SECONDARY_BASE_URL / YOUCODER_SECONDARY_MAX_TOKENS	secondary_* fallback model
YOUCODER_EMBEDDING_PROVIDER / YOUCODER_EMBEDDING_MODEL / YOUCODER_EMBEDDING_BASE_URL / YOUCODER_EMBEDDING_API_KEY	[embedding] (the first two also set enabled = true)
YOUCODER_LICENSE_KEY	license key (activation)

10. FAQ

Issue	Solution
Wrote model = "..." but it has no effect	The model field is deprecated (silently ignored) — use primary_models = ["..."] instead
Config changes don't take effect	Make sure you edited ~/.youcoder/config.toml (user-level), not a project one; restart the session / app to reload; note the GUI settings panel writes web-config.toml, which has the highest priority and overrides same-name keys
"No API key configured"	Check the api_key field and location, or use env vars (see §9)
Tool execution denied	Check [tools.exec] security / allowlist and your perception scope
How to roll back a broken file	Use the undo_file tool to restore backups (count controlled by max_file_backups)