Craft Agents：Claude Code 的图形界面 GUI 版，支持 Codex 模型，能连 Slack 和 Gmail

它底层用的就是 Claude Agent SDK——跟 Claude Code 完全相同的引擎。区别在于它外面套了一层 Electron 桌面应用，加上了收件箱式的会话管理、自然语言的数据源连接、多 LLM 提供商切换、Skills 系统和事件驱动自动化。

由 Craft Docs 团队开发（Apple Mac App of the Year 2021 获奖者，拥有 100 万 + 活跃用户和 50,000+ 付费客户），在 GitHub 上获得 6,200+ Star、840+ Fork，Apache 2.0 开源。

Craft Agents 是什么

一句话：基于 Claude Agent SDK 的开源 AI Agent 桌面应用，有图形界面，支持多个 AI 模型，能用自然语言连接外部服务。

技术架构：

它使用两个 Agent 后端：

• Claude 后端：基于 Claude Agent SDK，处理 Anthropic API Key、Claude Max/Pro OAuth 以及所有第三方端点（OpenRouter、Ollama、自定义端点）
• Pi 后端：基于 Pi SDK，处理 Google AI Studio、ChatGPT Plus（Codex OAuth）、GitHub Copilot OAuth

项目目录结构：

craft-agent/
├── apps/
│   ├── cli/                   # 终端客户端
│   └── electron/              # 桌面 GUI（主要界面）
│       └── src/
│           ├── main/          # Electron 主进程
│           ├── preload/       # 上下文桥接
│           └── renderer/      # React UI (Vite + shadcn)
└── packages/
    ├── core/                  # 共享类型
    └── shared/                # 业务逻辑
        └── src/
            ├── agent/         # CraftAgent, 权限系统
            ├── auth/          # OAuth, Token 管理
            ├── config/        # 存储、偏好、主题
            ├── credentials/   # AES-256-GCM 加密存储
            ├── sessions/      # 会话持久化
            ├── sources/       # MCP, API, 本地数据源
            └── statuses/      # 动态状态系统

功能介绍

1. 图形界面 + 收件箱式会话管理

界面设计像邮件客户端：左侧是会话列表，右侧是对话区域。

每个会话有独立的工作流状态（Todo → In Progress → Needs Review → Done），可以标记（Flag）重要会话，完成的会话可以归档。AI 自动生成会话标题，也可以手动命名。

所有对话自动保存到磁盘（JSONL 格式），关掉应用再打开，之前的会话还在。

文件变更用 VS Code 风格的多文件 Diff 视图展示——不是在终端里翻看代码改动，而是在专门的窗口里查看所有文件变更。

2. Sources：用自然语言连接外部服务

这是 Craft Agents 最独特的能力。你不需要写配置文件，不需要 OAuth 向导，直接在对话中说：

"Add Slack as a source."

Agent 会自动查找 Slack 的公共 API 和 MCP 服务器、阅读文档、引导你配置凭据、完成连接。GitHub README 原话："It finds public APIs and MCP servers, reads their docs, sets up credentials, and configures everything. No config files, no setup wizards."

如果你已经有 MCP 配置 JSON，直接粘贴也行。如果是自定义 API，粘贴 OpenAPI 规范、endpoint URL、甚至 API 文档的截图都行——Agent 自己搞清楚怎么连接。

支持三种数据源类型：

安全设计：API Source 像 MCP 服务器一样向 Agent 暴露工具，但 Craft Agents 在请求中注入凭据，Agent 本身不接触敏感凭据。本地 MCP 服务器启动时，会过滤敏感环境变量（如 ANTHROPIC_API_KEY、AWS_ACCESS_KEY_ID、GITHUB_TOKEN 等），防止凭据泄漏到子进程。

你还可以直接告诉 Agent 导入 Claude Code 的 Skills 和 MCP 配置，它处理迁移。

3. 多 LLM 提供商

不绑定单一 AI 模型。四种直连方式：

通过自定义端点还支持：

• OpenRouter（https://openrouter.ai/api）：一个 Key 访问数百个模型，用 provider/model-name 格式（如 anthropic/claude-opus-4.7）
• Ollama（http://localhost:11434）：本地运行开源模型，不需要 API Key
• 任何 OpenAI 或 Anthropic 兼容的自定义端点

