@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/reference/wizard.md

@@ -0,0 +1,242 @@
+---
+read_when:
+  - 查找特定的向导步骤或标志
+  - 使用非交互模式自动执行新手引导
+  - 调试向导行为
+sidebarTitle: Wizard Reference
+summary: CLI 设置向导的完整参考：每个步骤、标志和配置字段
+title: 设置向导参考
+x-i18n:
+  generated_at: "2026-03-16T06:28:28Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: f6560ef9921e58e4fe7f9b23872c0f8bbf3a0a3c4449d686752fc5b5b50bb216
+  source_path: reference/wizard.md
+  workflow: 15
+---
+
+# 设置向导参考
+
+这是 `quantumclaw onboard` CLI 向导的完整参考。
+有关高层概览，请参阅 [设置向导](/start/wizard)。
+
+## 流程详情（本地模式）
+
+<Steps>
+  <Step title="现有配置检测">
+    - 如果 `~/.quantumclaw/quantumclaw.json` 存在，请选择 **Keep / Modify / Reset**。
+    - 重新运行向导**不会**清除任何内容，除非你明确选择 **Reset**
+      （或传入 `--reset`）。
+    - CLI `--reset` 默认值为 `config+creds+sessions`；使用 `--reset-scope full`
+      可额外移除工作区。
+    - 如果配置无效或包含旧版键，向导会停止，并要求
+      你先运行 `quantumclaw doctor` 再继续。
+    - 重置会使用 `trash`（绝不使用 `rm`），并提供以下范围：
+      - 仅配置
+      - 配置 + 凭证 + 会话
+      - 完整重置（也会移除工作区）
+  </Step>
+  <Step title="模型/认证">
+    - **Anthropic API key**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示输入 key，然后保存以供守护进程使用。
+    - **Anthropic OAuth（Claude Code CLI）**：在 macOS 上，向导会检查钥匙串项目 “Claude Code-credentials”（请选择 “Always Allow”，这样 launchd 启动时就不会被阻塞）；在 Linux/Windows 上，如果存在，则会重用 `~/.claude/.credentials.json`。
+    - **Anthropic token（粘贴 setup-token）**：在任意机器上运行 `claude setup-token`，然后粘贴该 token（你可以为其命名；留空 = default）。
+    - **OpenAI Code (Codex) 订阅（Codex CLI）**：如果 `~/.codex/auth.json` 存在，向导可以重用它。
+    - **OpenAI Code (Codex) 订阅（OAuth）**：浏览器流程；粘贴 `code#state`。
+      - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.2`。
+    - **OpenAI API key**：如果存在则使用 `OPENAI_API_KEY`，否则提示输入 key，然后将其存储到凭证配置文件中。
+    - **xAI（Grok）API key**：提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。
+    - **OpenCode**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，可从 https://opencode.ai/auth 获取），并让你选择 Zen 或 Go 目录。
+    - **Ollama**：提示输入 Ollama base URL，提供 **Cloud + Local** 或 **Local** 模式，发现可用模型，并在需要时自动拉取所选本地模型。
+    - 更多细节： [Ollama](/providers/ollama)
+    - **API key**：为你存储该 key。
+    - **Vercel AI Gateway（多模型代理）**：提示输入 `AI_GATEWAY_API_KEY`。
+    - 更多细节： [Vercel AI Gateway](/providers/vercel-ai-gateway)
+    - **Cloudflare AI Gateway**：提示输入 Account ID、Gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
+    - 更多细节： [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
+    - **MiniMax M2.5**：自动写入配置。
+    - 更多细节： [MiniMax](/providers/minimax)
+    - **Synthetic（Anthropic 兼容）**：提示输入 `SYNTHETIC_API_KEY`。
+    - 更多细节： [Synthetic](/providers/synthetic)
+    - **Moonshot（Kimi K2）**：自动写入配置。
+    - **Kimi Coding**：自动写入配置。
+    - 更多细节： [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
+    - **Skip**：暂不配置认证。
+    - 从已检测到的选项中选择默认模型（或手动输入 `provider/model`）。为了获得最佳质量并降低 prompt injection 风险，请选择你在提供商栈中可用的最强最新一代模型。
+    - 向导会运行模型检查，并在所配置模型未知或缺少认证时发出警告。
+    - API key 存储模式默认为明文 auth-profile 值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。
+    - OAuth 凭证保存在 `~/.quantumclaw/credentials/oauth.json`；auth-profile 保存在 `~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json`（API key + OAuth）。
+    - 更多细节： [/concepts/oauth](/concepts/oauth)
+    <Note>
+    无头/服务器提示：在有浏览器的机器上完成 OAuth，然后将
+    `~/.quantumclaw/credentials/oauth.json`（或 `$QUANTUMCLAW_STATE_DIR/credentials/oauth.json`）复制到
+    Gateway 网关主机上。
+    </Note>
+  </Step>
+  <Step title="工作区">
+    - 默认为 `~/.quantumclaw/workspace`（可配置）。
+    - 为工作区植入智能体引导仪式所需的文件。
+    - 完整工作区布局 + 备份指南： [智能体工作区](/concepts/agent-workspace)
+  </Step>
+  <Step title="Gateway 网关">
+    - Port、bind、auth mode、tailscale 暴露方式。
+    - 认证建议：即使是 loopback，也保留 **Token**，这样本地 WS 客户端也必须进行认证。
+    - 在 token 模式下，交互式设置提供：
+      - **生成/存储明文 token**（默认）
+      - **使用 SecretRef**（可选启用）
+      - 快速开始会在新手引导探测/dashboard 引导期间，跨 `env`、`file` 和 `exec` 提供商重用现有的 `gateway.auth.token` SecretRef。
+      - 如果该 SecretRef 已配置但无法解析，则新手引导会提前失败，并给出明确修复信息，而不是静默降级运行时认证。
+    - 在 password 模式下，交互式设置也支持明文或 SecretRef 存储。
+    - 非交互式 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
+      - 要求新手引导进程环境中存在非空环境变量。
+      - 不能与 `--gateway-token` 组合使用。
+    - 仅当你完全信任每个本地进程时，才禁用认证。
+    - 非 loopback 绑定仍然需要认证。
+  </Step>
+  <Step title="渠道">
+    - [WhatsApp](/channels/whatsapp)：可选 QR 登录。
+    - [Telegram](/channels/telegram)：bot token。
+    - [Discord](/channels/discord)：bot token。
+    - [Google Chat](/channels/googlechat)：服务账号 JSON + webhook audience。
+    - [Mattermost](/channels/mattermost)（插件）：bot token + base URL。
+    - [Signal](/channels/signal)：可选安装 `signal-cli` + 账号配置。
+    - [BlueBubbles](/channels/bluebubbles)：**iMessage 推荐方案**；server URL + password + webhook。
+    - [iMessage](/channels/imessage)：旧版 `imsg` CLI 路径 + 数据库访问。
+    - 私信安全：默认为 pairing。首次私信会发送一个代码；通过 `quantumclaw pairing approve <channel> <code>` 批准，或使用允许列表。
+  </Step>
+  <Step title="Web 搜索">
+    - 选择一个提供商：Perplexity、Brave、Gemini、Grok 或 Kimi（也可跳过）。
+    - 粘贴你的 API key（QuickStart 会自动从环境变量或现有配置中检测 key）。
+    - 使用 `--skip-search` 跳过。
+    - 之后再配置：`quantumclaw configure --section web`。
+  </Step>
+  <Step title="守护进程安装">
+    - macOS：LaunchAgent
+      - 需要已登录的用户会话；无头场景请使用自定义 LaunchDaemon（未随产品提供）。
+    - Linux（以及通过 WSL2 的 Windows）：systemd 用户单元
+      - 向导会尝试启用 lingering：`loginctl enable-linger <user>`，以便 Gateway 网关在注销后仍保持运行。
+      - 可能会提示输入 sudo（会写入 `/var/lib/systemd/linger`）；它会先尝试不使用 sudo。
+    - **运行时选择：** Node（推荐；WhatsApp/Telegram 必需）。**不推荐** Bun。
+    - 如果 token 认证需要 token，并且 `gateway.auth.token` 由 SecretRef 管理，则守护进程安装会验证它，但不会将解析出的明文 token 值持久化到 supervisor 服务环境元数据中。
+    - 如果 token 认证需要 token，但配置的 token SecretRef 尚未解析，则会阻止守护进程安装，并给出可执行指导。
+    - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，则会阻止守护进程安装，直到显式设置 mode。
+  </Step>
+  <Step title="健康检查">
+    - 启动 Gateway 网关（如果需要）并运行 `quantumclaw health`。
+    - 提示：`quantumclaw status --deep` 会在状态输出中添加 Gateway 网关健康探测（需要能访问到 Gateway 网关）。
+  </Step>
+  <Step title="Skills（推荐）">
+    - 读取可用的 Skills 并检查要求。
+    - 让你选择一个 node manager：**npm / pnpm**（不推荐 bun）。
+    - 安装可选依赖（某些在 macOS 上使用 Homebrew）。
+  </Step>
+  <Step title="完成">
+    - 摘要 + 后续步骤，包括可提供额外功能的 iOS/Android/macOS 应用。
+  </Step>
+</Steps>
+
+<Note>
+如果未检测到 GUI，向导会打印用于访问 Control UI 的 SSH 端口转发说明，而不是打开浏览器。
+如果缺少 Control UI 资源，向导会尝试构建它们；回退方式是 `pnpm ui:build`（会自动安装 UI 依赖）。
+</Note>
+
+## 非交互模式
+
+使用 `--non-interactive` 自动化或脚本化新手引导：
+
+```bash
+quantumclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --install-daemon \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+添加 `--json` 可获得机器可读摘要。
+
+在非交互模式中使用 Gateway token SecretRef：
+
+```bash
+export QUANTUMCLAW_GATEWAY_TOKEN="your-token"
+quantumclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice skip \
+  --gateway-auth token \
+  --gateway-token-ref-env QUANTUMCLAW_GATEWAY_TOKEN
+```
+
+`--gateway-token` 和 `--gateway-token-ref-env` 互斥。
+
+<Note>
+`--json` **并不**意味着非交互模式。脚本中请使用 `--non-interactive`（以及 `--workspace`）。
+</Note>
+
+特定提供商的命令示例位于 [CLI Automation](/start/wizard-cli-automation#provider-specific-examples)。
+本参考页用于说明标志语义和步骤顺序。
+
+### 添加智能体（非交互）
+
+```bash
+quantumclaw agents add work \
+  --workspace ~/.quantumclaw/workspace-work \
+  --model openai/gpt-5.2 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+## Gateway 网关向导 RPC
+
+Gateway 网关通过 RPC 暴露向导流程（`wizard.start`、`wizard.next`、`wizard.cancel`、`wizard.status`）。
+客户端（macOS 应用、Control UI）可以渲染这些步骤，而无需重新实现新手引导逻辑。
+
+## Signal 设置（signal-cli）
+
+向导可以从 GitHub releases 安装 `signal-cli`：
+
+- 下载适合的发布资源。
+- 将其存储到 `~/.quantumclaw/tools/signal-cli/<version>/` 下。
+- 将 `channels.signal.cliPath` 写入你的配置。
+
+说明：
+
+- JVM 构建需要 **Java 21**。
+- 在可用时会使用原生构建。
+- Windows 使用 WSL2；`signal-cli` 安装会在 WSL 中遵循 Linux 流程。
+
+## 向导会写入的内容
+
+`~/.quantumclaw/quantumclaw.json` 中的典型字段：
+
+- `agents.defaults.workspace`
+- `agents.defaults.model` / `models.providers`（如果选择了 Minimax）
+- `tools.profile`（本地新手引导在未设置时默认为 `"coding"`；已有的显式值会被保留）
+- `gateway.*`（mode、bind、auth、tailscale）
+- `session.dmScope`（行为细节： [CLI 设置参考](/start/wizard-cli-reference#outputs-and-internals)）
+- `channels.telegram.botToken`、`channels.discord.token`、`channels.signal.*`、`channels.imessage.*`
+- 当你在提示中选择启用时，渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）（名称会在可能时解析为 ID）。
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`quantumclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。
+
+WhatsApp 凭证位于 `~/.quantumclaw/credentials/whatsapp/<accountId>/` 下。
+会话存储在 `~/.quantumclaw/agents/<agentId>/sessions/` 下。
+
+某些渠道以插件形式提供。当你在设置期间选择其中一个时，向导
+会提示先安装它（npm 或本地路径），然后才能配置。
+
+## 相关文档
+
+- 向导概览： [设置向导](/start/wizard)
+- macOS 应用新手引导： [新手引导](/start/onboarding)
+- 配置参考： [Gateway 配置](/gateway/configuration)
+- 提供商： [WhatsApp](/channels/whatsapp)、[Telegram](/channels/telegram)、[Discord](/channels/discord)、[Google Chat](/channels/googlechat)、[Signal](/channels/signal)、[BlueBubbles](/channels/bluebubbles)（iMessage）、[iMessage](/channels/imessage)（旧版）
+- Skills： [Skills](/tools/skills)、[Skills 配置](/tools/skills-config)

package/docs/zh-CN/security/formal-verification.md

@@ -0,0 +1,171 @@
+---
+permalink: /security/formal-verification/
+summary: 针对 QuantumClaw 最高风险路径的机器检查安全模型。
+title: 形式化验证（安全模型）
+x-i18n:
+  generated_at: "2026-02-03T07:54:04Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8dff6ea41a37fb6b870424e4e788015c3f8a6099075eece5dbf909883c045106
+  source_path: security/formal-verification.md
+  workflow: 15
+---
+
+# 形式化验证（安全模型）
+
+本页跟踪 QuantumClaw 的**形式化安全模型**（目前是 TLA+/TLC；根据需要会添加更多）。
+
+> 注意：一些较旧的链接可能引用了以前的项目名称。
+
+**目标（北极星）：** 提供机器检查的论证，证明 QuantumClaw 在明确假设下执行其
+预期的安全策略（授权、会话隔离、工具门控和
+配置错误安全）。
+
+**目前是什么：** 一个可执行的、攻击者驱动的**安全回归测试套件**：
+
+- 每个声明都有一个在有限状态空间上运行的模型检查。
+- 许多声明有一个配对的**负面模型**，为现实的 bug 类别生成反例追踪。
+
+**目前还不是什么：** 证明"QuantumClaw 在所有方面都是安全的"或完整 TypeScript 实现是正确的。
+
+## 模型存放位置
+
+模型维护在一个单独的仓库中：[vignesh07/quantumclaw-formal-models](https://github.com/vignesh07/quantumclaw-formal-models)。
+
+## 重要注意事项
+
+- 这些是**模型**，不是完整的 TypeScript 实现。模型和代码之间可能存在偏差。
+- 结果受 TLC 探索的状态空间限制；"绿色"并不意味着在建模的假设和边界之外也是安全的。
+- 一些声明依赖于明确的环境假设（例如，正确的部署、正确的配置输入）。
+
+## 复现结果
+
+目前，结果通过在本地克隆模型仓库并运行 TLC 来复现（见下文）。未来的迭代可能提供：
+
+- 带有公开产物（反例追踪、运行日志）的 CI 运行模型
+- 用于小型、有界检查的托管"运行此模型"工作流
+
+开始使用：
+
+```bash
+git clone https://github.com/vignesh07/quantumclaw-formal-models
+cd quantumclaw-formal-models
+
+# 需要 Java 11+（TLC 在 JVM 上运行）。
+# 仓库内置了固定版本的 `tla2tools.jar`（TLA+ 工具）并提供 `bin/tlc` + Make 目标。
+
+make <target>
+```
+
+### Gateway 网关暴露和开放 Gateway 网关配置错误
+
+**声明：** 在没有认证的情况下绑定到 loopback 之外可能使远程入侵成为可能 / 增加暴露；令牌/密码可以阻止未认证的攻击者（根据模型假设）。
+
+- 绿色运行：
+  - `make gateway-exposure-v2`
+  - `make gateway-exposure-v2-protected`
+- 红色（预期）：
+  - `make gateway-exposure-v2-negative`
+
+另见：模型仓库中的 `docs/gateway-exposure-matrix.md`。
+
+### Nodes.run 管道（最高风险能力）
+
+**声明：** `nodes.run` 需要（a）节点命令允许列表加上声明的命令以及（b）配置时的实时批准；批准被令牌化以防止重放（在模型中）。
+
+- 绿色运行：
+  - `make nodes-pipeline`
+  - `make approvals-token`
+- 红色（预期）：
+  - `make nodes-pipeline-negative`
+  - `make approvals-token-negative`
+
+### 配对存储（私信门控）
+
+**声明：** 配对请求遵守 TTL 和待处理请求上限。
+
+- 绿色运行：
+  - `make pairing`
+  - `make pairing-cap`
+- 红色（预期）：
+  - `make pairing-negative`
+  - `make pairing-cap-negative`
+
+### 入站门控（提及 + 控制命令绕过）
+
+**声明：** 在需要提及的群组上下文中，未授权的"控制命令"不能绕过提及门控。
+
+- 绿色：
+  - `make ingress-gating`
+- 红色（预期）：
+  - `make ingress-gating-negative`
+
+### 路由/会话键隔离
+
+**声明：** 来自不同对等方的私信不会折叠到同一会话中，除非明确链接/配置。
+
+- 绿色：
+  - `make routing-isolation`
+- 红色（预期）：
+  - `make routing-isolation-negative`
+
+## v1++：额外的有界模型（并发、重试、追踪正确性）
+
+这些是后续模型，围绕真实世界的故障模式（非原子更新、重试和消息扇出）提高保真度。
+
+### 配对存储并发 / 幂等性
+
+**声明：** 配对存储应该在交错情况下也强制执行 `MaxPending` 和幂等性（即"检查然后写入"必须是原子/加锁的；刷新不应创建重复项）。
+
+这意味着：
+
+- 在并发请求下，你不能超过渠道的 `MaxPending`。
+- 对同一 `(channel, sender)` 的重复请求/刷新不应创建重复的活跃待处理行。
+
+- 绿色运行：
+  - `make pairing-race`（原子/加锁的上限检查）
+  - `make pairing-idempotency`
+  - `make pairing-refresh`
+  - `make pairing-refresh-race`
+- 红色（预期）：
+  - `make pairing-race-negative`（非原子 begin/commit 上限竞争）
+  - `make pairing-idempotency-negative`
+  - `make pairing-refresh-negative`
+  - `make pairing-refresh-race-negative`
+
+### 入站追踪关联 / 幂等性
+
+**声明：** 摄入应在扇出过程中保持追踪关联，并在提供商重试下保持幂等。
+
+这意味着：
+
+- 当一个外部事件变成多个内部消息时，每个部分都保持相同的追踪/事件标识。
+- 重试不会导致重复处理。
+- 如果提供商事件 ID 缺失，去重回退到安全键（例如，追踪 ID）以避免丢弃不同的事件。
+
+- 绿色：
+  - `make ingress-trace`
+  - `make ingress-trace2`
+  - `make ingress-idempotency`
+  - `make ingress-dedupe-fallback`
+- 红色（预期）：
+  - `make ingress-trace-negative`
+  - `make ingress-trace2-negative`
+  - `make ingress-idempotency-negative`
+  - `make ingress-dedupe-fallback-negative`
+
+### 路由 dmScope 优先级 + identityLinks
+
+**声明：** 路由必须默认保持私信会话隔离，只有在明确配置时才折叠会话（渠道优先级 + 身份链接）。
+
+这意味着：
+
+- 渠道特定的 dmScope 覆盖必须优先于全局默认值。
+- identityLinks 应该只在明确链接的组内折叠，而不是跨不相关的对等方。
+
+- 绿色：
+  - `make routing-precedence`
+  - `make routing-identitylinks`
+- 红色（预期）：
+  - `make routing-precedence-negative`
+  - `make routing-identitylinks-negative`

package/docs/zh-CN/start/bootstrapping.md

@@ -0,0 +1,9 @@
+---
+summary: 智能体引导流程：首次运行时如何初始化工作区与身份文件
+title: 智能体引导
+sidebarTitle: 引导
+---
+
+# 智能体引导
+
+该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Agent Bootstrapping](/start/bootstrapping)。

package/docs/zh-CN/start/docs-directory.md

@@ -0,0 +1,70 @@
+---
+read_when:
+  - 你想快速访问关键文档页面
+summary: 精选的常用 QuantumClaw 文档链接。
+title: 文档目录
+x-i18n:
+  generated_at: "2026-02-04T17:53:20Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 489085dae583ba0690b1b972f037610313973df95813283069c95a06bdc949fa
+  source_path: start/docs-directory.md
+  workflow: 15
+---
+
+<Note>
+如需查看完整的文档地图，请参阅[文档中心](/start/hubs)。
+</Note>
+
+## 从这里开始
+
+- [文档中心（所有页面链接）](/start/hubs)
+- [帮助](/help)
+- [配置](/gateway/configuration)
+- [配置示例](/gateway/configuration-examples)
+- [斜杠命令](/tools/slash-commands)
+- [多智能体路由](/concepts/multi-agent)
+- [更新与回滚](/install/updating)
+- [配对（私信和节点）](/channels/pairing)
+- [Nix 模式](/install/nix)
+- [QuantumClaw 助手设置](/start/quantumclaw)
+- [Skills](/tools/skills)
+- [Skills 配置](/tools/skills-config)
+- [工作区模板](/reference/templates/AGENTS)
+- [RPC 适配器](/reference/rpc)
+- [Gateway 网关运维手册](/gateway)
+- [节点（iOS 和 Android）](/nodes)
+- [Web 界面（控制面板 UI）](/web)
+- [设备发现与传输协议](/gateway/discovery)
+- [远程访问](/gateway/remote)
+
+## 提供商与用户体验
+
+- [WebChat](/web/webchat)
+- [控制面板 UI（浏览器）](/web/control-ui)
+- [Telegram](/channels/telegram)
+- [Discord](/channels/discord)
+- [Mattermost（插件）](/channels/mattermost)
+- [BlueBubbles (iMessage)](/channels/bluebubbles)
+- [iMessage（旧版）](/channels/imessage)
+- [群组](/channels/groups)
+- [WhatsApp 群消息](/channels/group-messages)
+- [媒体图片](/nodes/images)
+- [媒体音频](/nodes/audio)
+
+## 配套应用
+
+- [macOS 应用](/platforms/macos)
+- [iOS 应用](/platforms/ios)
+- [Android 应用](/platforms/android)
+- [Windows (WSL2)](/platforms/windows)
+- [Linux 应用](/platforms/linux)
+
+## 运维与安全
+
+- [会话](/concepts/session)
+- [定时任务](/automation/cron-jobs)
+- [Webhooks](/automation/webhook)
+- [Gmail 钩子（Pub/Sub）](/automation/gmail-pubsub)
+- [安全](/gateway/security)
+- [故障排除](/gateway/troubleshooting)

package/docs/zh-CN/start/getting-started.md

@@ -0,0 +1,143 @@
+---
+read_when:
+  - 从零开始进行首次设置
+  - 你想用最快的路径开始可用聊天
+summary: 在几分钟内安装 QuantumClaw 并开始你的第一次聊天。
+title: 入门指南
+x-i18n:
+  generated_at: "2026-03-16T06:27:55Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 47583047c1a603c1254d2540846452ad321d12bc7fc3f24e5def9282ee96f415
+  source_path: start/getting-started.md
+  workflow: 15
+---
+
+# 入门指南
+
+目标：以最少的设置，从零开始到完成第一次可用聊天。
+
+<Info>
+最快的聊天方式：打开 Control UI（无需设置渠道）。运行 `quantumclaw dashboard`
+并在浏览器中聊天，或在
+<Tooltip headline="Gateway host" tip="运行 QuantumClaw Gateway 网关服务的机器。">网关主机</Tooltip>
+上打开 `http://127.0.0.1:18789/`。
+文档：[Dashboard](/web/dashboard) 和 [Control UI](/web/control-ui)。
+</Info>
+
+## 前置条件
+
+- 推荐使用 Node 24（Node 22 LTS，目前为 `22.16+`，仍因兼容性而受支持）
+
+<Tip>
+如果你不确定，请使用 `node --version` 检查你的 Node 版本。
+</Tip>
+
+## 快速设置（CLI）
+
+<Steps>
+  <Step title="安装 QuantumClaw（推荐）">
+    <Tabs>
+      <Tab title="macOS/Linux">
+        ```bash
+        curl -fsSL https://quantumclaw.ai/install.sh | bash
+        ```
+        <img
+  src="/assets/install-script.svg"
+  alt="安装脚本流程"
+  className="rounded-lg"
+/>
+      </Tab>
+      <Tab title="Windows（PowerShell）">
+        ```powershell
+        iwr -useb https://quantumclaw.ai/install.ps1 | iex
+        ```
+      </Tab>
+    </Tabs>
+
+    <Note>
+    其他安装方式和要求： [Install](/install)。
+    </Note>
+
+  </Step>
+  <Step title="运行新手引导">
+    ```bash
+    quantumclaw onboard --install-daemon
+    ```
+
+    新手引导会配置认证、Gateway 网关设置和可选渠道。
+    详情请参见 [CLI 新手引导](/start/wizard)。
+
+  </Step>
+  <Step title="检查 Gateway 网关">
+    如果你已安装服务，它应该已经在运行：
+
+    ```bash
+    quantumclaw gateway status
+    ```
+
+  </Step>
+  <Step title="打开 Control UI">
+    ```bash
+    quantumclaw dashboard
+    ```
+  </Step>
+</Steps>
+
+<Check>
+如果 Control UI 能加载，你的 Gateway 网关就已准备就绪，可以使用。
+</Check>
+
+## 可选检查和附加内容
+
+<AccordionGroup>
+  <Accordion title="在前台运行 Gateway 网关">
+    适合快速测试或故障排除。
+
+    ```bash
+    quantumclaw gateway --port 18789
+    ```
+
+  </Accordion>
+  <Accordion title="发送一条测试消息">
+    需要已配置的渠道。
+
+    ```bash
+    quantumclaw message send --target +15555550123 --message "Hello from QuantumClaw"
+    ```
+
+  </Accordion>
+</AccordionGroup>
+
+## 常用环境变量
+
+如果你将 QuantumClaw 作为服务账户运行，或想使用自定义配置/状态位置：
+
+- `QUANTUMCLAW_HOME` 设置用于内部路径解析的主目录。
+- `QUANTUMCLAW_STATE_DIR` 覆盖状态目录。
+- `QUANTUMCLAW_CONFIG_PATH` 覆盖配置文件路径。
+
+完整的环境变量参考： [环境变量](/help/environment)。
+
+## 深入了解
+
+<Columns>
+  <Card title="CLI 新手引导" href="/start/wizard">
+    完整的 CLI 新手引导参考和高级选项。
+  </Card>
+  <Card title="macOS 应用新手引导" href="/start/onboarding">
+    macOS 应用的首次运行流程。
+  </Card>
+</Columns>
+
+## 你将获得什么
+
+- 一个正在运行的 Gateway 网关
+- 已配置好的认证
+- Control UI 访问权限或一个已连接的渠道
+
+## 后续步骤
+
+- 私信安全和批准：[Pairing](/channels/pairing)
+- 连接更多渠道：[Channels](/channels)
+- 高级工作流和源码安装：[Setup](/start/setup)