Cheng CLI 安装与配置

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：crates/cheng-cli/src/config.rs、crates/cheng-cli/src/main.rs、deploy/chengos.sh

cheng CLI 是 ChengOS 的终端客户端。它不需要装在服务器上——它跑在你的笔记本上，驱动任何位置的 ChengOS 安装。这正是它的意义：你工作的机器和运行工作流的机器不必是同一台。

安装

如果你安装 ChengOS 时带了 --with ...,cli，那它已经装好了。否则在 deploy/ 下运行向导：

./chengos.sh cli

它会询问这是哪种安装：

1. 本机安装——自动连接 http://127.0.0.1:3000。
2. 远程安装——提示输入服务器地址，例如 https://your-server.example.com。

要让 cheng 在任意目录下都可用，请在交互式菜单中选择安装系统快捷命令，它会把命令软链接到 /usr/local/bin。

配置优先级

配置按从高到低解析。了解这个顺序能省下大量「为什么这个参数没生效」的困惑：

1. 命令行参数
2. 环境变量——CHENG_SERVER_URL、CHENG_TOKEN
3. 配置文件
4. 内置默认值

配置文件位于 $CHENG_CONFIG，默认是 ~/.config/cheng/config.json。

配置文件

{
  "server_url": "https://your-server.example.com",
  "token_file": "~/.config/cheng/token",
  "default_workspace": "Default Workspace",
  "default_workflow": "main_chat",
  "workspace_mode": "server_local",
  "auth_storage": "auto",
  "request_timeout_secs": 30
}

默认值：server_url 为 http://localhost:3000，default_workspace 为 Default Workspace，default_workflow 为 main_chat，request_timeout_secs 为 30。

令牌

CLI 对 bearer 令牌处理得很谨慎：永远不回显、不写入 REPL 历史、不写入项目文件。 持久化令牌是一个显式选择，并且只会写进用户级配置文件——可以内联为 token，更好的做法是用 token_file 指向一个只含令牌的文件。

更推荐的方式是使用 CHENG_TOKEN 环境变量，根本不做持久化存储。

--auth-storage 选择存储策略：auto、keyring（操作系统钥匙串）、host-bound、encrypted-file、file 或 none。auto 会选择你的系统上可用的最强选项，在桌面环境中通常是钥匙串。

服务端的沙箱前置条件

有一个要求容易被忽略，而且会产生令人困惑的失败：服务器上必须设置 CHENG_CLI_ALLOWED_ROOTS。 它是一个冒号分隔的绝对路径列表，指定可用作 CLI 沙箱的目录，而未配置时 CLI 会话会被完全禁用。

另外，CLI 和 API 必须在同一文件系统命名空间中看到这些路径。一个在你笔记本上和在 Docker 容器内含义不同的路径是不行的——这也是沙箱显示为空或缺失时的常见原因。

工作区模式

决定文件和 shell 工具实际在哪里执行：

用 --workspace-mode 按会话设置，或在配置文件中用 workspace_mode 持久设置。

client_local 有自己的一组安全设置，位于配置文件的 workspace_tools 段——shell 执行可以开启或关闭，原始 sh -c 字符串因风险较高而默认关闭，另有超时限制、环境变量白名单和拒绝模式。Git 与测试执行则单独开关。

验证

cheng --version
cheng sessions      # 列出服务器上你的 CLI 会话

如果 sessions 返回认证错误，说明令牌不对或缺失。如果它提示 CLI 会话不可用，说明服务器上没有配置 CHENG_CLI_ALLOWED_ROOTS。

下一步

• 使用 CLI——会话、命令与后台智能体。
• 安装问题排查——当上述步骤不奏效时。