配置

Codeg 在两个地方进行配置。桌面应用和 Web 界面通过 设置 界面几乎暴露了所有内容——外观、智能体、版本控制、Web 服务等等。而界面之外的一切——独立的 codeg-server 如何绑定和进行身份验证、数据在磁盘上的位置，以及少数几个高级运行时调节项——则由环境变量控制，这正是本页所要介绍的内容。

使用桌面应用？

你多半用不到本页。请改从 设置 中配置 Codeg——参见参考部分。当你运行 codeg-server，或需要调整界面未暴露的某项内容时，再使用环境变量。

工作原理

codeg-server 从环境变量读取其配置——无论你以何种方式启动它，都可以设置这些变量：在 shell 中内联设置、在 systemd 单元中、在你的 Docker Compose environment: 块中，或用 docker run -e。这里没有配置文件；服务器唯一的持久状态是它的 SQLite 数据库（在桌面端还额外有一个小小的偏好设置文件）。

有两条约定贯穿始终：

• 空值或仅含空白字符的值视为未设置——将采用默认值。
• 数值型调节项将 0 或无法解析的值视为“使用默认值”，除非 0 明确表示禁用（下文会指出）。

核心设置

你在服务器上最可能设置的变量：

变量	默认值	说明
CODEG_PORT	3080	HTTP 和 WebSocket 监听端口。
CODEG_HOST	0.0.0.0	绑定地址——一个 IP、localhost 或带方括号的 IPv6 字面量。0.0.0.0 会在每个接口上暴露它。
CODEG_TOKEN	（随机）	每个请求都需要的访问令牌。若未设置，则会生成一个、保存到数据库，并在启动时打印到 stderr。
CODEG_DATA_DIR	（因操作系统而异——见下文）	数据库、上传文件、日志和密钥的根目录。
CODEG_STATIC_DIR	./web	要提供服务的捆绑 Web 界面所在目录。
CODEG_MCP_BIN	（自动）	当 codeg-mcp 伴生程序不在服务器二进制文件旁边时其所在路径——某些源码构建需要它。没有它，多智能体委派会被静默禁用。

关于 CODEG_HOST 和 CODEG_TOKEN 在网络和 TLS 方面的影响，参见部署。

Codeg 将数据存储在何处

除非你设置 CODEG_DATA_DIR，否则 codeg-server 会把数据保存在平台的数据目录中：

平台	默认数据目录
macOS	~/Library/Application Support/codeg
Linux	~/.local/share/codeg
Windows	%APPDATA%\codeg

桌面应用将同类数据存储在相同位置的 app.codeg 文件夹下。在数据目录中你会找到：

• codeg.db——SQLite 数据库：会话、设置、频道、自动化——实际上就是 Codeg 的全部状态。
• uploads/——从 Web 客户端附加的文件。
• pets/——桌面宠物资源。
• logs/——按天轮转的日志文件（参见日志）。
• tokens.json——服务器的加密密钥存储（git 凭据之类）。在桌面端，这些内容改为存放在你的系统密钥环中，因此该文件仅存在于服务器上。

要备份或迁移一个部署，复制此目录即可。（应用内的备份功能会将相同的状态导出为一个可移植的 .codegbak 归档文件。）

技能存放在数据目录之外

已安装的技能保存在 ~/.codeg/skills/ 下，它遵循 CODEG_HOME（默认 ~/.codeg），而不是 CODEG_DATA_DIR。如果你在服务器上重新定位了数据目录，并希望技能随之迁移，也请设置 CODEG_HOME。当两者都设置时，对于 uploads/、pets/ 和 logs/，CODEG_HOME 也优先于 CODEG_DATA_DIR。

存储限制

默认情况下，上传的唯一上限就是你的磁盘容量。要对其加以约束：

变量	默认值	说明
CODEG_UPLOAD_MAX_TOTAL_BYTES	（无上限）	uploads/ 下所有内容的硬性上限（以字节为单位）——例如 10737418240 表示 10 GiB。未设置、0 或无效值会禁用该上限。
CODEG_UPLOAD_QUOTA_STRICT	（关闭）	当为真值（1 / true / yes / on）时，如果上面的配额已设置但无法解析，则拒绝启动（退出码 2），而不是带着警告回退到“无上限”。当策略要求已配置的配额必须真正生效时使用它。
CODEG_BACKUP_UPLOAD_MAX_BYTES	（无上限）	恢复端点将接受的最大备份归档。

