配置文件路径

用户级别配置文件：~/.hcode/settings.json
项目级别配置文件：项目根目录下的 .hcode/settings.json

配置说明

属性名称	作用	是否支持热加载
env	环境变量配置，用于设置系统级别的环境变量，参考环境变量章节	是
language	界面语言设置，配置 Hawa Code 的默认回复语言	是
disableSuggestion	禁用提示词建议	是
permissions	权限配置，参考权限配置章节	是
sandbox	沙箱配置，具体参考沙箱配置章节	否
autoCompactEnabled	启用会话自动压缩，默认值为 true	是
sessionSummary	会话摘要配置, 参考会话摘要章节	是
autoMemory	会话记忆自动提取, 参考会话记忆自动提取章节	是
autoDream	会话记忆自动整合, 参考会话记忆自动整合章节	是
autoMode	自动工具授权模式, 参考工具自动授权章节	是

配置示例

{
  "env": {
    "HAWA_CODE_LAZY_TOOL": false,
    "HAWA_CODE_FIX_SCHEMA": true
  },
  "permissions": {
    "allow": [
      "Bash(git branch:*)",
      "Bash(git status:*)",
      "mcp_notion_*"
    ],
    "deny": [
      "Read(./settings/**)"
    ]
  },
  "language": "chinese"
}

环境变量

通过 env 配置项可以设置系统级别的环境变量，这些变量会影响 Hawa Code 的运行行为。

属性	描述	示例
HAWA_CODE_LAZY_TOOL	工具懒加载开关	false
HAWA_CODE_FIX_SCHEMA	工具调用入参的兼容性修复选项	true
HAWA_CODE_USER_AGENT	自定义 HTTP 请求的 User-Agent 字符串	“MyCustomAgent/1.0”
HAWA_CODE_AUTH_DISABLED	禁用 Authentication HTTP 请求 Header	true
HAWA_CODE_X_API_KEY_DISABLED	禁用 x-api-key HTTP 请求 Header	true
HAWA_CODE_OPENAI_IMAGE_DETAIL	设置 OpenAI 图片分辨率级别，可选值：”low”、”high”、”auto”、”original”，默认为 auto	“high”
HTTPS_PROXY	设置 HTTPS 代理地址	“http://127.0.0.1:7890“
HTTP_PROXY	设置 HTTP 代理地址	“http://127.0.0.1:7890“

权限配置

属性名称	作用	是否支持热加载
permissions.allow	权限配置，定义允许调用的工具	是
permissions.ask	权限配置，工具执行的时候需要人工授权确认	是
permissions.deny	权限配置，定义禁止调用的工具	是
permissions.disableBypassPermissionsMode	设置为 “disable” 以防止激活 bypassPermissions 模式	是

权限配置规则

权限规则遵循 Tool 或 Tool(specifier) 的格式。规则优先级：deny > ask > allow 。使用第一个匹配的规则

规则	效果
Bash	匹配所有 Bash 命令
Bash(npm test *)	匹配以 npm test 开头的命令
Read(./.md)	匹配读取 .md 文件
WebFetch(domain:test.com)	匹配对 test.com 的获取请求

有关完整的规则语法参考，包括通配符行为、Read、Edit、WebFetch、MCP 和 Agent 规则的工具特定模式，以及 Bash 模式的安全限制，请参阅权限规则语法。

沙箱配置

配置高级沙箱行为。沙箱将 bash 命令与您的文件系统和网络隔离。请参阅沙箱了解详情。

