跳转到主要内容

​
入门指南

目标：尽快从零到第一个可用聊天（使用合理的默认值）。
如果你准备使用钱包、SAT Mining、Fased Network、运营者经济或后续交易/新闻功能，请先阅读仓库风险边界： docs/legal/disclaimer.md。
最快聊天：打开 Control UI（无需先配置渠道）。运行 fased dashboard 并在浏览器中聊天，或在 Gateway 主机上打开 http://localhost:18789/。文档：Dashboard 和 Control UI。
推荐路径：使用 CLI 新手引导向导（fased onboard）。它设置：
  • 模型/认证（推荐 OAuth）
  • Gateway 网关设置
  • 工作区引导
  • 可选钱包和 Mining 钱包角色
  • 托管/远程访问安全选项
  • 可选的后台服务
如果你想要更深入的参考页面，跳转到：向导、设置、配对、安全。

​
0) 前置条件

  • Node 24 推荐，或带内置 node:sqlite 模块的 Node 22.14+
  • pnpm（可选；如果从源代码构建则推荐）
  • 可选网页搜索：在 Control UI 中打开 Agent > Services，配置 web/search 提供商和 API key。CLI 也支持 fased configure --section web。
macOS：如果你计划构建应用，安装 Xcode / CLT。仅用于 CLI + Gateway 网关的话，Node 就足够了。 Windows：使用 WSL2（推荐 Ubuntu）。强烈推荐 WSL2；原生 Windows 未经测试，问题更多，工具兼容性更差。先安装 WSL2，然后在 WSL 内运行 Linux 步骤。参见 Windows (WSL2)。

​
1) 安装 CLI（推荐）

git clone https://github.com/fased-ai/fased.git fased
cd fased
./install.sh
安装程序选项（安装方法、非交互式、从 GitHub）：安装。 Windows：请先使用 WSL2，然后在 Ubuntu 里运行同样的仓库安装命令。

​
2) 运行新手引导向导（并安装服务）

fased onboard --install-daemon
./install.sh 默认会运行新手引导。只有在你用了 ./install.sh --no-onboard、新手引导被中断，或需要重新配置守护进程时，才需要单独运行这条命令。 你将选择：
  • 本地 vs 托管 Gateway
  • 认证：OpenAI/OpenAI Codex、Anthropic 或其他模型提供商；可以用 OAuth 或 API key。
  • 钱包（可选）：Agent、Mining、Vault 角色分离；Fased Network bond 使用 Vault 钱包。
  • 渠道（可选）：Telegram、Discord、WhatsApp 等可以在向导或稍后在 Agent > Channels 完成。
  • 守护进程：后台安装（launchd/systemd；WSL2 使用 systemd）
    • 运行时：Node（推荐；WhatsApp/Telegram 必需）。不推荐 Bun。
  • Gateway 网关令牌：向导默认生成一个（即使在 loopback 上）并存储在 gateway.auth.token。
向导文档：向导

​
凭证：存储位置（重要）

  • **推荐的 Anthropic 路径：**设置 API 密钥（向导可以为服务使用存储它）。如果你想复用 Claude Code 凭证，也支持 claude setup-token。
  • OAuth 凭证（旧版导入）：~/.fased/credentials/oauth.json
  • 认证配置文件（OAuth + API 密钥）：~/.fased/agents/<agentId>/agent/auth-profiles.json
无头/服务器提示：先在普通机器上完成 OAuth，然后将 oauth.json 复制到 Gateway 网关主机。

​
3) 启动 Gateway 网关

如果你在新手引导期间安装了服务，Gateway 网关应该已经在运行： 
fased gateway status
手动运行（前台）： 
fased gateway --port 18789 --verbose
Dashboard（local loopback）：http://localhost:18789/ 如果配置了令牌，将其粘贴到 Control UI 设置中（存储为 connect.params.auth.token）。 ⚠️ **Bun 警告（WhatsApp + Telegram）：**Bun 与这些渠道存在已知问题。如果你使用 WhatsApp 或 Telegram，请使用 Node 运行 Gateway 网关。

​
3.5) 快速验证（2 分钟）

fased status
fased health
fased security audit --deep

​
4) 打开 Control UI 并完成 Agent 设置

fased dashboard
继续在浏览器中设置选定 Agent：
  • Agent > Models：添加提供商 API key 或登录，然后选择 Primary/Fallback/Task 模型。
  • Agent > Skills：创建、审查、安装、配置、编辑并允许该 Agent 使用 Skills。
  • Agent > Services：连接 Gmail、Calendar、GitHub、web/search、browser/media 或自定义 API。
  • Agent > Channels：连接聊天应用并路由到该 Agent。
  • Agent > Memory：启用 session-memory，并查看该 Agent 的 archive/QMD 状态。
  • Agent > Tasks：为该 Agent 创建定时或事件触发任务。
当 Agent > Models 显示可用模型后，打开 Chat，选择同一个 Agent，发送： 
Reply with one sentence: Fased is ready.
如果失败，按顺序检查：
  1. Agent > Models：提供商认证或模型选择
  2. Logs：提供商/运行时错误详情
  3. Advanced > Debug：原始诊断和修复工具

​
5) 可选：连接消息渠道

​
WhatsApp（QR 登录）

fased channels login
通过 WhatsApp → 设置 → 链接设备扫描。 WhatsApp 文档：WhatsApp

​
Telegram / Discord / 其他

向导可以为你写入令牌/配置。如果你更喜欢手动配置，从这里开始： **Telegram 私信提示：**你的第一条私信会返回配对码。批准它（见下一步），否则机器人不会响应。

​
6) 私信安全（配对审批）

默认姿态：未知私信会获得一个短代码，消息在批准之前不会被处理。如果你的第一条私信没有收到回复，批准配对： 
fased pairing list whatsapp
fased pairing approve whatsapp <code>
配对文档：配对

​
从源代码（开发）

如果你正在开发 Fased 本身，从源代码运行： 
git clone https://github.com/fased-ai/fased.git fased
cd fased
pnpm install
pnpm build:app # 构建运行时和 Control UI
./install.sh --no-onboard
fased onboard --install-daemon
如果 fased 命令缺失，请先在仓库目录运行 ./install.sh --no-onboard。pnpm build:app 也会打包 A2UI 资源；如果你只需要运行那个步骤，使用 pnpm canvas:a2ui:bundle。 Gateway 网关（从此仓库）： 
node fased.mjs gateway --port 18789 --verbose

​
7) 验证端到端

在新终端中，发送测试消息： 
fased message send --target +15555550123 --message "Hello from Fased"
如果 fased health 显示”未配置认证”，回到向导设置 OAuth/密钥认证——没有它智能体将无法响应。 提示：fased status --all 是最佳的可粘贴、只读调试报告。 健康探测：fased health（或 fased status --deep）向运行中的 Gateway 网关请求健康快照。

​
下一步（可选，但很棒）