Web 端 Settings

Hawa Code Web 端内置了可视化 Settings（设置）面板，方便你在浏览器中查看和修改常用配置，无需手动编辑 settings.json 文件。

1. 打开设置面板

在 Web 页面顶部工具栏点击 Settings 按钮，即可切换到设置视图；再次点击 Settings 或点击 Close 按钮可关闭面板，返回 Agent Viewer。

2. 界面布局

设置面板分为三个区域：

顶部标题栏：显示当前操作状态，包含 Reset、Save、Close 按钮
左侧导航栏：设置分类列表，点击可切换不同分类
右侧内容区：显示当前分类下的所有配置项

3. 设置分类

设置面板将配置项分为 5 个分类：

3.1 General（通用）

用于管理最常用的全局选项。

配置项	说明
`proxy`	启用/禁用代理
`lazyTool`	启用/禁用工具懒加载，开启后可以减少启动时加载的工具数量
`thinking`	模型思考强度，可选 `off` / `low` / `medium` / `high`，默认 `medium`
`language`	输出语言，默认 `auto`（自动）
`disableSuggestion`	是否禁用建议功能

3.2 Web Server

用于配置 Web 服务本身。

配置项	说明
`Enabled`	是否启用 Web Server
`Port`	Web Server 监听端口，默认 `3210`
`Host`	Web Server 监听地址，默认 `127.0.0.1`

提示：修改 Web Server 端口或地址后，通常需要重启 Web Server 才能完全生效。

3.3 Auto Mode（自动模式）

用于配置自动模式（YOLO 模式）的行为。

配置项	说明
`Enabled`	是否启用自动模式
`Model`	自动模式下分类器使用的模型
`Max Consecutive Denials`	连续被拒绝多少次后回退到人工提示，默认 `3`
`Max Total Denials`	总共被拒绝多少次后回退到人工提示，默认 `20`

3.4 Memory（记忆）

用于配置自动记忆相关功能。

Auto Memory（实时记忆提取）

配置项	说明
`Enabled`	是否启用实时记忆提取
`Min Tokens`	触发记忆提取的最小 token 数
`Min Turns`	触发记忆提取的最小对话轮数
`Team Memory Enabled`	是否启用团队记忆

Auto Dream（自动整合记忆）

配置项	说明
`Enabled`	是否启用 Auto Dream
`Min Hours`	距离上次自动整合的最小小时数
`Min Sessions`	触发整合所需的新会话最小数量

3.5 Advanced（高级）

用于配置环境变量、权限、沙箱和会话摘要等高级选项。

配置项	说明
`env`	环境变量，以键值对形式配置，保存后实时生效
`permissions`	权限配置，JSON 格式，包含允许/禁止/询问的工具列表
`sandbox`	沙箱配置，JSON 格式，控制文件系统、网络和命令权限
`sessionSummary`	会话摘要配置，JSON 格式，控制自动压缩与摘要阈值

注意：permissions、sandbox、sessionSummary 为高级配置，建议在熟悉字段含义后再修改。

4. 编辑配置

不同类型的配置项提供不同的编辑方式：

开关按钮：点击可在 On / Off 之间切换
下拉选择：点击选项框，从列表中选择
文本输入框：直接输入文本内容
数字输入框：直接输入数字，部分字段有最小值限制
对象表单：以多个子字段组合成一个配置对象
键值对编辑器：用于 env 环境变量，可添加、修改、删除键值对
JSON 编辑器：用于 permissions、sandbox、sessionSummary，可直接编辑 JSON 内容，失焦后自动校验格式

5. 保存配置

修改任意配置项后，变更会暂存在面板中
当存在未保存的变更时，Save 按钮变为可用状态
点击 Save，系统会将变更保存到当前项目的配置文件中
保存成功后，顶部会显示 “Settings saved successfully” 提示

注意：当前 Web 端设置面板保存的配置会写入项目级配置（.hcode/settings.json），仅对当前项目生效。

6. 重置未保存的变更

如果你修改了配置但不想保存，可以点击 Reset 按钮，所有未保存的变更都会恢复到上一次保存的状态。

7. 保存失败怎么办

如果保存时顶部出现错误提示，可能的原因包括：

网络连接异常，导致无法连接到后端服务
输入值格式不正确，例如 JSON 编辑器中填写了无效 JSON
输入值不符合校验规则，例如端口不在有效范围内

建议检查输入内容格式，或查看后端日志了解具体原因。

8. 配置生效范围

Hawa Code 的配置分为两个层级：

层级	存储位置	生效范围
用户级	`~/.hcode/settings.json`	对所有项目生效
项目级	`项目目录/.hcode/settings.json`	仅对当前项目生效

Web 端 Settings 面板读取的是合并后的配置，但保存时只写入项目级配置。项目级配置的优先级高于用户级配置。

9. 配置热加载

保存配置后，大部分设置会立即生效，无需重启 Hawa Code。例如：

env 中的环境变量保存后会立即注入当前进程
permissions、sandbox 等配置保存后会立即影响后续操作

但部分配置（如 webServer 的端口、地址）需要重启 Web Server 才能完全生效。

10. 使用建议

首次使用建议只修改 General 中的常用选项
修改 Web Server 配置后，记得确认端口是否被占用
配置 env 环境变量时，键名和值都必须是字符串
编辑 JSON 配置时，注意保持正确的 JSON 语法
不确定含义的高级配置，建议先查阅相关文档或保持默认

11. 常见问题

Q：修改配置后为什么没有立即生效？
A：大部分配置会立即生效，但 Web Server 相关配置通常需要重启服务才能生效。

Q：Web 端修改的配置会影响其他项目吗？
A：不会。Web 端 Settings 面板只写入当前项目的配置文件，不会影响用户级配置或其他项目。

Q：Reset 按钮什么时候出现？
A：当你修改了任意配置项但尚未保存时，Reset 按钮会出现；保存后如果无未保存变更，按钮会自动隐藏。

Q：可以在 Web 端修改用户级配置吗？
A：当前 Web 端 Settings 面板仅支持写入项目级配置。如需修改用户级配置，请手动编辑 ~/.hcode/settings.json 文件。