两种使用方式
PinableAgents 提供两种使用方式，选择适合你的：
| 方式 | 适用场景 | 入口 |
|---|---|---|
| 桌面端 | GUI 爱好者，习惯图形界面 | pinable-desktop 应用 |
| 终端 | 开发者，最大化原生 CLI 能力 | 任意终端 + Claude Code / Codex / Gemini CLI |
本指南覆盖两种方式的核心操作。
终端使用：原生 CLI 直接调用
第一步：安装 AI CLI
根据你使用的 AI 后端，安装对应的 CLI 工具：
bash
# Claude Code (Anthropic) - 主要推荐
npm install -g @anthropic-ai/claude-code
# Codex (OpenAI)
npm install -g @openai/codex
# Gemini CLI (Google)
npm install -g @google/gemini-cli验证安装：
bash
claude --version # Claude Code
codex --version # Codex
gemini --version # Gemini CLI第二步：配置 API 密钥
bash
# Claude Code
export ANTHROPIC_API_KEY="sk-ant-..."
# Codex
export OPENAI_API_KEY="sk-..."
# Gemini CLI
export GEMINI_API_KEY="..."第三步：直接调用 CLI
Claude Code — 主要推荐用它作为主力引擎：
bash
claude "解释这个函数的逻辑"Codex — 代码生成任务：
bash
codex - <<'EOF'
为这个函数添加单元测试
EOFGemini CLI — 多模态任务（截图分析、设计稿转代码）：
bash
gemini --image screenshot.png "描述这个界面并给出 HTML 实现"进阶：HEREDOC 语法传递复杂任务
当任务包含多行内容、代码块、特殊字符时，使用 HEREDOC 避免 shell 转义问题：
bash
codex - <<'EOF'
重构 src/auth/ 目录下的代码：
1. 将 auth.go 拆分为多个小文件
2. 提取公共逻辑到 helpers
3. 添加错误处理
4. 确保通过现有测试
EOF并行任务
通过 stdin 传递多个任务：
bash
codex --parallel <<'EOF'
---TASK---
id: task1
---CONTENT---
实现用户注册接口
---TASK---
id: task2
dependencies: task1
---CONTENT---
实现用户登录接口，依赖注册接口
EOF桌面端使用：pinable-desktop
下载安装
从项目首页下载对应平台的安装包：
- macOS:
PinableAgents-mac.dmg - Windows:
PinableAgents-win.exe
首次配置
启动后进入「设置」页面，配置 API 密钥。桌面端会自动检测已安装的 AI CLI。
核心页面一览
| 页面 | 功能 |
|---|---|
| Provider | 管理 Claude/Codex/Gemini/OpenCode 的 API 密钥和优先级 |
| Modules | 安装/卸载/管理技能模块，查看配置 Schema 和使用量 |
| Skills | 导入/导出/配置技能，为不同后端设置技能 |
| Workflows | 选择工作流、配置 Provider 组、执行任务、查看历史 |
| Terminal | 嵌入式 xterm.js 终端，多标签页，Workflow 联动 |
| Logs | 查看工作流执行历史和日志 |
| History | AgentSession 历史，可恢复断掉的会话 |
| Conversations | 对话浏览器，Token 统计，消息详情 |
| Gateway | Telegram/飞书/企业微信三通道接入配置 |
| Scheduled Tasks | Cron 定时任务调度（HTTP/Shell/Workflow） |
| License | 查看和激活授权（Community/Pro/Team） |
| Settings | 应用设置、语言、代理、分析配置 |
| Status（Doctor） | 系统诊断：Provider 状态、Gateway 状态、终端会话、事件日志、告警 |
| About | 版本信息、更新检查、反馈、应用路径 |
Telegram Gateway 配置
创建 Telegram Bot
- 在 Telegram 中搜索 @BotFather
- 发送
/newbot创建新 Bot - 按提示输入 Bot 名称和用户名
- 复制 BotFather 返回的 Token（格式如
123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ）
在桌面端配置
- 进入 Gateway 页面
- 选择或创建一个 Gateway 实例
- 在 Channels Tab 中找到 Telegram 配置区
- 填写 Bot Token，启用 Telegram 通道
- 在 Allow From 中填入你的 Telegram User ID（留空则允许所有人）
- 点击 Save 保存，然后 Start 启动实例
使用 Telegram 控制
配置完成后，在 Telegram 向机器人发送消息即可触发 AI 对话：
| 指令 | 效果 |
|---|---|
hello | 测试连接，Bot 应答 |
/do <任务> | 启动 do 工作流 |
/omo <问题> | 启动 omo 工作流 |
/ask <问题> | 技术咨询（直接回答） |
执行完成后，结果自动推送到 Telegram。
定时任务使用
创建第一个定时任务
- 进入 Scheduled Tasks 页面
- 点击 Add Task 按钮
- 填写任务名称（如 "Daily Code Scan"）
- 选择任务类型（HTTP/Shell/Workflow）
- 输入 Cron 表达式（如
0 9 * * *每天早上 9 点） - 填写任务目标（URL/Shell 命令/工作流描述）
- 点击 Save
Cron 表达式预设
| 频率 | 表达式 | 说明 |
|---|---|---|
| 每 5 分钟 | */5 * * * * | 高频检测场景 |
| 每小时 | 0 * * * * | 整点执行 |
| 每天早上 | 0 9 * * * | 工作日早间 |
| 工作日早间 | 0 9 * * 1-5 | 周一至周五 |
| 每月 1 日 | 0 2 1 * * | 定期报告 |
详细说明请参阅 Scheduled Tasks 定时任务。
授权等级
pinable-desktop 有三个授权等级，从免费到团队版：
| 功能 | Community（免费） | Pro | Team |
|---|---|---|---|
| Provider 数 | 4 | 无限 | 无限 |
| 工作流数 | 5 | 无限 | 无限 |
| 终端数 | 2 | 无限 | 无限 |
| 历史保留 | 7 天 | 无限 | 无限 |
| 技能（Skills） | No | Yes | Yes |
| 工作流导出 | No | Yes | Yes |
| HTTP/Shell 定时任务 | No | Yes | Yes |
| Workflow 定时任务 | No | Yes | Yes |
| Gateway（TG/飞书/企微） | No | No | Yes |
| 飞书历史 | No | No | Yes |
| 会话（Conversations） | No | No | Yes |
激活 License
- 进入 License 页面
- 输入 License Key
- 点击 Activate
- 激活成功后，功能限制自动解除
技能（Skills）系统
Skills 页面让你管理 AI 技能扩展：
| 功能 | 说明 |
|---|---|
| 导入技能 | 从 GitHub URL 导入社区技能 |
| 导出技能 | 将技能导出为本地文件共享 |
| 删除技能 | 移除不再需要的技能 |
| 按 Provider 设置 | 为技能指定运行后端（global/claude/codex/gemini/opencode） |
| 搜索过滤 | 按名称、描述、来源快速定位 |
详细说明请参阅 Skills 技能管理。
使用 Claude Code 工作流命令
在 Claude Code 终端中，直接输入 slash 命令启动工作流：
bash
# 启动 do 工作流（功能交付）
/do 实现用户注册接口
# 启动 omo 工作流（Bug 调查）
/omo 调查登录失败的原因
# 启动 bmad 工作流（企业级）
/bmad 实现完整的权限管理系统Claude Code 会自动加载对应的工作流技能，交互式引导你完成任务。
飞书集成配置
创建飞书应用
- 访问 飞书开放平台
- 创建企业自建应用，记录 App ID 和 App Secret
- 申请权限：
im:message、contact:user.base:readonly等
配置连接
在桌面端「Gateway」页面 Channels Tab 的 Feishu 配置区填写：
| 字段 | 说明 |
|---|---|
| Mode | 推荐选择 ws（WebSocket） |
| App ID | 飞书应用的 App ID |
| App Secret | 飞书应用的 App Secret |
| Port | 本地监听端口（默认 9800） |
详细 Gateway 配置说明请参阅 Gateway 多通道网关。
环境验证清单
bash
# CLI 工具
claude --version # Claude Code
codex --version # Codex
gemini --version # Gemini CLI
# API 密钥（验证可访问）
curl -s https://api.anthropic.com/v1/models \
-H "x-api-key: $ANTHROPIC_API_KEY" | head -c 100
# 飞书连接（桌面端）
# 打开桌面端 → Gateway 页面 → 选择实例 → Channels Tab → Feishu 配置 → Save → Start
# Telegram 连接（桌面端）
# 打开桌面端 → Gateway 页面 → 选择实例 → Channels Tab → Telegram 配置 → 填入 Token → Save → Start下一步
- 深入了解 pinable-desktop 完整指南 — 14 个页面详解
- 探索 Gateway 多通道网关 — Telegram/飞书/企微配置
- 配置 定时任务 — Cron 自动化
- 探索 技能系统 — 扩展 AI 能力