cc_server CLI
每个进程标志都可以通过命令行标志或环境变量设置；优先级依次是标志、环境变量、默认值。第三方凭据是例外——见下文。
| 标志 | 环境变量 | 默认值 | 含义 |
|---|---|---|---|
--data-dir |
CC_SERVER_DATA_DIR |
操作系统的按用户应用数据目录（见下文） | 数据库、密钥、模型和缓存的媒体 |
--port |
CC_SERVER_PORT |
9030 |
TCP 端口（0 = 临时端口） |
--bind |
CC_SERVER_BIND |
loopback |
loopback，或 any/all/0.0.0.0 表示所有网络接口（需要 TLS 或 --insecure） |
--repo-roots |
CC_SERVER_REPO_ROOTS |
服务器用户的主目录 | 客户端注册仓库时可以浏览的基准目录，以逗号分隔。超出根目录的浏览会被拒绝 |
--log-level |
CC_SERVER_LOG_LEVEL |
warning |
debug、info、warning 或 error。启动/就绪的日志行始终会打印 |
--server-name |
CC_SERVER_NAME |
本机主机名 | 在选择器、发现和配对界面中显示的名称 |
可达性与 TLS
标题为“可达性与 TLS”的部分| 标志 | 环境变量 | 默认值 | 含义 |
|---|---|---|---|
--tls-cert |
CC_SERVER_TLS_CERT |
未设置 | PEM 证书链。与私钥一起设置时，在进程内提供 wss:// |
--tls-key |
CC_SERVER_TLS_KEY |
未设置 | 与证书匹配的 PEM 私钥 |
--insecure |
CC_SERVER_INSECURE |
关闭 | 允许非环回的明文绑定。仅限在可信网络上、位于终止 TLS 的代理之后使用；配置了 TLS 时会被忽略 |
--public-url |
CC_SERVER_PUBLIC_URL |
根据绑定推导 | 本服务器向已配对客户端公布的 RPC URL。在代理、NAT 或隧道之后请显式设置它——默认值只是对本地绑定的一个猜测 |
--allowed-origins |
CC_SERVER_ALLOWED_ORIGINS |
https://app.usectrl.dev |
允许跨源访问 /rpc 的浏览器源，以逗号分隔。环回和原生客户端始终允许 |
--web-client-url |
CC_SERVER_WEB_CLIENT_URL |
未设置 | 托管式 Web 客户端的源，单点登录回调会跳转回该地址 |
--signaling-url |
CC_SERVER_SIGNALING_URL |
wss://signaling.usectrl.dev |
本服务器加入的中继代理，以便手机在没有直达路径时也能访问到它 |
--mdns |
CC_SERVER_MDNS |
auto |
局域网公布：auto（仅在绑定到环回之外的地址时）、on、off。发现只公布服务器的存在——加入仍需要配对 |
--tunnel |
CC_SERVER_TUNNEL |
off |
受管的隧道提供商：off、cloudflared、ngrok、tailscale。对外暴露需要主动开启 |
--tunnel-binary |
CC_SERVER_TUNNEL_BINARY |
从 PATH 解析 |
显式指定隧道二进制文件的路径 |
--tunnel-sha256 |
CC_SERVER_TUNNEL_SHA256 |
未设置 | 该二进制文件的预期 SHA-256，每次启动前都会校验 |
--tunnel-args |
CC_SERVER_TUNNEL_ARGS |
空 | 隧道调用所需的额外参数，以逗号分隔 |
索引与第三方凭据
标题为“索引与第三方凭据”的部分| 标志 | 环境变量 | 默认值 | 含义 |
|---|---|---|---|
--sandbox |
CC_SERVER_SANDBOX |
on |
当主机提供操作系统原生沙盒时，是否用它包裹智能体运行。这是退出开关，而不是启用开关——见下文 |
--code-index |
CC_SERVER_CODE_INDEX |
on |
后台代码图索引的现场关停开关。设为 off 无需重新构建即可干净启动 |
--code-index-defer |
CC_SERVER_CODE_INDEX_DEFER |
15 |
就绪横幅出现后推迟首次索引扫描的秒数（限制在 0–300） |
--tool-deferral |
CC_SERVER_TOOL_DEFERRAL |
on |
运行框架发出的请求是否只带一小批常驻工具加一份名称索引，其余工具在首次使用时加载。见下文 |
--credential-gate |
CC_SERVER_CREDENTIAL_GATE |
900 |
当凭据无法为某次运行提供服务时，该运行等待人工修复的挂起秒数（限制在 0–3600）。见下文 |
凭据取空值会被视为未设置，因此内置的回退值仍然生效。从源码构建的版本完全不带任何内置凭据。
Google Calendar 和 Klipy GIF 选择器只能通过环境变量配置——不存在 --google-client-id / --klipy-app-key 标志（未知标志会被忽略）。请在环境中（或服务器旁的 .env 文件中）设置 GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET 以及 KLIPY_APP_KEY。留空会禁用该功能，而不会导致启动失败。
--sandbox
标题为“--sandbox”的部分服务器在启动时会对主机探测一次，只要存在可用的后端，就用操作系统原生沙盒包裹智能体的命令执行：macOS 上是 sandbox-exec（Seatbelt），Linux 和 WSL2 上是 bwrap 加 socat。在没有后端的地方——Windows，或缺少这些工具的 Linux 主机——运行会回退到环境净化、命令策略和操作护栏，启动日志会说明当前适用的是哪种状态。
--sandbox off 是针对探测无法察觉的情况的现场关停开关：主机上的沙盒配置本身行为异常。它不需要重新构建，服务器会在整个进程生命周期内记录一条警告，因此这种状态永远不会悄无声息。
--tool-deferral
标题为“--tool-deferral”的部分内置运行框架发出的请求会附带一小批常驻的工具定义，加上其余工具的仅含名称的索引，后者在首次使用时才加载各自的 schema。这把工具块缩减了大约 78%，并让始终可见的集合落在模型能可靠选择工具的区间内。延迟加载的工具自始至终都可以按名称调用，search_tools 也能按意图找到它们。参见工具上下文与提示缓存。
--tool-deferral off 会让每个被准入的工具重新常驻，产生与延迟加载出现之前服务器所发出的完全相同的请求。它是针对无法良好应对两层式工具面的模型的关停开关——只需一个标志，而不必重新构建。它只影响内置运行框架；外部客户端看到的 MCP tools/list 始终是完整目录。
--credential-gate
标题为“--credential-gate”的部分当某次运行所用的提供商凭据缺失或已耗尽时，该运行会被挂起而不是直接失败：操作员会收到提示去修复它，修复后运行便会继续。默认时限为 900 秒（15 分钟），限制在 0–3600 之间。
这个时限被刻意设置得比审批提示长得多：审批是某个人在几秒内做出的决定，而修复凭据意味着打开终端、登录再回来。正是这个上限让无人值守的运行——流水线步骤、cron 触发器、webhook——不必一直等待某个正在睡觉的人。时限一到，运行就会带着它本来就会给出的那条消息失败。
--credential-gate=0 是关停开关：任何运行都不会被挂起，凭据有问题时会像这个闸门出现之前那样直接结束该轮次。
子命令
标题为“子命令”的部分| 命令 | 作用 |
|---|---|
cc_server |
运行服务器，直到收到 SIGINT/SIGTERM |
cc_server pair |
预配一台设备，并打印其 id 和配对密钥。即使服务器正在为某个数据目录提供服务也可安全执行——运行中的服务器无需重启即可接纳该设备 |
cc_server calendar connect --workspace <id> |
通过设备码流程把一个 Google 账户连接到工作区，然后退出 |
cc_server update |
检查、下载并校验更新的独立版本 |
cc_server --version |
打印构建版本和 git SHA——与 /healthz 及 RPC 握手对外公布的身份相同 |
pair
标题为“pair”的部分| 标志 | 默认值 | 含义 |
|---|---|---|
--device |
web-client |
设备 id。平台由它推断得出，因此 --device desktop 会创建一行桌面设备，--device ios/android 会创建一行手机设备；其他任何值都视为 Web |
--label |
平台名称加上本机主机名 | 设备列表中的显示名称 |
--host |
localhost，或绑定到所有接口时的 <this-host> |
要嵌入打印出的 URL 中的主机。请把它设置为客户端实际会拨号访问的局域网 IP 或隧道主机 |
--client-url |
未设置 | 托管式 Web 客户端的源。会额外打印一个可扫描的深层链接和终端二维码 |
pair 也接受核心的 --data-dir、--port 和 --bind 标志：它们决定要写入的数据目录，并影响打印出的服务器 URL（环回时为 ws，--bind any 时为 wss）。对同一个 --device 重新运行 pair 会轮换其密钥，并断开该设备当前的会话。这里签发的凭据永不过期，而应用内配对设置的凭据有效期为 30 天。
update
标题为“update”的部分--apply 会替换当前的安装；只要配置的端口上仍有服务器在应答，该操作就会被拒绝，除非传入 --force。--allow-downgrade 允许降级到更旧的版本。
对于它并不拥有的安装，该命令会直接拒绝，给出的是说明而不是错误：
| 环境 | 检测方式 | 给出的说明 |
|---|---|---|
| 桌面端内嵌的服务器 | CC_EMBEDDED=1 或 CC_BOOTSTRAP_DEVICE_ID |
请改为更新应用——安装程序会替换整棵目录树 |
用 dart run 运行的源码检出 |
脚本路径以 .dart 结尾 |
请用 git 更新 |
| Docker | 容器标记 | 拉取更新的镜像 |
进程生命周期
标题为“进程生命周期”的部分cc_server 会一直运行，直到收到 SIGINT / SIGTERM。还有一个额外的环境变量控制这一点，它由桌面端设置，而不是由你设置：
| 变量 | 作用 |
|---|---|
CC_EXIT_WITH_PARENT=1 |
当父进程退出时，服务器也随之退出，判断依据是父进程关闭了其 stdin 管道的写入端。桌面端会设置它，这样即使应用崩溃，也不会留下一个仍占用数据目录的孤儿服务器 |
只有当你把 cc_server 作为子进程监管、并希望获得同样的保证时，才需要自行设置它。
数据目录结构
标题为“数据目录结构”的部分默认数据目录在 macOS 上是 ~/Library/Application Support/control-center，在 Windows 上是 %APPDATA%\control-center，其他平台上则是 $XDG_DATA_HOME/control-center（否则为 ~/.local/share/control-center）。只有当主目录和应用数据目录都无法解析时，才会使用相对于当前工作目录的 .cc_server。
| 路径 | 内容 |
|---|---|
global.db |
工作区注册表、用户、已配对设备、新闻流和机群队列 |
<workspaceId>/workspace.db |
每个工作区一个数据库——智能体、空间、工单、记忆、代码图 |
<workspaceId>/chat_credentials/ |
聊天机器人令牌，以明文 JSON 保存，因此会随工作区一起迁移 |
secrets.json |
配对密钥、提供商应用身份、按用户区分的令牌和 Google 令牌、SSO（0600） |
backups/<timestamp>/ |
一份安装快照——manifest.json、global.db 以及每个工作区的副本 |
backups/exports/ |
单工作区导出，<workspaceId>-<timestamp>.db |
backups/transfer/ |
备份下载和上传的暂存区；由写入它的路由负责清理 |
models/ |
设备端的嵌入、说话人分离和语音模型 |
meetings/<meetingId>/ |
保留的会议音频 |
rigs/images/ |
导入的机台磁盘镜像（QEMU 桌面界面） |
rigs/smolvm/<rigId>/ |
每个机台的 microVM 运行时状态（代理密钥，0600） |
rigs/smolvm-packs/ |
预先解压的机器包——让机台重复启动变快的缓存 |
rigs/tls/ |
用于机台 HTTPS 的开发域名证书颁发机构（密钥权限 0600） |
rigs/run/<rigId>/ |
QEMU 覆盖层、种子镜像和每台虚拟机的密钥（0600） |