macOS/Linux快速安装Craft Agents：5分钟从零到第一个AI会话完整指南-酒店常州论坛

macOS/Linux快速安装Craft Agents：5分钟从零到第一个AI会话完整指南

【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss

Craft Agents 是一款开源 AI 智能体桌面应用，主打多会话收件箱、多模型连接（Anthropic、Google AI Studio、ChatGPT 等）、MCP 数据源接入与文档中心工作流。本文将带你用一行命令完成 macOS/Linux 安装，并在 5 分钟内发起你的第一个 AI 会话。

⚡ 30秒了解：Craft Agents 能做什么

在动手安装前，先看看这款 AI Agent 工具的核心能力：

多会话收件箱：会话按状态流转（Todo → In Progress → Done），支持置顶、归档与 AI 自动命名
多模型自由切换：Anthropic API Key / Claude Max、Google AI Studio、ChatGPT Plus、GitHub Copilot 均可接入
即连即用：直接告诉 Agent「接入 Slack」，它会自行查找 API、读取文档并完成配置，无需手写配置文件
文件附件：拖入图片、PDF、Office 文档，自动转换供模型理解
三档权限控制：Explore（只读）/ Ask to Edit（默认）/ Auto（自动放行），SHIFT+TAB一键切换

🚀 一键安装：macOS/Linux 通用命令

官方提供了一行安装脚本，自动检测系统（macOS / Linux）与 CPU 架构（arm64 / x64），下载对应安装包并校验 SHA-512 后完成安装：

curl -fsSL https://agents.craft.do/install-app.sh | bash

脚本源码位于scripts/install-app.sh，可先阅读再执行，安全透明。

macOS 与 Linux 的安装差异一览：

项目	macOS	Linux
安装包	ZIP（内含 .app）	AppImage（目前仅支持 x64）
安装位置	`/Applications/Craft Agents.app`	`~/.craft-agent/app/`
启动方式	应用程序文件夹，或`open -a 'Craft Agents'`	终端输入`craft-agents`
额外依赖	无	需要 FUSE 组件

macOS 脚本会自动移除隔离属性（quarantine），首次打开不会触发系统拦截；Linux 若缺少 FUSE，按提示安装即可：

sudo apt install fuse libfuse2 # Debian/Ubuntu

🛠 从源码构建：clone 仓库完整步骤

如果你想体验最新功能或参与开发，从源码构建只需 4 步（需要 Bun 运行时，如未安装可访问 bun.sh 获取）：

git clone https://gitcode.com/GitHub_Trending/cr/craft-agents-oss cd craft-agents-oss bun install bun run electron:start

桌面应用源码位于apps/electron/，架构说明见apps/electron/README.md；日常开发推荐热重载模式bun run electron:dev。

🔑 首次启动：连接 AI 并创建第一个工作区

安装完成后启动应用，按向导操作 4 步即可：

选择 API 连接：新手推荐 Anthropic（API Key 或 Claude Max 登录）；已有 ChatGPT Plus / Copilot 订阅也可直接 OAuth 登录
创建工作区（Workspace）：工作区用于组织会话，还能为其单独设置默认模型与主题
连接数据源（可选）：支持 MCP 服务器、REST API（Gmail、Slack 等）与本地文件目录
开始对话：新建会话，发出你的第一句话

💬 创建你的第一个 AI 会话

进入主界面后，几个高频操作帮你快速上手：

快捷键	功能
`Cmd+N`（Linux 为`Ctrl+N`）	新建会话
`Enter`/`Shift+Enter`	发送消息 / 换行
`SHIFT+TAB`	切换权限模式
`Cmd+/`	打开全部快捷键列表

会话支持拖拽图片、PDF 等附件（自动转换后交给模型处理），例如拖入一张风景照让 Agent 描述画面内容：

默认权限模式为Ask to Edit，Agent 执行写操作前会弹出确认框，新手可安心使用；熟悉后再切到 Auto 模式提升效率。

⌨️ 进阶：命令行 10 秒验证环境

仓库自带终端客户端，run命令完全自包含——自动拉起无头服务器、创建会话、流式输出响应后退出，无需任何额外配置：

ANTHROPIC_API_KEY=sk-xxx bun run apps/cli/src/index.ts run "Hello, world!"

更多 CLI 用法（会话管理、流式发消息、21 步服务器体检）可查阅 docs/cli.md。

📁 你的数据都存放在哪里

所有配置与会话数据统一保存在~/.craft-agent/目录：

config.json— 工作区与 LLM 连接配置
credentials.enc— 凭据文件（AES-256-GCM 加密存储）
workspaces/— 各工作区的会话记录、数据源与技能（Skills）

🩺 常见问题排查

症状	原因	解决方法
Linux 启动后闪退	缺少 FUSE	`sudo apt install fuse libfuse2`
提示`craft-agents: command not found`	`~/.local/bin`未加入 PATH	`echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc`后重开终端
macOS 首次打开被拦截	系统隔离属性	重新执行安装脚本会自动处理
无法与 AI 对话	未配置 API 连接	进入设置页填写 API Key 或完成 OAuth 登录

遇到其他问题时，可开启调试模式查看详细日志：

# macOS /Applications/Craft\ Agents.app/Contents/MacOS/Craft\ Agents -- --debug # Linux ./craft-agents -- --debug

日志位置：macOS 为~/Library/Logs/@craft-agent/electron/main.log，Linux 为~/.config/@craft-agent/electron/logs/main.log。

总结

Craft Agents 把「和 AI 智能体协作」做成了开箱即用的桌面体验：一行命令安装 macOS/Linux 客户端，首次启动选择模型连接、创建工作区，5 分钟即可开启第一个 AI 会话。从此多任务并行、数据源即连即用，全部交给 Agent 自己搞定。

【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析