配置文件详解
ChatRoom 的主要运行配置保存在：
~/.chatroom/config.json运行 chatroom init 时会自动创建该文件。默认情况下，配置目录权限为 0700，配置文件权限为 0600。
如果没有通过 --root 指定目录，ChatRoom 默认允许访问：
~/Projects该目录不存在时，chatroom init 会自动创建。
config.json中包含ownerToken。它相当于 ChatRoom 实例的所有者凭据，请不要公开、提交到 Git 仓库或发送给其他人。
完整配置示例
初始化后生成的配置结构如下。ownerToken 会由 ChatRoom 随机生成，下面仅使用占位符表示：
{
"allowedRoots": [
"/home/user/Projects"
],
"dataDir": "/home/user/.chatroom",
"databasePath": "/home/user/.chatroom/chatroom.sqlite",
"server": {
"host": "127.0.0.1",
"port": 8765
},
"auth": {
"localWebAuth": false,
"ownerToken": "<generated-owner-token>",
"mcpPublicBaseUrl": null,
"webPublicBaseUrl": null,
"allowedRedirectHosts": [
"chatgpt.com",
"localhost",
"127.0.0.1"
]
},
"audit": {
"maxPayloadBytes": 524288
},
"process": {
"maxOutputBytes": 524288,
"defaultTimeoutMs": 1800000,
"maxCompletedProcesses": 200
},
"agents": {
"acp": [],
"external": []
}
}ChatRoom 会严格校验配置文件。字段类型错误、端口超出范围或出现未支持的字段时，启动会失败，而不是静默忽略配置错误。
allowedRoots
allowedRoots 定义 ChatRoom 可以打开和管理的项目根目录，也是最重要的文件系统安全边界之一。
默认值：
{
"allowedRoots": ["/home/user/Projects"]
}可以配置多个根目录：
{
"allowedRoots": [
"/home/user/Projects",
"/srv/projects"
]
}ChatRoom 启动时会把这些路径解析为绝对路径。只有位于允许根目录内的项目才能作为普通 Workspace 被 ChatRoom 打开和管理。
修改 allowedRoots 后需要重新启动 ChatRoom。
dataDir
dataDir 是 ChatRoom 的运行数据目录。
默认值：
~/.chatroom例如：
{
"dataDir": "/home/user/.chatroom"
}ChatRoom 管理的 Worktree 等运行数据会保存在这个目录下。除非有明确的数据目录规划，一般不需要修改。
databasePath
databasePath 指定 ChatRoom SQLite 数据库的位置。
默认值：
~/.chatroom/chatroom.sqlite数据库用于保存 Workspace、审计记录、OAuth 状态、Web 会话、Agent 运行记录等持久化状态。
如果配置中省略 databasePath，ChatRoom 会使用：
<dataDir>/chatroom.sqlite也可以使用环境变量临时覆盖：
CHATROOM_DATABASE=/path/to/chatroom.sqlite chatroom serve环境变量的优先级高于配置文件中的 databasePath。
server
server 控制 ChatRoom HTTP 服务监听地址和端口。
默认值：
{
"server": {
"host": "127.0.0.1",
"port": 8765
}
}server.host
默认只监听本机回环地址：
127.0.0.1这是推荐配置。通常应通过 Caddy、Nginx、Cloudflare Tunnel、Tailscale Funnel 等方式把本地服务安全地暴露到公网，而不是让 ChatRoom 直接监听所有网卡。
如果把 server.host 改为非回环地址，例如：
{
"server": {
"host": "0.0.0.0",
"port": 8765
}
}则必须同时启用：
{
"auth": {
"localWebAuth": true
}
}否则 ChatRoom 会拒绝启动。
server.port
默认端口：
8765有效范围为 1 到 65535。
可以通过环境变量临时覆盖：
CHATROOM_SERVER_PORT=9000 chatroom serveauth
auth 控制 WebUI、本地所有者认证以及远程 MCP OAuth 相关行为。
auth.localWebAuth
默认值：
false当 ChatRoom 只监听 127.0.0.1、localhost 或 ::1 时，本地 WebUI 默认不要求登录。
如果 ChatRoom 直接监听非回环地址，必须设置为：
true启用后，WebUI 需要通过 ChatRoom 的所有者认证机制建立会话。
auth.ownerToken
ownerToken 是 ChatRoom 实例的所有者凭据。
chatroom init 会自动生成一个随机 Token，并写入配置文件。例如：
{
"auth": {
"ownerToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}它主要用于：
- ChatGPT 通过 OAuth 连接 ChatRoom 时，在授权页面确认所有者身份；
- 启用 WebUI 身份验证时建立所有者会话；
- 其他需要确认实例所有权的操作。
只要启用了 localWebAuth、mcpPublicBaseUrl 或 webPublicBaseUrl 中任意一项，ownerToken 就不能为空，否则 ChatRoom 会拒绝启动。
如果 Token 泄露，应重新生成并替换，而不是继续使用旧 Token。
auth.mcpPublicBaseUrl
mcpPublicBaseUrl 告诉 ChatRoom：外部用户通过哪个 HTTPS 基础地址访问当前实例的 MCP 服务。
默认值：
null自托管公网 MCP 时，例如：
{
"auth": {
"mcpPublicBaseUrl": "https://mcp.example.com"
}
}对应的 MCP Endpoint 为：
https://mcp.example.com/mcp设置这个字段不会自动创建公网连接或反向代理。你仍然需要自行配置 Caddy、Nginx、Tunnel 等网络入口，把公网 HTTPS 请求转发到 ChatRoom 的本地端口。
如果只在本机使用 ChatRoom，可以保持为 null。
auth.webPublicBaseUrl
webPublicBaseUrl 表示 WebUI 对外提供访问时使用的公网基础地址。
默认值：
null例如：
{
"auth": {
"webPublicBaseUrl": "https://chatroom.example.com"
}
}与 mcpPublicBaseUrl 一样，该配置只声明外部访问地址，不负责建立公网网络连接。
如果 WebUI 不需要公网访问，保持 null 即可。
auth.allowedRedirectHosts
allowedRedirectHosts 是 OAuth 回调地址的 Host 白名单。
默认值：
[
"chatgpt.com",
"localhost",
"127.0.0.1"
]ChatGPT 或其他 OAuth 客户端注册回调地址时，回调 URL 的主机名必须在这个列表中。
远程 OAuth 回调必须使用 HTTPS；只有 localhost、127.0.0.1 和 ::1 等回环地址允许使用 HTTP。
一般使用 ChatGPT 时无需修改该配置。如果需要接入其他 OAuth 客户端，再把对应的回调 Host 明确加入白名单，不建议使用过于宽泛的配置。
audit
audit 控制操作审计记录的保存行为。
audit.maxPayloadBytes
默认值：
524288即 512 KiB。
它限制单条审计事件中输入、输出或错误信息可保存的最大 JSON Payload 大小。超过限制时，ChatRoom 会截断记录，而不是无限制地把大输出写入数据库。
允许范围：
4096 ～ 16777216 bytes即 4 KiB 到 16 MiB。
提高该值会让 WebUI 中的大型输入输出保留得更完整，但也会增加数据库空间占用。
process
process 控制 ChatRoom 托管命令和 PTY 进程时的输出、超时和历史保留策略。
process.maxOutputBytes
默认值：
524288即 512 KiB。
它限制每个受监督进程保存在内存中的标准输出和标准错误大小。超过限制后会保留受控范围内的输出，避免无限增长。
允许范围：
4096 ～ 67108864 bytes即 4 KiB 到 64 MiB。
process.defaultTimeoutMs
默认值：
1800000即 30 分钟。
这是没有单独指定超时时间时，ChatRoom 启动命令使用的默认超时。
允许范围：
1000 ～ 86400000 ms即 1 秒 到 24 小时。
process.maxCompletedProcesses
默认值：
200控制运行时最多保留多少条已结束进程记录。
允许范围：
0 ～ 10000设置为 0 表示不保留已完成进程的运行时历史。
agents
开发中
Agent 配置功能目前仍在开发中，当前版本暂不提供支持。以下内容仅用于说明预留的配置结构，请暂时不要依赖或使用该功能。
agents 是高级配置，用于注册 ACP Agent 或普通外部 CLI Agent。
默认配置：
{
"agents": {
"acp": [],
"external": []
}
}普通使用 ChatRoom 的 MCP 文件、Git、进程和 Worktree 功能时，不需要配置这里。
ACP Agent
示例：
{
"agents": {
"acp": [
{
"name": "example-acp",
"command": "example-acp-agent",
"args": [],
"permissionPolicy": "deny",
"capabilities": {
"filesystem": "read",
"process": "none",
"network": "denied"
}
}
],
"external": []
}
}字段说明：
| 字段 | 说明 |
|---|---|
name | Agent 在 ChatRoom 中的唯一名称 |
command | 要执行的 ACP Agent 可执行文件 |
args | 启动 Agent 时附加的命令行参数 |
permissionPolicy | ACP 权限请求策略，可选 deny 或 allow-once |
capabilities.filesystem | 文件能力声明：none、read、write |
capabilities.process | 进程能力声明：none、execute |
capabilities.network | 网络能力声明：denied、allowed |
permissionPolicy: "deny" 会拒绝 ACP Agent 发起的权限请求；allow-once 只会自动选择 ACP 提供的单次授权选项，不会授予持久权限。
External CLI Agent
external 用于把普通命令行程序注册为 Agent Provider。例如：
{
"agents": {
"acp": [],
"external": [
{
"name": "my-agent",
"command": "my-agent-cli",
"args": ["--mode", "chat"],
"capabilities": {
"filesystem": "read",
"process": "none",
"network": "denied"
}
}
]
}
}ChatRoom 启动 Agent 时会在对应 Workspace 根目录运行该命令，并把 Prompt 作为最后一个命令行参数传入。
capabilities 是该 Provider 声明并匹配的能力集合。这里属于高级扩展接口，不建议普通用户在不了解对应 Agent 行为的情况下随意开启更高权限。
环境变量覆盖
ChatRoom 当前支持以下与配置相关的环境变量：
| 环境变量 | 作用 |
|---|---|
CHATROOM_CONFIG | 指定配置文件路径，替代默认的 ~/.chatroom/config.json |
CHATROOM_DATABASE | 覆盖 databasePath |
CHATROOM_SERVER_PORT | 覆盖 server.port |
例如使用另一份配置启动：
CHATROOM_CONFIG=/etc/chatroom/config.json chatroom serve这些覆盖只影响当前进程，不会自动修改原来的 config.json。
修改配置后
ChatRoom 当前在启动时读取配置。修改 config.json 后，应重新启动 ChatRoom：
chatroom serve如果使用 systemd、Docker 或其他进程管理器运行 ChatRoom，则应通过对应的服务管理方式重新启动实例。
可以使用下面的命令检查当前配置是否能够正常加载：
chatroom doctordoctor 会显示当前配置文件路径、允许访问的根目录、数据库路径、监听地址以及公网 MCP/Web 状态等信息。