常见问题 FAQ

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-13 ｜ 来源：根 README.md、deploy/README.md、deploy/.env.example、deploy/config/providers.toml、crates/cheng-core/src/types.rs

最常被问到的问题的简短回答，每条都指向讲细节的那一页。

入门

一句话说，ChengOS 是什么？ 一个可视化、基于节点的工作流系统，面向 AI 驱动的数据处理：你画一张图，它作为 DAG 运行，产出可以发布成应用、对话渠道或 API。见 ChengOS 是什么。

跑起来到底需要什么？ PostgreSQL。这是唯一的硬性依赖。定时和智能体记忆需要 Redis，RAG 需要 Qdrant，两者默认都关闭。见部署模式。

原生还是 Docker？ 试用选原生，正式跑选 Docker。原生配合 DB_INSTALL_MODE=managed-process 完全不需要 root。见原生部署和 Docker 部署。

多久能跑出点东西？ 第一个工作流大约十分钟；再花十五分钟做第一个智能体。

工作流

工作流、节点、连线、执行有什么区别？ 工作流是你保存并做版本的那张图。节点是一步，有类型化的输入输出。连线把输出端口接到输入端口，并定义顺序。执行是一次运行，有自己的记录和轨迹。见核心概念。

为什么我的节点字段不能编辑？ 因为有连线接到它上面了。在输入优先级顺序里，连线压过配置。

我的节点为什么被跳过了？ 入边全部产出 null 的节点会被自动跳过。条件路由正是这么工作的——未选中的分支收到 null 就自行跳过，并向下游级联。

工作流能放进 Git 吗？ 可以。导出 workflow.json；身份与租户信息绝不从文件里读取，因此提交、评审、diff 都是安全的。见工作流版本控制。

编辑器里有可回滚的版本历史吗？ 没有。version 计数器和 change_note 是元数据，不是快照。答案是 Git。

用子流程还是循环容器？ 被调方是有独立身份的可复用工作流时用子流程；只是要对每个 item 重跑同样几个本地节点时用循环容器。见子流程与批量子流程。

智能体

我的智能体毫无动作／不调工具就直接回话。 多半是供应商没有声明 native_tool_calling。在随附的 providers.toml 里，Anthropic 和 Ollama 都没有。见大语言模型供应商错误。

该用智能体还是普通图？ 各步骤确实取决于前面步骤发现了什么时用智能体；顺序你已经知道就用图，因为图更便宜、更快、也可预测。

怎么让它别一直跑下去？ max_iterations 是硬边界，而 task_run_mode: short（默认）会暂停并询问你，而不是悄悄停下。long 模式只在智能体仍在推进时才续预算。见 ReAct 智能体指南。

怎么阻止它做危险的事？ 在动作之前放一道审批门，或者干脆不启用那项能力——Hub 节点的写开关默认关闭，而关着的开关在操作运行之前就会失败。

工具、技能、MCP 服务，三者什么关系？ 工具是一个可调用的函数。技能把一项能力连同说明和 schema 打包。MCP 服务是由另一个进程提供的外部能力。

数据

用文档还是表格？ 文档是面向散文的块树，带按块的优先级和标签。表格是有类型的列加稳定的记录 id。两者都能放心交给模型，但理由不同。

怎么让智能体安全地改文档？ 它本来就是安全的：写入都走 Shadow 会话，逐块暂存并可评审，执行会等待决策。

是不是什么都需要 Qdrant？ 只有 RAG 需要。文档、表格和知识库记录都在 PostgreSQL 里。

该用哪种检索模式？ 先用 economy。召回成为瓶颈时上 power。只有在实测出重排值回其延迟之后，才用 ultimate。

执行

执行有多少个状态？ 八个：pending、running、paused、waiting_for_review、completed、failed、cancelled、timeout。后四个是终态。

执行为什么卡在 waiting_for_review？ 它在等一次审批或评审决策。如果审批卡片的按钮返回 NO_ACTIVE_APPROVAL_WAITER，说明等待者已经不在了，清道夫会把它超时掉——见人工审批与评审。

重试会覆盖失败的那次运行吗？ 不会。重试产生新的执行 id；失败的那次原样留存，作为证据。

轨迹保留多久？ 按工作区配置，已完成和失败的执行各有独立天数，另有归档保留级别。见轨迹、日志与回放。

集成

能从我自己的代码里跑工作流吗？ 能——用 REST API，实时事件用 WebSocket API。

用生成的客户端还是 SDK？ 做对话和网关就用 SDK：它还处理 WebSocket 协议、会话映射和令牌刷新，而这些 OpenAPI 生成器做不出来。

怎么把它接到 WhatsApp 或 Slack？ 建一个渠道，绑定工作流，然后连接。Telegram、Slack Socket Mode 和钉钉不需要公网地址。见即时通讯渠道。

channelId 决定用哪个工作流吗？ 不。工作流在渠道记录上显式绑定。channelId 说明的是消息来自哪个应用。见渠道路由。

运维

必须备份什么？ 数据库和 CREDENTIAL_MASTER_KEY_1。丢了密钥，所有已存凭证都不可恢复——只有数据库备份是恢复不出可用系统的。

前端构建为什么失败？ pnpm build 会执行 gen:pages，它要调用后端来渲染页面。先启动后端。见开发环境搭建。

git status 为什么显示 m chengflow-sdk？ chengflow-sdk 被记录为一个没有 .gitmodules 的裸 gitlink。这是预期行为，不是工作树变脏。

OpenAPI 规范完整吗？ 不完整——它只描述了 28 条路径，是一个精选子集。以 rest/routes.rs 和 REST 总览为准。

能让 CLI 连远程服务器而文件留在本地吗？ 可以，那就是 workspace_mode: client_local，对任何非本地的服务器 URL 它都是自动默认值。见跨设备远程连接。

扩展

怎么加一个节点？ 一个结构体、#[derive(Node)]、类型化的输入输出、一个函数，以及一次带沙箱能力的注册宏调用——未分类的节点是 UnsupportedForCli。见自定义节点开发。

为此要写前端代码吗？ 不用。属性面板是从节点的 JSON Schema 生成的。

共享配置放哪儿？ 全局的 presets.yaml / shortcuts.yaml，工作区文件只用于真正的覆盖。见预设与快捷指令。

下一步

• 安装问题排查——安装出问题时。
• 执行失败排查——运行出问题时。
• 系统总览——各部分如何组合。