每个工作空间可以设置不同的默认 LLM 提供商。

4. Skills：可复用的 Agent 指令

类似 Claude Code 的 Skills，你定义一次，之后在任何会话中用 @ 提及触发。不需要重启——所有变更即时生效。

Craft 内部客户支持团队的实际使用案例：

• Bug Report Processor：自动识别 Bug 所属平台 → 与 Linear 交叉检查 → 技术根因分析 → 起草客户回复 → 创建工程团队任务（含代码引用）
• Get User Data：通过后端 API 查询用户信息（计划类型、计费状态、Feature Flag、使用指标），自动添加到上下文
• 教育机构验证：检查域名是否为学术域名，自动批准合法域名，标记可疑请求

Pragmatic Engineer 报道称，客户支持团队是 Craft Agents 内部最活跃的用户，工作效率提升显著，Craft 可能因此替换 Zendesk。

5. 自动化系统

事件驱动的自动化，让 Agent 在特定事件发生时自动执行任务。支持 11+ 种触发器类型：

不需要写配置文件——直接告诉 Agent 你想自动化什么，它帮你设置。也可以手动编辑 automations.json：

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "cron": "0 9 * * 1-5",
        "timezone": "America/New_York",
        "actions": [
          {
            "type": "prompt",
            "prompt": "Check @github for new issues assigned to me"
          }
        ]
      }
    ],
    "LabelAdd": [
      {
        "matcher": "^urgent$",
        "actions": [
          {
            "type": "prompt",
            "prompt": "Triage the session and summarise what needs attention."
          }
        ]
      }
    ]
  }
}

Prompt actions 支持用 @mentions 引用数据源和 Skills，环境变量 $CRAFT_LABEL 和 $CRAFT_SESSION_ID 自动展开。

6. 三级权限控制

用 Shift+Tab 快速切换。

7. CLI 客户端：命令行也能用

除了桌面应用，Craft Agents 还有一个 CLI 客户端，通过 WebSocket 连接 Headless 服务器。适合脚本、CI/CD、服务器验证、或者你更喜欢命令行的场景。

安装后可用这些命令：

run 命令是亮点——完全自包含，不需要单独启动服务器。一行命令就能跑：

# 最简用法
craft-cli run "Summarize the README"

# 指定工作空间和数据源
craft-cli run --workspace-dir ./my-project --source github "List open PRs"

# 切换到 OpenAI 模型
craft-cli run --provider openai --model gpt-4o "Summarize this repo"

# 切换到 Google 模型
GOOGLE_API_KEY=... craft-cli run --provider google --model gemini-2.0-flash "Hello"

# 通过 OpenRouter 路由
craft-cli run --provider anthropic --base-url https://openrouter.ai/api/v1 --api-key $OR_KEY "Hello"

run 命令支持的参数：

其他 CLI 用法示例：

# 快速连通性检查
craft-cli ping

# 列出会话
craft-cli sessions

# 发送消息并流式输出 AI 响应
craft-cli send abc-123 "What files are in the current directory?"

# 管道输入
echo "Summarize this" | craft-cli send abc-123

# JSON 输出用于脚本
craft-cli --json workspaces | jq '.[].name'

8. 深度链接

外部应用可以通过 craftagents:// URL 直接跳转到 Craft Agents 的特定视图：

craftagents://allSessions                      # 所有会话
craftagents://allSessions/session/session123   # 特定会话
craftagents://settings                         # 设置
craftagents://sources/source/github            # 数据源信息
craftagents://action/new-chat                  # 创建新会话

9. 其他功能

• 文件附件：拖放图片、PDF、Office 文档到对话中，自动转换格式
• 主题系统：应用级和工作空间级的级联主题，完全可定制
• 后台任务：长时间运行的任务有进度追踪，不阻塞界面
• 大响应处理：工具响应超过 ~60KB 时，自动用 Claude Haiku 做摘要，保留意图感知上下文。_intent 字段会注入到 MCP 工具 schema 中，保证摘要时保留关键意图
• 原生 Mermaid 图表渲染：内置 beautiful-mermaid，不需要外部依赖

怎么安装

直接下载安装包

