参考

配置项一览

heng-agent 配置文件 config.json 的全部字段：服务商配置档（protocol、base_url、model、密钥、价格、代理、上下文长度……）与 settings 段的启动默认值（权限模式、轮数上限、超时、自动压缩、思考、下一句建议、状态栏……），默认值与哪些只能写在用户配置里。

预计用时: 查阅
适用版本: v0.5.0 及以上

配置文件在哪、怎么改

文件	用途
`~/.heng-agent/config.json`	用户配置：你的服务商、密钥、默认值
`项目根目录/.heng-agent/config.json`	项目配置：这个项目默认用哪个服务商、模型，以及项目的钩子、MCP

后面的覆盖前面的；命令行参数优先于 settings。对话里改：/config set settings.permission_mode plan（键用点号路径，值按 JSON 解析），/config edit 用编辑器打开，加 --project 改项目配置；改错了自动恢复原配置。

文件的最外层有这几段：

段	内容
`default`	启动时默认用哪个服务商配置档
`profiles`	服务商配置档，见下一步
`settings`	启动默认值，见第三步
`hooks`	钩子，见钩子
`mcp_servers`	MCP 服务，见 MCP 服务

profiles：服务商配置档

字段	默认	说明
`preset`		继承一个内置预设（或用户配置里的配置档），只写要改的字段
`protocol`		`anthropic` 或 `openai`
`base_url`		服务地址
`model`		模型名；预设只给建议值，以服务商文档为准
`api_key_env`		从这个环境变量读密钥（推荐）
`api_key`		直接写密钥；只能写在用户配置里
`auth`	`auto`	密钥放哪个请求头：`auto` / `x-api-key` / `bearer`
`context_window`	自动	上下文长度（token）；不写就向服务商查 → 按模型名推断 → 用 `settings.context_window`
`price_in` / `price_out`		每百万 token 的输入 / 输出价格，填了 `/cost` 按金额显示
`price_cache_read` / `price_cache_write`	输入价 × 0.1 / × 1.25	读缓存 / 写缓存的价格
`currency`	`元`	金额单位
`prompt_cache`	`true`	Anthropic 协议开启提示缓存
`proxy`		只管这个服务商的代理，优先于 `settings.proxy`

settings：启动默认值

字段	默认	说明
`permission_mode`	`ask`	权限模式：`ask` / `accept-edits` / `plan` / `auto`
`max_tokens`	`8192`	每次回答最多输出多少 token
`max_rounds`	`50`	一问之内最多调多少轮模型，防止工具调用死循环
`bash_timeout`	`120`	单条命令超时（秒）
`context_window`	`128000`	配置档查不到上下文长度时用的值
`compact_ratio`	`0.8`	输入超过上下文的这个比例就自动压缩历史
`image_preview`	`auto`	附图时画缩略图：`auto`（只在 Windows Terminal 里画）/ `on` / `off`
`notify_after`	`30`	任务跑超过这么多秒，结束时响铃提醒；`0` 关闭
`prompt_suggestions`	`true`	答完给一句灰字的下一句建议
`mcp_tool_search`	`auto`	MCP 工具按需加载：`auto` / `on` / `off`
`thinking`	`false`	思考模式常开
`thinking_budget`	`8000`	思考预算（token），至少 1024
`effort`	不设	思考强度：`low` / `medium` / `high` / `xhigh` / `max`；不设 = 服务的默认
`claude_user_config`	`true`	读 Claude Code 的用户级配置（`~/.claude`）
`claude_hooks_skip`	`[]`	不跑的 Claude Code 钩子：命令里含其中任一段文字就跳过
`update_check`	`true`	每天最多一次后台查新版本，有就在欢迎页提示
`proxy`	不设	代理：不设 = 按 `HTTP_PROXY` 等环境变量；`direct` = 不走代理；或 `http://主机:端口`、`socks5://主机:端口`
`status_line`	不设	状态栏命令，输出替换状态栏第一行；`claude` = 用 Claude Code 配的状态栏

做完是这样

/config set 改一项后立即生效，/status 里能看到当前的权限模式、模型与上下文长度；配置写错时它恢复原文件并告诉你哪一项不对。