此外，每个单独的附件还被限制在 2 MiB——这是一个固定限制，不可配置。

日志

Codeg 会将按天轮转的日志写入数据目录中的 logs/，并将它们镜像到应用内的查看器中。

变量	默认值	说明
CODEG_LOG	（已保存的级别）	一个 tracing 过滤指令——info、debug，或像 codeg=debug,tower_http=warn 这样的定向设置。优先于 RUST_LOG，并且在其被设置期间，它会锁定界面中的级别选择器。
RUST_LOG	（未设置）	标准的 Rust 日志过滤器。仅当 CODEG_LOG 为空时使用。
CODEG_LOG_MAX_FILES	30	保留的按天轮转日志文件数量。

对于日常使用，你可以改为从界面更改级别——参见设置 → 日志。

代理支持

启动时，Codeg 会对标准的 HTTP_PROXY、HTTPS_PROXY 和 ALL_PROXY 变量（及其小写形式）拍下快照，并将它们传播给它启动的每一个智能体进程。因此，一处代理设置就同时覆盖了 Codeg 以及它所驱动的智能体——这正是为企业网关设计的路径。关于 Codeg 如何处理网络访问，参见隐私与安全。

高级调优

你很少会用到这些——默认值的选择对几乎所有人来说都是合适的。它们决定了空闲的智能体连接和预览服务器在被回收之前会存续多久：

变量	默认值	说明
CODEG_ACP_IDLE_TIMEOUT_SECS	180	空闲这么多秒后回收一个智能体连接。0 会禁用该清理。
CODEG_ACP_SPAWN_HANDSHAKE_TIMEOUT_SECS	60	在放弃之前，等待智能体启动并完成其握手的时长。
CODEG_ACP_BACKGROUND_KEEPALIVE_MAX_SECS	3600	带有未完成后台工作的连接能豁免于空闲清理多长时间。0 会禁用该豁免。
CODEG_OFFICE_WATCH_IDLE_TIMEOUT_SECS	300	空闲这么多秒后回收一个空闲的 Office 实时预览服务器。0 会禁用。

远程工作区同步还暴露了一组并发调节项（CODEG_WORKSPACE_UPLOAD_MAX_CONCURRENCY 及类似变量）；它们的默认值很合理，很少需要更改。

更新监督

当你在 --supervise 下运行服务器时（参见部署），有两个调节项塑造了就地升级的安全网：

变量	默认值	说明
CODEG_UPGRADE_TRIAL_SECS	30	刚升级的服务器必须在此窗口内成功启动，否则将被自动回滚。
CODEG_RESTART_DELAY_MS	2000	升级后监督进程重新启动服务器前的暂停时间（最小 200）。

监督进程会设置 CODEG_SUPERVISED，Docker 镜像会设置 CODEG_RUNTIME=docker，这些都是自动完成的——它们由系统为你管理，而非需要你手动设置的东西。

桌面偏好设置

桌面应用将其设置保存在数据库中，通过设置界面进行管理——但有一个例外。~/.codeg/preferences.json 会在应用窗口启动之前被读取，其中只保存一个字段：

{ "disable_hardware_acceleration": false }

它对应应用设置中的一个开关。只有在遇到导致窗口无法渲染的 GPU 或驱动问题需要恢复时，才手动编辑它——将其设为 true，重新启动，Codeg 就会在不使用硬件加速的情况下启动。codeg-server 从不读取此文件。

智能体自身的设置

Codeg 通过每个智能体自己的环境变量来找到它现有的会话——CLAUDE_CONFIG_DIR、CODEX_HOME、GEMINI_CLI_HOME 等等。如果你已将某个智能体 CLI 指向非默认位置，Codeg 会自动跟随它。完整的映射见支持的智能体。

后续步骤

• 部署——启动、监督和更新 codeg-server。
• 支持的智能体——每个智能体将会话保存在何处，以及 Codeg 所遵循的变量。
• 设置 → 日志——从界面更改日志级别并查看运行日志。