从官网 agents.craft.do 下载对应平台的安装包，双击安装即可。

一行命令安装

macOS / Linux：

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

Windows（PowerShell）：

irm https://agents.craft.do/install-app.ps1 | iex

从源码构建

需要 Bun：

git clone https://github.com/lukilabs/craft-agents-oss.git
cd craft-agents-oss
bun install
bun run electron:start

开发模式（热重载）：

bun run electron:dev

类型检查：

bun run typecheck:all

调试模式

启动打包好的应用时加 -- --debug（注意双横线）：

macOS：

/Applications/Craft Agents.app/Contents/MacOS/Craft Agents -- --debug

Windows（PowerShell）：

& "$env:LOCALAPPDATAPrograms@craft-agentelectronCraft Agents.exe" -- --debug

Linux：

./craft-agents -- --debug

日志文件位置：

• macOS：~/Library/Logs/@craft-agent/electron/main.log
• Windows：%APPDATA%@craft-agentelectronlogsmain.log
• Linux：~/.config/@craft-agent/electron/logs/main.log

怎么用

第一步：配置 LLM 连接

启动应用后，选择一个 AI 提供商。最简单的方式是用你已有的：

• Anthropic API Key：如果你已经有 Claude API Key，直接填进去
• Claude Max/Pro 订阅：用 OAuth 登录，不需要 API Key
• ChatGPT Plus 订阅：用 Codex OAuth 登录
• GitHub Copilot 订阅：一键设备码认证
• Google AI Studio：填 API Key

第二步：创建工作空间

工作空间是独立的上下文环境。不同项目、不同客户可以各建一个工作空间——各有自己的数据源、凭据、Skills 和会话历史。

配置文件存储在 ~/.craft-agent/workspaces/{id}/ 目录下：

~/.craft-agent/
├── config.json              # 主配置（工作空间、LLM 连接）
├── credentials.enc          # 加密凭据（AES-256-GCM）
├── preferences.json         # 用户偏好
├── theme.json               # 应用级主题
└── workspaces/
    └── {id}/
        ├── config.json      # 工作空间设置
        ├── automations.json # 自动化配置
        ├── sessions/        # 会话数据（JSONL）
        ├── sources/         # 已连接的数据源
        ├── skills/          # 自定义 Skills
        └── statuses/        # 状态配置

第三步：连接外部服务

连接 Slack

直接在对话中说：

"Add Slack as a source."

Agent 自动查找 Slack 的 API 和 MCP 服务器，引导你完成 OAuth 授权或输入 Bot Token。

如果你有现成的 MCP 配置，也可以直接粘贴 JSON。以下是官方的 Slack MCP 配置示例：

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-bot-token",
        "SLACK_TEAM_ID": "T01234567",
        "SLACK_CHANNEL_IDS": "C01234567, C76543210"
      }
    }
  }
}

其中 SLACK_CHANNEL_IDS 是可选的，用于限制 Agent 可以访问的频道。如果留空，则默认只能访问公开频道。

配置完成后，任何会话中用 @slack 就能让 Agent 读取和发送 Slack 消息。

连接 Gmail / Google Calendar / Google Drive

Google 的服务需要先在 Google Cloud Console 创建 OAuth 凭据：

1. 创建 Google Cloud 项目
2. 启用需要的 API（Gmail API / Calendar API / Drive API）
3. 配置 OAuth 同意屏幕（选 External 类型）
4. 创建 OAuth 2.0 客户端 ID（选择"Desktop app"类型）
5. 记下 Client ID 和 Client Secret

然后在 Craft Agents 中告诉 Agent "connect Gmail"，它会引导你输入凭据并完成 OAuth 授权。凭据使用 AES-256-GCM 加密存储。

也可以直接在 Source 的 config.json 中配置：

{
  "api": {
    "googleService": "gmail",
    "googleOAuthClientId": "your-client-id.apps.googleusercontent.com",
    "googleOAuthClientSecret": "your-client-secret"
  }
}

连接自定义 API

粘贴 OpenAPI 规范、endpoint URL、或 API 文档截图，Agent 自己搞清楚怎么连接。GitHub README 的原话："Paste an OpenAPI spec, some endpoint URLs, screenshots of docs, whatever you have. It figures it out and guides you through the rest."

