letcode 从用户主目录下的 TOML 文件读取系统配置:
~/.config/letcode/letcode.toml
配置文件支持使用环境变量,也可以使用命令脱机验证格式:
letcode config validate仓库根目录的 letcode.schema.json 使用 JSON Schema(draft-07)描述配置结构。在 letcode.toml 首行加入注释指令,编辑器即可识别并提供补全与校验:
#:schema https://raw.githubusercontent.com/letr007/letcode/main/letcode.schema.jsonTaplo、VS Code 的 Even Better TOML 与 Zed 等编辑器均支持该指令,也可指向本地文件路径。letcode 解析配置时会自动忽略注释。首次启动生成的默认配置已自带该声明。
Schema 检查字段名称、类型、枚举值与必填项,并拒绝未声明的未知字段。
会话运行期间,在终端输入 /config 打开内置的交互式配置编辑器。
- 编辑器按表逐层显示字段。按
Enter或→进入子表,按Esc返回上一级。 - 在字段浏览列表中输入文字,可搜索整个配置中的字段路径。按
Backspace删减搜索词。 - 选中字段后显示当前值、操作提示和本地化说明。凭据字段(如
credential)在列表中脱敏显示。
- 文本和数字字段按
Enter进入编辑,修改后按Enter确认,按Esc取消。数字格式错误时保留输入供继续修改。 - 布尔字段按
Enter切换值。枚举和推理强度字段按Enter展开选项,用↑/↓选择,再按Enter确认。 - 数组字段(如
allowed_models、command)按Enter展开,用a追加元素,用d或Delete删除选中元素。按←或Esc收起列表。 providers、models和mcp等表提供新增条目选项。输入名称后生成新条目的初始字段。
- 字段修改保留在内存草稿中。关闭有未保存改动的编辑器时,可选择保存、丢弃或继续编辑。
- 未编辑字段时,按
Ctrl+S保存。保存前校验整个配置,写回时保留 TOML 注释。 - 配置读取和保存共用文件锁,读取会等待正在进行的写入完成。
- Windows 文件替换失败时保留恢复文件,并在错误中列出临时文件和备份目录路径。替换成功后,备份清理失败只记录警告。
- 配置监听器检测到保存后,在引擎空闲时重载支持热更新的设置。当前路由已从配置删除时,继续保留该会话路由并发出提示。
当 letcode.toml 存在语法错误或非法字段时,TUI 模式在启动阶段进入原地修复流程,输出错误原因并提示按 Enter 调用环境变量 $EDITOR 打开文件,修复保存后重新载入;输入 q 则安全退出。非交互模式(如 --cli、-p 批处理与 acp)保持快速失败并输出错误。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
active_provider |
字符串 | [providers] 下首个服务商 |
当前会话默认使用的模型服务商名称 |
fast_mode |
布尔值 | false |
快速模式初始开关。开启时为受支持的 GPT 模型请求优先服务,运行时偏好保存在 preferences.json 中 |
控制运行环境、文件路径与执行限制:
[global]
sessions_dir = "sessions"
log_file = "logs/combined.log"
tool_timeout_secs = 60
submit_while_running = "insert"
# max_iterations = 64
# max_tool_calls = 128sessions_dir:会话记录存储目录,相对路径按配置文件所在目录解析。log_file:运行日志输出文件,相对路径按配置文件所在目录解析。tool_timeout_secs:常规工具默认超时秒数。shell__exec内部保持独立默认值 300 秒。submit_while_running:活动回合中新输入的处理方式,适用于本地提交与跨实例消息。insert(默认)在下一个工具批次结束时关闭回合并执行该消息,没有工具批次时在回合结束时执行;queue等当前回合结束后执行。max_iterations:单个交互回合内允许的最大循环轮数。省略表示不设限制。max_tool_calls:单个交互回合内允许调用的工具总次数。省略表示不设限制。
[global.compaction]
preserve_recent_tokens = 12000preserve_recent_tokens:执行上下文压缩时,在历史末尾强制保留的 Token 预算。省略时根据当前模型的有效输入上限动态计算。
[global.retry]
enabled = true
max_attempts = 50
max_recovery_attempts = 3
initial_delay_secs = 1
exponential_backoff = true
backoff_multiplier = 2.0
jitter_secs = 1enabled:是否开启物理网络请求重试。max_attempts:未产生可观察副作用前允许的最大网络重试次数,计入首次请求。max_recovery_attempts:模型产生部分输出后,受控恢复迭代的最大重试次数。initial_delay_secs:首次重试前的初始等待秒数;在exponential_backoff = false时作为固定等待间隔。exponential_backoff:是否使用指数退避算法增加等待时间。backoff_multiplier:指数退避乘数。jitter_secs:退避时间的随机抖动范围秒数。
[global.session_archive]
enabled = true
older_than_days = 7enabled:是否在后台归档长期闲置的历史会话。older_than_days:判定会话闲置的天数阈值。归档会话仍可在列表中检索,在执行恢复时自动解压载入。
设置系统执行外部操作时的默认授权级别。
[permissions]
mode = "default" # safe | default | auto | yolomode设置运行模式,支持四种级别。safe为安全模式。每次调用工具前均弹窗请求用户确认。default为默认模式。只读操作直接放行,写入与外部变更请求确认。auto为智能审查模式。由内置的安全审查专家自动裁决操作安全性。yolo为全自动模式。直接执行所有工具调用。
限制特定工具的并发执行策略:
[tools.parallelism]
"fs__read" = "parallel"
"web__fetch" = "exclusive"- 可选值包括
parallel(允许在同批次中重叠并发执行)与exclusive(必须排他单线程执行)。该配置只能收窄工具自身声明的能力,不能强制并发未支持的工具。
接入基于 Model Context Protocol(MCP)协议的外部工具服务:
[mcp.local_server]
enabled = true
timeout = 5000
[mcp.local_server.local]
command = ["/path/to/server", "--stdio"]
environment = { ENV_VAR = "value" }local.command:可执行程序路径及参数列表。必填。local.environment:传递给子进程的环境变量键值对。别名为env。enabled:是否启用该服务,默认为true。也可在会话内使用/mcp快捷切换。timeout:服务响应与方法调用的超时毫秒数,默认为 5000 毫秒。type与顶层command/environment是旧式扁平写法,仅用于兼容已有配置。
[mcp.remote_server]
enabled = true
timeout = 10000
[mcp.remote_server.remote]
url = "https://example.com/mcp"
headers = { Authorization = "Bearer YOUR_TOKEN" }remote.url:远程服务 HTTP/SSE 端点地址。必填。remote.headers:请求时附带的自定义标头。timeout:网络请求超时毫秒数。remote.oauth:远程 MCP 暂不支持 OAuth 授权,必须保持为false。type与顶层url/headers/oauth是旧式扁平写法,仅用于兼容已有配置。
声明模型服务商基础信息与认证参数:
[providers.openai]
protocol = "responses" # responses | completions | anthropic
flavor = "standard" # standard | deepseek
default_model = "gpt-5.5"
[providers.openai.auth]
type = "bearer" # bearer | header | query | none
credential_env = "OPENAI_API_KEY"
[providers.openai.endpoints]
base_url = "https://api.openai.com/v1"protocol:传输协议类型,支持responses、completions与anthropic。flavor:接口特征模式,支持standard或适配 DeepSeek 的deepseek。default_model:未显式指定模型时的默认模型标识。必须是该服务商[models]下已定义的键。reviewer:旧版 Jev 标记,仅用于兼容已有配置。新配置改用[agents.reviewer] backend。headers:附加的固定请求头映射表。query:附加的固定 URL 查询参数映射表。
[providers.openai.transport]
connect_timeout_secs = 10
no_proxy_loopback = trueconnect_timeout_secs:TCP 与 TLS 握手建连超时秒数。no_proxy_loopback:回环地址(如127.0.0.1)是否强制绕过代理。
可选配置。继承 [global.retry] 的未声明字段,用于单独调整特定服务商的重试频率与上限。
[providers.openai.auth]
type = "bearer"
credential_env = "OPENAI_API_KEY"type:认证方案,支持bearer、header、query与none。credential_env:存储 API 密钥的环境变量名。默认值为<PROVIDER>_API_KEY。credential:明文 API 密钥。优先读取credential_env指定的环境变量;环境变量为空时才使用该明文。name:当type为header或query时,携带凭据的标头名或查询参数键名。
[providers.openai.endpoints]
base_url = "https://api.openai.com/v1"
[providers.openai.endpoints.responses]
path = "responses"
query = { api_version = "2026-01-01" }base_url:服务商 API 基础网关地址。- 子表重写:支持配置
responses、completions、anthropic与jev(别名reviewer)子表。每个子表支持path(覆盖默认协议路径,可为绝对路径)与query(追加查询参数)。
在指定服务商下定义模型的推理能力与生成参数:
[providers.openai.models."gpt-5.5"]
display = "GPT-5.5"
context_window = 400000
effective_input_limit_tokens = 256000
[providers.openai.models."gpt-5.5".capabilities]
tools = true
parallel_tool_calls = true
reasoning = true
[providers.openai.models."gpt-5.5".generation]
temperature = 0.2
max_output_tokens = 128000
reasoning_effort = "medium"
reasoning_efforts = ["none", "low", "medium", "high", "max"]display:在 TUI 界面与选择菜单中显示的友好名称。model_override:实际发送给上游网关的真实模型标识;仅在与配置键名不一致时填写。strategy:模型请求封装策略,省略时根据模型名自动推断。context_window:总上下文窗口 Token 容量。effective_input_limit_tokens:有效输入上限 Token 预算。超过该限制后系统启动上下文整理。protocol:单独覆盖该模型所用的传输协议。flavor:单独覆盖该模型所用的接口特征模式。transport.websocket:对于 Responses 协议,是否启用全双工 WebSocket 流式传输。
声明模型具备的基础能力。所有标志默认均为 false:
tools:是否支持工具调用。parallel_tool_calls:是否支持单次响应中并行调用多个工具。reasoning:是否支持输出思考推导过程。input_images:是否支持输入多模态图片。tool_result_images:是否支持工具返回图片并在多轮对话中传回模型。priority_service:是否声明优先级调度服务。structured_output:结构化输出契约,支持json_schema或json_object。
设置常规回合的生成默认参数。协议和模型能力决定哪些参数可用。
temperature:采样温度。top_p:核采样阈值。max_output_tokens:最大单次输出 Token 上限。reasoning_effort:默认推理强度,可选none、minimal、low、medium、high、xhigh、max或服务商自定义名称。要求capabilities.reasoning = true。reasoning_efforts:提供给当前会话选择的推理强度档位列表。reasoning_summary:推理摘要模式,可选auto、concise或detailed。text_verbosity:文本详细程度,可选low、medium或high。parallel_tool_calls:是否开启并行工具调用。要求capabilities.parallel_tool_calls = true。async_tools:异步派发的工具名列表。需要 Astra 策略、Responses 协议且capabilities.tools = true。
声明模型对结构化输出的支持级别:
json_schema:在解码器层硬性约束 JSON 语法有效性。json_object:仅在系统层面表达输出 JSON 意图。
[providers.openai.models."gpt-5.5".cache]
enabled = true
retention = "in_memory" # in_memory | 24h
namespace = "openai"enabled:是否启用服务商原生 Prompt 缓存。retention:缓存保留策略,24h仅部分服务商的 Responses 协议支持。namespace:缓存命名空间划分。
针对特定协议的专属参数:
[providers.anthropic.models."claude-3-7-sonnet".protocol_settings]
anthropic_thinking = { mode = "adaptive", budget_tokens = 16000 }
anthropic_betas = ["context-1m-2025-08-07"]anthropic_thinking:Anthropic 思考参数结构,包含mode(disabled、adaptive、budget)与budget_tokens。anthropic_betas:发送给 Anthropic 接口的 Beta 特性请求头数组。
[subagents]
mode = "swarm" # expert | swarm,默认 expert
max_depth = 3
max_concurrent = 16
max_pending_messages = 16
max_message_bytes = 16384
run_timeout_secs = 600| 配置项 | 默认值 | 说明 |
|---|---|---|
mode |
"expert" |
expert 由父代理委派,子代理不再委派;swarm 支持成员继续委派与同树消息 |
max_depth |
3 |
swarm 最大深度,根为 0,包含上限 |
max_concurrent |
16 |
同一根会话的子代理并发上限,包含启动预约、执行中和消息恢复预约;结束后释放名额 |
max_pending_messages |
16 |
每会话待处理消息数上限,跨 run 交接保留 |
max_message_bytes |
16,384 |
单条消息正文的 UTF-8 字节数上限 |
run_timeout_secs |
600 |
swarm 子 run 未指定请求或模板超时时的默认秒数 |
数值字段必须为正整数,超时还须在运行时可表示的期限范围内。非法模式、未知字段与无效数值会报错。swarm 限制不改变 expert 的运行行为。
配置在新根会话创建时记录,配置重载只影响后续新根会话。恢复使用保存的上限,历史成员不占并发名额。旧字段 max_descendants 兼容读取为 max_concurrent,两者不可同时填写。消息接纳、权限与取消规则见子代理组件。
为特定内置专家指定独立的服务商与模型。配置专家时必须同时填写 provider 与 model:
[agents.explorer]
provider = "openai"
model = "gpt-5.5"
allowed_models = ["openai/gpt-5.5"]
reasoning_effort = "medium"支持配置以下 8 个内置专家:
explorer:代码库只读检索与探索专家。fixer:代码实现与故障修复专家。oracle:根因分析与风险审查专家。designer:系统方案与交互设计专家。librarian:技术资料与上下文归档专家。general:通用任务辅助专家。reviewer是权限安全审查内部专家。historian:会话历史整理与上下文压缩内部专家。
allowed_models:该专家允许使用的路由列表,格式为provider/model。列表第一项作为默认路由;后续项限定单次agent__*委派时可通过参数覆盖的目标模型范围。未配置专家路由时,系统自动回退至全局默认模型。reasoning_effort:该专家每次运行使用的思考强度。所选模型必须支持该档位。backend:仅reviewer使用。chat走普通模型审查;jev调用该 provider 的 Jev 接口,要求auth.type = "bearer"。
在开启 /fake 时伪装请求元数据特征,模拟特定开发工具环境:
[fake.identity]
# installation_id = "..."
# agent_name = "Hypatia"
[fake.clock]
timezone = "Asia/Shanghai"
[fake.codex]
version = "0.167.2"
originator = "Codex Desktop"
sandbox = "none"
sandbox_mode = "danger-full-access"
shell = "zsh"
[fake.claude]
version = "2.1.322"
package_version = "0.128.0"
timeout = "600"[fake.identity]:客户端安装 ID 与代理标识。[fake.clock]:请求模拟使用的 IANA 时区名称。[fake.codex]:Codex 桌面端环境剖面参数。[fake.codex.extra]支持最多 16 个额外的请求元数据键。[fake.claude]:Claude Code 命令行工具剖面参数。
未声明的字段由系统在运行时自动检测当前主机的真实环境补充。详细规范参见客户端特征仿真。
创建 ~/.config/letcode/letcode.toml 并写入以下内容即可启动:
#:schema https://raw.githubusercontent.com/letr007/letcode/main/letcode.schema.json
active_provider = "openai"
[permissions]
mode = "default"
[providers.openai]
protocol = "responses"
default_model = "gpt-5.5"
[providers.openai.auth]
type = "bearer"
credential_env = "OPENAI_API_KEY"
[providers.openai.endpoints]
base_url = "https://api.openai.com/v1"
[providers.openai.models."gpt-5.5"]
display = "GPT-5.5"
[providers.openai.models."gpt-5.5".capabilities]
tools = true
reasoning = true
[providers.openai.models."gpt-5.5".generation]
reasoning_effort = "medium"src/config.rs:配置结构定义、默认值与加载校验逻辑。src/config/persistence.rs:配置文件保格式读写、Schema 字段提取与原子落盘。src/config/schema.rs:内置 JSON Schema 解析与字段元数据查询。src/tui/runtime.rs:/configTUI 配置编辑器交互处理与状态管理。src/tui/recover.rs:启动阶段错误配置文件交互式修复入口。