属性	描述	示例
enabled	启用 bash 沙箱，支持的系统有 macOS、Linux 和 WSL2 。默认：false	true
autoAllowBashIfSandboxed	启用沙箱时候 bash 命令不要人工确认。默认：true	true
excludedCommands	可以绕过沙箱运行的命令	[“git”, “docker”]
allowUnsandboxedCommands	允许命令通过 dangerouslyDisableSandbox 参数在沙箱外运行。当设置为 false 时，dangerouslyDisableSandbox 不能生效，不在 excludedCommands 中的所有命令必须沙箱化。默认：true	false
filesystem.allowWrite	沙箱命可以写入的文件路径，user、project setting 文件配置合并，同时也于 Edit(…)、Write（…）允许权限规则中的路径合并。请参阅下面的路径前缀。	[“//dev/ccr”, “~/.hcode”]
filesystem.denyWrite	沙箱命令禁止写入的路径。user、project setting 文件配置合并。也与 Edit(…)、Write（…）拒绝权限规则中的路径合并。	[“//etc”, “//usr/test”]
filesystem.denyRead	沙箱命令禁止读取的路径。user、project setting 文件配置合并。也与 Read(…) 拒绝权限规则中的路径合并。	[“~/dev/cre”]
filesystem.allowRead	沙箱命令允许读取的路径。user、project setting 文件配置合并。也与 Read(…) 允许权限规则中的路径合并。	[“~/dev/cre”]
network.allowedDomains	沙箱命令允许访问的域名。支持通配符（例如 *.example.com）。	[“github.com”, “*.npmjs.org”]
network.deniedDomains	沙箱命令禁止访问的域名。支持通配符（例如 *.example.com）。	[“github.com”, “*.npmjs.org”]
network.allowUnixSockets	沙箱中可访问的 Unix 套接字路径（用于 SSH 代理等）	[“~/.ssh/code-socket”]
network.allowLocalBinding	允许绑定到 localhost 端口（仅 macOS）。默认：false	true

沙箱配置示例

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "filesystem": {
      "allowWrite": ["//tmp/", "~/.hcode"],
      "denyRead": ["~/.ct/caa"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
       "deniedDomains": ["evil.example.com"],
      "allowLocalBinding": true
    }
  }
}

会话摘要

当 autoCompactEnabled 设置为 true 时，会启用会话自动压缩功能。当上下文窗口快占满时，Hawa Code 会自动对会话消息进行压缩，从而保证 Hawa Code 能够长时间运行。会话压缩是一次性完成的，压缩过程相对耗时。

sessionSummary 用于配置会话摘要功能，Hawa Code 会在对话过程中异步对当前会话进行增量摘要总结。

摘要文件存储路径为 ~/.hcode/projects/{项目名称}/messages/{会话ID}/session-summary/summary.md

属性	描述	示例
enabled	启用会话摘要，默认：false	true
config.minimumMessageTokensToInit	首次执行摘要时会话最小 token 数量，默认：10000	10000
config.minimumTokensBetweenUpdate	多次执行摘要时会话最小 token 增量，默认：5000	5000
config.toolCallsBetweenUpdates	多次执行摘要时会话最少工具调用增量，默认：3	3

会话记忆自动提取

autoMemory 会在对话过程中自动提取关键信息并保存为记忆，无需手动维护 HAWA.md 或 rules 配置。

属性	描述	示例
enabled	启用自动记忆提取，默认：false	true
minTokens	首次提取及后续多次提取的最小 token 增量，默认：3000	3000
minTurns	触发提取所需的最小对话轮次，默认：3	3

会话记忆自动整合

autoDream 会定期对自动提取的记忆进行整合、去重和过期清理。使用该功能前需先开启 autoMemory。

属性	描述	示例
enabled	启用会话记忆自动整合，默认：false	true
minHours	两次整合之间的最小时间间隔（小时），默认：24	24
minSessions	触发整合所需的最少新增会话数，默认：5	5

工具自动授权

启用 autoMode 后，Hawa Code 会自动判断工具是否允许执行，实现无人值守的自动授权模式。

设置环境变量 HAWA_CODE_AUTO_MODE_ACCEPTEDITS = "1" 后，Hawa Code 会自动放行 acceptEdits 允许执行的工具。该设置可减少模型请求次数，但会默认授权更多工具，请根据实际需求权衡是否开启。

属性	描述	示例
enabled	是否启用 auto 模式，默认：false	true
maxConsecutiveDenials	连续拒绝多少次后回退到人工提示，默认：3	3
maxTotalDenials	总共拒绝多少次后回退到人工提示，默认：20	5