第四步：创建和使用 Skills

在对话中描述你想创建的 Skill：

"Create a skill called 'Bug Report Processor' that identifies the bug's platform, cross-checks with @linear, does a root cause analysis, drafts a customer response, and creates an engineering ticket."

Agent 生成 Skill 文件保存到工作空间的 skills/ 目录。之后在任何会话中用 @bug-report-processor 触发。

第五步：设置自动化

直接告诉 Agent：

• "每个工作日早上 9 点，检查 @github 上分配给我的新 Issue"
• "当会话标记为 urgent 时，自动分流并总结需要关注的内容"
• "每周五下午 5 点，总结本周完成的任务"

Agent 自动配置自动化规则。

Headless 服务器模式

如果你想长时间运行 Agent、从多台机器访问、或跑计算密集任务，可以在远程服务器上运行 Headless 模式。

启动服务器：

CRAFT_SERVER_TOKEN=$(openssl rand -hex 32) bun run packages/server/src/index.ts

服务器启动后会打印连接信息：

CRAFT_SERVER_URL=ws://203.0.113.5:9100
CRAFT_SERVER_TOKEN=<generated-token>

桌面应用作为瘦客户端连接：

CRAFT_SERVER_URL=wss://203.0.113.5:9100 CRAFT_SERVER_TOKEN=<token> bun run electron:start

在瘦客户端模式下，桌面应用只渲染 UI，所有会话逻辑、工具执行和 LLM 调用都在远程服务器上运行。

支持的环境变量：

也支持 Docker 部署：

docker run -d 
  -p 9100:9100 
  -e CRAFT_SERVER_TOKEN=<token> 
  -e CRAFT_RPC_HOST=0.0.0.0 
  -v craft-data:/root/.craft-agent 
  craft-agents-server

Docker 中启用 TLS：

docker run -d 
  -p 9100:9100 
  -e CRAFT_SERVER_TOKEN=<token> 
  -e CRAFT_RPC_HOST=0.0.0.0 
  -e CRAFT_RPC_TLS_CERT=/certs/cert.pem 
  -e CRAFT_RPC_TLS_KEY=/certs/key.pem 
  -v ./certs:/certs:ro 
  -v craft-data:/root/.craft-agent 
  craft-agents-server

跟 Codex 和 Claude Code 对比

三者的定位

• Claude Code：Anthropic 的终端 Agent，锁定 Claude 模型，最强工程能力
• OpenAI Codex：OpenAI 的 Agent 平台，有 App + CLI + IDE + 云端沙箱，锁定 GPT 模型
• Craft Agents：开源桌面 Agent 工作台，基于 Claude Agent SDK 但支持多 LLM，强调外部服务连接

对比表

Craft Agents 的独特之处

• 自然语言连接任何服务——说一句就行，不需要配置文件
• 一个应用多个 LLM——Claude、GPT、Gemini、本地模型随意切换
• 完全开源——Apache 2.0，可以 fork 修改
• 数据不经过 Craft 服务器——会话数据、凭据都存在本地，只有调用 LLM API 时数据才会发送到对应的 AI 提供商

Codex 的独特之处

• 云端沙箱——任务在远程容器运行，关电脑也不影响
• Goals 功能——给 Agent 一个长期目标，它自己分解执行
• 内置浏览器——Agent 可以直接在应用内操作网页
• GPT-5.3-Codex——SWE-Bench Pro 56.8%、Terminal-Bench 77.3%- ChatGPT 生态深度集成——从 Slack 启动任务、管理邮件等

Claude Code 的独特之处

• 终端深度集成——Git、文件系统、shell 命令无缝操作
• /effort max 模式——复杂多文件重构能力最强
• 开发者工作流最成熟——代码审查、测试、部署全流程

参考资料

• 下载安装：agents.craft.do
• GitHub 仓库：github.com/craft-ai-agents/craft-agents-oss
• 官方介绍：Introducing Craft Agents — Craft Blog
• 深度报道：Inside a five-year-old startup's rapid AI makeover — Pragmatic Engineer
• 演示视频：Craft Agents Demo — YouTube
• 自动化文档：agents.craft.do/docs/automations