CodePilot Documentation

A multi-model AI agent desktop client — connect any AI provider, extend with MCP & skills, control from your phone. Built with Electron + Next.js.

6,146 stars TypeScript TypeScript 1 file · ~6,698 tokens #ai#anthropic#claude#claude-code#desktop-app#electron#gui#nextjs
RAW Doc

File: README.md

CodePilot

A multi-model AI agent desktop client -- connect any AI provider, extend with MCP & skills, control from your phone, and let your assistant learn your workflow.





中文文档 | 日本語

Download | Quick Start | Documentation | Contributing | Community

Download

Platform Download Architecture
macOS Apple Silicon (.dmg) · Intel (.dmg) arm64 / x64
Windows Installer (.exe) x64
Linux AppImage / deb / rpm x64 / arm64

Or visit the Releases page for all versions.

Why CodePilot

Multi-provider, one interface

Connect to 17+ AI providers out of the box. Switch providers and models mid-conversation without losing context.

Category Providers
Direct API Anthropic, OpenRouter
Cloud platforms AWS Bedrock, Google Vertex AI
Chinese AI providers Zhipu GLM (CN/Global), Kimi, Moonshot, MiniMax (CN/Global), Volcengine Ark (Doubao), Xiaomi MiMo, Aliyun Bailian (Qwen)
Local & self-hosted Ollama, LiteLLM
Custom Any Anthropic-compatible or OpenAI-compatible endpoint
Media Google Gemini (image generation)

Beyond coding — a full AI agent

CodePilot started as a coding tool but has grown into a general-purpose AI agent desktop:

  • Assistant Workspace — Persona files, persistent memory, onboarding flows, and daily check-ins. Your assistant learns your preferences and adapts over time.
  • Generative UI — AI can create interactive dashboards, charts, and visual widgets rendered live in-app.
  • Remote Bridge — Connect to Telegram, Feishu, Discord, QQ, and WeChat. Send messages from your phone, get responses on your desktop.
  • MCP + Skills — Add MCP servers (stdio / sse / http) with runtime monitoring. Define reusable skills or install from the skills.sh marketplace.
  • Media Studio — AI image generation with batch tasks, gallery, and tagging.
  • Task Scheduler — Schedule recurring tasks with cron expressions or intervals.

Built for daily use

  • Pause, resume, and rewind sessions to any checkpoint
  • Split-screen dual sessions side by side
  • Track token usage and costs with daily charts
  • Import Claude Code CLI session history
  • Dark / Light theme toggle
  • English + Chinese interface

Quick Start

Path A: Download a release (most users)

  1. Download the installer for your platform from the Download section above
  2. Launch CodePilot
  3. Configure a Provider in Settings > Providers — add your API key for any supported provider
  4. Start a conversation

Note: Installing the Claude Code CLI (npm install @anthropic-ai/claude-code) unlocks additional capabilities like direct file editing, terminal commands, and git operations. It is recommended but not required for basic chat.

Path B: Build from source (developers)

Prerequisite Minimum version
Node.js 18+
npm 9+ (ships with Node 18)
bash
git clone https://github.com/op7418/CodePilot.git
cd CodePilot
npm install
npm run dev              # browser mode at http://localhost:3000
# -- or --
npm run electron:dev     # full desktop app

Core Capabilities

Conversation & Interaction

Capability Details
Interaction modes Code / Plan / Ask
Reasoning effort Low / Medium / High / Max + Thinking mode
Permission control Default / Full Access, per-action approval
Session control Pause, resume, rewind to checkpoint, archive
Model switching Change model mid-conversation
Split screen Side-by-side dual sessions
Attachments Files and images with multimodal vision support
Slash commands /help /clear /cost /compact /doctor /review and more

Extensions & Integrations

Capability Details
Providers 17+ providers: Anthropic, OpenRouter, Bedrock, Vertex, Zhipu GLM, Kimi, Moonshot, MiniMax, Volcengine, MiMo, Bailian, Ollama, LiteLLM, custom endpoints
MCP servers stdio / sse / http, runtime status monitoring
Skills Custom / project / global skills, skills.sh marketplace
Bridge Telegram / Feishu / Discord / QQ / WeChat remote control
CLI import Import Claude Code CLI .jsonl session history
Image generation Gemini image gen, batch tasks, gallery

Data & Workspace

Capability Details
Assistant Workspace Persona files (soul.md, user.md, claude.md, memory.md), onboarding, daily check-ins, persistent memory
Generative UI AI-created interactive dashboards and visual widgets
File browser Project file tree with syntax-highlighted preview
Git panel Status, branches, commits, worktree management
Usage analytics Token counts, cost estimates, daily usage charts
Task scheduler Cron-based and interval scheduling with persistence
Local storage SQLite (WAL mode), all data stays on your machine
i18n English + Chinese
Themes Dark / Light, one-click toggle

First Launch

  1. Configure a Provider — Go to Settings > Providers and add credentials for the provider you want to use. CodePilot includes presets for all major providers — just pick one and enter your API key.
  2. Create a conversation — Pick a working directory, select a mode (Code / Plan / Ask), and choose a model.
  3. Set up Assistant Workspace (optional) — Go to Settings > Assistant, choose a workspace directory, and enable Onboarding. CodePilot creates soul.md, user.md, claude.md, and memory.md at the workspace root.
  4. Add MCP servers (optional) — Go to the MCP page in the sidebar to add and manage MCP servers. Custom skills are managed on the separate Skills page.
  5. Install Claude Code CLI (optional) — For advanced features like file editing and terminal commands, install the CLI: npm install @anthropic-ai/claude-code

Platform & Installation Notes

macOS builds are code-signed with a Developer ID certificate but not notarized, so Gatekeeper may still prompt on first launch. Windows and Linux builds are unsigned.

macOS: Gatekeeper warning on first launch

Option 1 -- Right-click CodePilot.app in Finder > Open > confirm.

Option 2 -- System Settings > Privacy & Security > scroll to Security > click Open Anyway.

Option 3 -- Run in Terminal:

bash
xattr -cr /Applications/CodePilot.app

Windows: SmartScreen blocks the installer

Option 1 -- Click "More info" on the SmartScreen dialog, then "Run anyway".

Option 2 -- Settings > Apps > Advanced app settings > set App Install Control to allow apps from anywhere.

Documentation

📖 Full documentation: English | 中文

Getting started:

User guides:

  • Providers -- Configuring AI providers and custom endpoints
  • MCP Servers -- Adding and managing Model Context Protocol servers
  • Skills -- Custom skills, project skills, and the skills.sh marketplace
  • Bridge -- Remote control via Telegram, Feishu, Discord, QQ, WeChat
  • Assistant Workspace -- Persona files, onboarding, memory, daily check-ins
  • FAQ -- Common issues and solutions

Developer docs:

FAQ

Do I need the Claude Code CLI?

No. You can use CodePilot with any supported provider (OpenRouter, Zhipu GLM, Volcengine, Ollama, etc.) without the Claude Code CLI. The CLI is only needed if you want Claude to directly edit files, run terminal commands, or use git operations on your machine. For chat and assistant features, just configure a provider and start a conversation.

Configured a Provider but no models appear

Verify the API key is valid and the endpoint is reachable. Some providers (Bedrock, Vertex) require additional environment variables or IAM configuration beyond the API key. Use the built-in diagnostics (Settings > Providers > Run Diagnostics) to check connectivity.

What is the difference between npm run dev and npm run electron:dev?

npm run dev starts only the Next.js dev server -- you use CodePilot in your browser at http://localhost:3000. npm run electron:dev starts both Next.js and the Electron shell, giving you the full desktop app experience with native window controls.

Where are the Assistant Workspace files?

When you set up a workspace, CodePilot creates four Markdown files at the workspace root directory: soul.md (personality), user.md (user profile), claude.md (rules), and memory.md (long-term notes). State tracking (onboarding progress, check-in dates) is stored in the .assistant/ subdirectory. Daily memories go to memory/daily/.

Bridge requires additional setup per platform

Each Bridge channel (Telegram, Feishu, Discord, QQ, WeChat) requires its own bot token or app credentials. Go to the Bridge page in the sidebar to configure channels. You will need to create a bot on the target platform first and provide the token to CodePilot.

Community

Scan the QR code to join the WeChat user group for discussions, feedback, and updates.

Contributing

  1. Fork the repository and create a feature branch
  2. npm install and npm run electron:dev to develop locally
  3. Run npm run test before opening a PR
  4. Submit a PR against main with a clear description

Keep PRs focused -- one feature or fix per pull request.

Development commands

bash
npm run dev                    # Next.js dev server (browser)
npm run electron:dev           # Full Electron app (dev mode)
npm run build                  # Production build
npm run electron:build         # Build Electron distributable
npm run electron:pack:mac      # macOS DMG (arm64 + x64)
npm run electron:pack:win      # Windows NSIS installer
npm run electron:pack:linux    # Linux AppImage, deb, rpm

CI/CD: Pushing a v* tag builds macOS arm64/x64, Windows x64, and Linux arm64/x64 packages, then creates a GitHub Release automatically. A failure in any target blocks the Release.

Notes:

  • Electron forks a Next.js standalone server on 127.0.0.1 with a random free port
  • Chat data is stored in ~/.codepilot/codepilot.db (dev mode: ./data/)
  • SQLite uses WAL mode for fast concurrent reads

License

Business Source License 1.1 (BSL-1.1)

  • Personal / academic / non-profit use: free and unrestricted
  • Commercial use: requires a separate license — contact @op7418 on X
  • Change date: 2029-03-16 — after which the code converts to Apache 2.0

File: apps/site/content/docs/zh/bridge/discord.mdx

title: Discord

Discord 桥接

通过 Discord Bot 与 Claude 对话。支持服务器频道和私聊两种模式，支持流式消息预览。

创建 Discord Bot

  1. 前往 Discord Developer Portal
  2. 点击 New Application，输入应用名称
  3. 在左侧菜单选择 Bot
  4. 点击 Reset Token 获取 Bot Token，复制备用
  5. 在 Bot 设置中开启以下 Privileged Gateway Intents：
    • Message Content Intent — 必须，Bot 需要读取消息内容
    • Server Members Intent — 可选，用于用户身份验证
  6. 在左侧选择 OAuth2 > URL Generator
  7. 勾选 Scopes：bot
  8. 勾选 Bot Permissions：Send Messages、Read Message History、Embed Links
  9. 复制生成的邀请链接，在浏览器中打开
  10. 选择你的服务器，授权 Bot 加入

在 CodePilot 中配置

  1. 点击侧边栏 桥接，切换到 Discord 页面
  2. 在 Bot 凭据 区域粘贴 Bot Token
  3. 点击 测试连接 验证
  4. 配置访问控制（获取 ID 需要先开启 Discord 的开发者模式：打开 Discord 设置 → 高级 → 开启 开发者模式，之后就可以右键复制各类 ID）：
    • 允许的用户 — 右键用户 → 复制用户 ID，多个用逗号分隔
    • 允许的频道 — 右键频道 → 复制频道 ID，限制 Bot 只在特定频道响应
    • 允许的服务器 — 右键服务器图标 → 复制服务器 ID，限制 Bot 只在特定服务器工作
  5. 配置群组策略：
    • 开放 — Bot 在所有允许的服务器/频道中响应
    • 禁用 — Bot 只在私聊中响应
  6. （可选）需要 @提及 — 开启后 Bot 只响应 @提及它的消息
  7. 点击 保存

启用桥接

  1. 回到桥接总览页面
  2. 确保 Discord 渠道开关已打开
  3. 确保桥接主开关已开启
  4. 点击 启动

流式预览

Discord 桥接支持流式消息预览，Claude 生成回复时实时更新消息。参数：

  • 最小更新字符数 — 默认 40
  • 最小更新间隔 — 默认 1500ms
  • 最大消息长度 — 默认 1900 字符

消息格式

Discord 原生支持 Markdown，Claude 的回复会直接以 Markdown 格式发送。超长消息自动分片（每片最大 2000 字符）。

故障排除

Bot 在线但不响应

  1. 确认 Message Content Intent 已开启（Developer Portal → Bot 设置）
  2. 确认 Bot 有该频道的 发送消息 和 查看频道 权限
  3. 如果设置了允许的频道/用户/服务器列表，确认对应 ID 正确
  4. 如果开启了 需要 @提及，确保消息中 @了 Bot

Bot 掉线

Discord WebSocket 连接可能因网络波动断开。CodePilot 会自动重连。如果持续掉线，检查网络连接。

File: apps/site/content/docs/zh/bridge/feishu.mdx

title: 飞书

飞书桥接

通过飞书（或 Lark）应用与 Claude 对话。支持流式卡片输出、工具调用进度显示、权限审批按钮、项目快捷切换。

创建飞书应用

国内版（飞书）

  1. 前往 飞书开放平台，登录开发者账号
  2. 点击 创建企业自建应用
  3. 填写应用名称和描述
  4. 进入应用详情页，在 凭证与基础信息 中获取：
    • App ID（格式：cli_xxxxxxxxxx）
    • App Secret

添加应用能力

  1. 在左侧选择 添加应用能力 > 机器人，启用机器人功能

事件与回调

  1. 在 事件与回调 中配置：
    • 选择 使用长连接模式（WebSocket，无需公网地址或 Encrypt Key / Verification Token）
    • 添加事件：im.message.receive_v1（接收消息）
    • 添加回调：card.action.trigger（卡片回传交互回调，用于权限审批按钮和项目选择）
    • 保存配置

权限管理

  1. 在 权限管理 中，批量添加以下权限（可在「批量开通」中粘贴 scope 列表）：

应用权限（tenant scope）：

权限 说明
im:message:send_as_bot 以 Bot 身份发送消息
im:message:readonly 读取消息内容
im:message.p2p_msg:readonly 接收私聊消息
im:message.group_at_msg:readonly 接收群聊 @消息
im:message:update 更新消息（流式卡片更新）
im:message.reactions:read 读取消息表情回复
im:message.reactions:write_only 添加/删除表情回复（typing 指示器）
im:chat:read 读取群聊信息
im:resource 下载消息中的资源（图片等）
cardkit:card:write 创建和更新流式卡片
cardkit:card:read 读取卡片状态

以下权限为可选，用于未来平台能力扩展：

权限 说明
im:chat:update 更新群聊设置
im:message.pins:read 读取置顶消息
im:message.pins:write_only 置顶/取消置顶消息
im:message:recall 撤回消息
im:message:send_multi_users 向多人发送消息
im:message:send_sys_msg 发送系统消息
contact:contact.base:readonly 读取通讯录基础信息
docx:document:readonly 读取文档内容
application:application:self_manage 应用自管理

用户权限（user scope） — 如需用户级别的文档/日历/任务等能力，可按需添加对应权限。完整列表请参考飞书开放平台文档。

发布应用

  1. 发布应用 — 提交审核或自审通过

国际版（Lark）

流程与国内版相同，但在 Lark Developer 上操作。在 CodePilot 配置时选择域名为 Lark。

在 CodePilot 中配置

  1. 点击侧边栏 桥接，切换到 飞书 页面
  2. 选择域名：飞书（国内版）或 Lark（国际版）
  3. 填写 App ID 和 App Secret
  4. 点击 测试连接 验证凭据
  5. 配置访问与行为：
    • 私信策略 — 控制谁可以向 Bot 发私信（开放 / 配对 / 白名单 / 禁用）
    • 允许来源 — 填写飞书 open_id 限制可用用户，* 表示不限
    • 群聊策略 — 控制 Bot 在群聊中的响应方式（开放 / 白名单 / 禁用）
    • 需要 @提及 — 开启后群聊中只响应 @Bot 的消息
    • 话题会话 — 启用后不同话题拥有独立的对话上下文
  6. 点击 保存

启用桥接

  1. 回到桥接总览页面
  2. 确保 飞书 渠道开关已打开
  3. 确保桥接主开关已开启
  4. 点击 启动

消息格式

飞书桥接使用流式卡片输出 Claude 的回复：

  • 流式卡片 — 实时显示生成过程，支持 Markdown 渲染（代码高亮、表格、列表等）
  • 工具调用进度 — 实时显示 🔄 Running / ✅ Complete / ❌ Error
  • Thinking 状态 — 在文本到达前显示 💭 Thinking...
  • 页脚信息 — 状态指示 + 耗时显示
  • 权限审批 — 内联按钮卡片，点击即可 Allow / Deny
  • 项目切换 — /cwd 命令弹出项目选择器卡片

命令响应和错误消息使用富文本消息（Post）+ Markdown 格式。

故障排除

测试连接失败

  1. 确认 App ID 和 App Secret 正确
  2. 确认应用已发布（审核通过）
  3. 确认选择了正确的域名（国内版 vs 国际版）

Bot 不响应群聊

  1. 确认已添加机器人能力
  2. 确认已申请 im:message.group_at_msg:readonly 权限
  3. 确认群组策略不是"禁用"
  4. 如果策略为"白名单"，确认群聊 ID 在允许列表中
  5. 如果开启了"需要 @提及"，确保消息中 @了 Bot

Bot 不响应私聊

  1. 确认已申请 im:message.p2p_msg:readonly 权限
  2. 确认应用已发布
  3. 在飞书中搜索 Bot 名称，发起私聊

权限按钮无反应

  1. 确认已在 事件与回调 中添加了 card.action.trigger 回调
  2. 确认使用的是 长连接模式（WSClient），非 HTTP Webhook 模式
  3. 检查 CodePilot 日志中是否有 [feishu/gateway] handleEventData type: card 输出

流式卡片不显示

  1. 确认已申请 cardkit:card:write 和 cardkit:card:read 权限
  2. 确认应用已重新发布（权限变更后需要重新发布）
  3. 检查 CodePilot 日志中是否有 [card-controller] 相关输出

File: apps/site/content/docs/zh/bridge/index.mdx

title: 消息桥接

消息桥接

消息桥接让你从手机上的即时通讯应用与 Claude 对话。在桌面上启动 CodePilot，配置好 Bot 后，你可以通过 Telegram、Discord、飞书或 QQ 随时随地与 Claude 交互。

支持的平台

平台 特点
Telegram 长轮询模式，支持流式预览、权限按钮、丰富的 Markdown 渲染
Discord WebSocket 模式，支持流式预览、频道/私聊双模式
飞书 / Lark WebSocket 模式，支持国内/国际版切换、群组策略控制
QQ REST API 模式，支持图片发送、私聊桥接

工作原理

text
手机 IM → Bot 收到消息 → CodePilot 转发给 Claude → Claude 回复 → Bot 发回 IM
  1. 你在消息平台上向 Bot 发送消息
  2. CodePilot 的 Bridge 服务接收消息并转发给 Claude
  3. Claude 处理请求后生成回复
  4. 回复通过 Bot 发回你的消息平台
  5. 如果 Claude 需要权限确认（如写文件），会在 IM 中发送确认按钮

基本设置

开启桥接

  1. 点击侧边栏的 桥接
  2. 在桥接总览页面打开 桥接主开关
  3. 分别启用你需要的渠道（Telegram / Discord / 飞书 / QQ）
  4. 进入各渠道页面配置 Bot 凭据
  5. 点击 启动 按钮

桥接全局设置

在桥接总览页面可以配置：

  • 默认工作目录 — 新对话的默认项目路径
  • 默认模型 — 桥接对话使用的模型
  • 默认服务商 — 桥接对话使用的 API 服务商
  • 自动启动 — CodePilot 启动时自动开启桥接服务

桥接状态

桥接页面实时显示：

  • 主服务状态（已连接 / 已断开）
  • 各渠道适配器状态
  • 活跃的会话绑定数量
  • 最后一条消息时间

斜杠命令

在 IM 中可以使用斜杠命令控制 CodePilot：

命令 参数 说明
/new [路径] 新建对话，可指定工作目录
/bind <会话ID> 绑定当前 IM 聊天到已有的 CodePilot 对话
/cwd /path/to/dir 切换当前对话的工作目录
/mode plan|code|ask 切换对话模式
/status — 查看当前对话状态（ID、工作目录、模式、模型）
/sessions — 列出当前渠道最近的对话（最多 10 个）
/stop — 中止当前正在运行的任务
/help — 查看可用命令

使用建议

  • 保持 CodePilot 运行 — 桥接依赖桌面端作为中转，关闭后 Bot 无法响应
  • 系统托盘模式 — 最小化到系统托盘，桥接保持活跃不占桌面空间
  • 私聊优先 — 建议在私聊中使用，群聊中可能被其他消息干扰
  • 权限确认 — Claude 需要执行敏感操作时会在 IM 中发送确认按钮，注意及时处理

各渠道配置

File: apps/site/content/docs/zh/bridge/qq.mdx

title: QQ

QQ 桥接

通过 QQ Bot 与 Claude 对话。支持图片发送和私聊桥接。

创建 QQ Bot

  1. 前往 QQ 开放平台，注册开发者账号
  2. 创建一个新的 Bot 应用
  3. 完成实名认证（个人或企业）
  4. 在应用管理页面获取：
    • AppID（数字格式）
    • App Secret
  5. 在 功能配置 中开启需要的消息权限
  6. 提交审核，等待通过

QQ Bot 平台审核较严格，建议仔细阅读平台文档中的接入规范。

在 CodePilot 中配置

  1. 点击侧边栏 桥接，切换到 QQ 页面
  2. 填写 App ID 和 App Secret
  3. 点击 测试连接 验证凭据
  4. （可选）配置 允许的用户 — 填写 QQ user_openid，多个用逗号分隔
  5. （可选）配置图片设置：
    • 启用图片发送 — 允许 Bot 发送图片（默认开启）
    • 最大图片大小 — 单张图片大小限制（默认 20MB）
  6. 点击 保存

启用桥接

  1. 回到桥接总览页面
  2. 确保 QQ 渠道开关已打开
  3. 确保桥接主开关已开启
  4. 点击 启动
  5. 在 QQ 中添加 Bot 为好友，发送消息即可与 Claude 对话

消息格式

QQ 桥接以纯文本格式发送消息：

  • 不支持 Markdown 渲染
  • 超长消息自动分片（每片最大 2000 字符）
  • 每条回复最多发送 3 个分片（平台限制）
  • 支持发送图片（需开启图片设置）

权限处理

QQ Bot 平台不支持内联按钮，权限确认通过文本命令处理：

  • Bot 发送权限确认消息，包含操作说明和权限 ID
  • 你回复 /perm allow 允许操作
  • 你回复 /perm deny 拒绝操作
  • 你回复 /perm allow_session 允许本次会话内同类操作

故障排除

测试连接失败

  1. 确认 App ID 和 App Secret 正确
  2. 确认 Bot 应用已通过审核
  3. 确认开发者实名认证已完成

Bot 不响应

  1. 确认已添加 Bot 为 QQ 好友
  2. 确认 CodePilot 桥接已启动
  3. 如果设置了允许用户列表，确认你的 user_openid 在列表中

消息被截断

QQ 平台限制每条回复最多 3 个分片。对于特别长的回复，可能会丢失末尾部分。建议在提示中要求 Claude 简洁回复。

File: apps/site/content/docs/zh/bridge/telegram.mdx

title: Telegram

Telegram 桥接

通过 Telegram Bot 与 Claude 对话。支持流式消息预览、权限确认按钮和丰富的 Markdown 渲染。

创建 Telegram Bot

  1. 在 Telegram 中搜索 @BotFather
  2. 发送 /newbot
  3. 按提示输入 Bot 名称（显示名）和用户名（以 _bot 结尾）
  4. BotFather 会返回一个 Bot Token，格式类似 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
  5. 复制 Token 备用

在 CodePilot 中配置

  1. 点击侧边栏 桥接，切换到 Telegram 页面
  2. 在 Bot 凭据 区域粘贴 Bot Token
  3. 点击 测试连接 验证 Token 是否有效
  4. 验证成功后，点击 自动检测 Chat ID：
    • 先在 Telegram 中向你的 Bot 发一条任意消息
    • 然后点击检测按钮，CodePilot 会自动获取你的 Chat ID
  5. （可选）在 允许的用户 中填写允许使用 Bot 的 Telegram 用户 ID，多个用逗号分隔。留空则不限制。
  6. 点击 保存

启用桥接

  1. 回到桥接总览页面
  2. 确保 Telegram 渠道开关已打开
  3. 确保桥接主开关已开启
  4. 点击 启动

现在在 Telegram 中向 Bot 发送消息，你就能收到 Claude 的回复了。

流式预览

Telegram 桥接支持流式消息预览 — Claude 生成回复时，Bot 会实时更新消息内容，让你不用等完整回复就能看到进展。

流式预览的参数可以在高级设置中调整：

  • 最小更新字符数 — 累积至少多少新字符后才更新消息（默认 20）
  • 最小更新间隔 — 两次更新之间的最短间隔（默认 700ms）
  • 最大消息长度 — 预览消息的最大长度（默认 3900 字符）

消息格式

Telegram 桥接会将 Claude 的 Markdown 回复转换为 Telegram HTML 格式：

  • 代码块 → `` 带语言标注
  • 粗体、斜体 → HTML 标签
  • 链接 → 可点击链接
  • 超长消息自动分片（每片最大 4096 字符）

如果 HTML 渲染失败，会自动降级为纯文本发送。

权限处理

当 Claude 需要执行敏感操作时，Bot 会发送一条带有内联按钮的消息：

  • 允许 — 允许本次操作
  • 允许本次会话 — 本次会话内同类操作自动允许
  • 拒绝 — 拒绝操作

故障排除

Bot 没有响应

  1. 确认 CodePilot 桥接服务已启动（桥接页面显示"已连接"）
  2. 确认 Telegram 渠道开关已打开
  3. 确认 Bot Token 正确（重新测试连接）
  4. 如果设置了允许用户列表，确认你的用户 ID 在列表中

收到错误消息

  • API 额度不足 — 检查 API 密钥余额
  • 模型不可用 — 检查桥接默认服务商和模型配置
  • 权限超时 — Claude 等待权限确认超时，重新发送消息

File: apps/site/content/docs/zh/assistant-workspace.mdx

title: 助理工作区

助理工作区

助理工作区（Assistant Workspace）让你为 Claude 配置项目级的上下文和行为。你可以定义 Claude 的角色、记忆、自动化流程，让它在每次对话中都保持一致的工作状态。

打开工作区

前往 设置 > 助理 标签页即可管理助理工作区的所有配置。

工作区路径

工作区路径指定 Claude 工作时的项目目录。设置后，Claude 在对话中会自动以该目录为上下文进行文件操作和代码分析。

引导设置

引导设置是在新对话开始时自动执行的提示。启用后，每次新建对话的第一条消息会自动触发引导设置流程。

典型用途：

  • 让 Claude 阅读项目的 README 和关键配置文件
  • 了解项目架构和代码规范
  • 加载必要的上下文信息

配置

  1. 在助理标签页找到引导设置区域
  2. 切换开关启用引导设置
  3. 在文本框中编写引导设置提示内容
  4. 保存

每日问询

每日问询是定期自动执行的上下文刷新提示。启用后，Claude 会按设定的频率重新审视项目状态。

典型用途：

  • 定期检查项目进度
  • 刷新文件变更状态
  • 更新 Claude 对项目当前状态的认知

配置

  1. 在助理标签页找到每日问询区域
  2. 切换开关启用每日问询
  3. 编写每日问询提示内容
  4. 保存

使用场景

个人项目维护

为长期维护的项目配置引导设置，让 Claude 每次对话都能快速了解项目现状，不需要反复解释项目背景。

团队协作

配置统一的工作区设定，确保团队成员使用 Claude 时遵循相同的代码规范和工作流程。

复杂项目管理

结合引导设置和每日问询，让 Claude 在长时间运行的任务中保持对项目上下文的持续感知。

File: apps/site/content/docs/zh/chat.mdx

title: 对话

对话

对话是 CodePilot 的核心功能。你在这里与 Claude 协作完成编程任务。

对话模式

CodePilot 提供三种对话模式，可在输入框上方随时切换：

代码模式

默认模式。Claude 拥有完整的工具权限，可以：

  • 读写项目文件
  • 执行终端命令
  • 调用 MCP 工具
  • 搜索代码库

适合日常开发任务：写代码、修 Bug、重构、部署。

计划模式

规划模式。Claude 只进行分析和方案制定，不会执行任何操作。

  • 分析问题并给出实施方案
  • 列出需要修改的文件和步骤
  • 评估不同方案的优劣

适合在动手之前理清思路，或者评估大型改动的影响范围。

问答模式

问答模式。Claude 只回答问题，不使用任何工具。

  • 解释代码逻辑
  • 回答技术问题
  • 讨论架构设计

适合纯粹的知识问答场景，不需要 Claude 接触项目文件。

权限控制

会话权限

每次对话可以选择权限级别：

  • 默认权限 — Claude 执行敏感操作（写文件、运行命令）前会请求确认
  • 完全访问 — Claude 可以自动执行所有操作，无需逐一确认

权限选择器位于对话输入框旁。对于探索性任务建议使用默认权限，对于信任的重复性任务可以使用完全访问。

权限弹窗

当 Claude 需要执行受限操作时，会弹出权限确认对话框，显示：

  • 工具名称和参数
  • 操作说明
  • 允许 / 拒绝按钮

你可以逐一审核 Claude 的每个操作。

上下文管理

上下文用量指示器

输入框旁的圆形进度条显示当前对话的上下文窗口使用情况。鼠标悬停可以看到详细信息：

  • 已使用的 Token 数
  • 总可用 Token 数
  • 使用百分比

当上下文接近上限时，Claude 会自动压缩历史消息以继续对话。

对话回退

CodePilot 支持将对话回退到之前的某个节点。每条用户消息都是一个回退点 — 你可以回到任意一条之前的消息，从那里重新开始对话。

输入功能

文件附件

在输入框中可以附加图片文件，让 Claude 分析截图或设计稿。支持拖放或点击附件按钮。

斜杠命令

输入 / 触发斜杠命令菜单，快速执行常用操作。

@-提及

输入 @ 可以引用文件或上下文，帮助 Claude 聚焦到特定内容。

会话管理

导入 CLI 会话

如果你之前使用过 Claude Code CLI，可以通过导入会话功能将 CLI 中的对话导入到 CodePilot。支持搜索和筛选历史会话。

服务商切换

对话头部显示当前使用的服务商。你可以在对话中途切换服务商，切换后的消息将使用新服务商处理。每个对话会记住其服务商设置。

File: apps/site/content/docs/zh/cli-tools.mdx

title: CLI 工具

CLI 工具

很多 AI 工作流需要配合命令行工具——用 FFmpeg 处理视频、用 jq 解析 JSON、用 ripgrep 搜索代码。CodePilot 的 CLI 工具功能帮你管理这些工具，并让 Claude 自动知道你的电脑上有什么可用。

为什么需要这个功能？

当你跟 Claude 说"帮我把这个视频转成 MP4"，Claude 需要知道你的系统上是否安装了 FFmpeg。如果不知道，它只能给出通用建议；如果知道，它可以直接给你一条可以执行的命令。

CLI 工具功能做了三件事：

  1. 检测 — 自动扫描你系统上已安装的命令行工具
  2. 推荐 — 提供精选工具列表，一键安装
  3. 感知 — 在对话中自动告诉 Claude 你有哪些工具，让它给出更精准的回答

打开工具管理

点击左侧导航栏的 CLI Tools 图标（终端图标）进入管理页面。

页面分为两个区域：

  • 已安装 — 系统上检测到的工具，显示版本号和状态
  • 推荐 — 精选的常用 AI 工作流工具，可以直接安装

安装工具

在推荐区找到你需要的工具，点击 安装 按钮。

如果工具支持多种安装方式（如 Homebrew、npm），会先让你选择。安装过程中会实时显示终端日志，你可以看到完整的安装输出。

目前推荐的工具包括：

工具 用途 安装方式
FFmpeg 音视频转码、剪辑、合并 Homebrew
jq JSON 数据解析和转换 Homebrew
ripgrep 极速文本搜索（比 grep 快得多） Homebrew
yt-dlp 视频下载 Homebrew / pipx
pandoc 文档格式转换（Markdown、Word、PDF 互转） Homebrew

查看工具详情

点击工具卡片上的 详情 按钮，可以看到：

  • 工具简介 — 这个工具能做什么
  • 适用场景 — 最常见的使用方式
  • 操作引导 — 从安装到上手的步骤
  • 示例提示词 — 可以直接复制到对话中使用的提示词

示例提示词是这个功能最实用的部分。比如 FFmpeg 的示例提示词：

"把 input.mov 转换成 MP4 格式，保持原始质量"

点击旁边的复制按钮或"发送到聊天"按钮，就可以直接用这个提示词开始对话。

AI 自动完善介绍

已安装的工具支持用 AI 生成更详细的介绍。点击工具卡片上的 自动完善 按钮，Claude 会根据工具的名称和用途生成一段中英双语的详细描述。

这个描述会保存在本地，下次打开时自动显示。

在对话中使用

自动感知（推荐）

安装好工具后，不需要做任何额外操作。CodePilot 会在每次对话时自动检测你的已安装工具，并在 system prompt 中告诉 Claude。

这意味着当你说：

"帮我把这个目录下所有的 .mov 文件转成 .mp4"

Claude 会知道你有 FFmpeg，直接给出可执行的命令，而不是先问你"是否安装了 FFmpeg"。

手动选择工具

如果你想明确告诉 Claude 使用某个特定工具，可以在聊天输入框的工具栏中点击 终端图标，打开 CLI 工具选择器。

选择一个工具后：

  • 如果输入框为空，会自动预填一段引导文字，比如"我想用 FFmpeg 工具完成：" — 你只需补充具体需求
  • 如果输入框已有内容，会在消息上附加一个工具标记，Claude 会优先使用这个工具来回答

最佳实践

描述需求而不是命令

不好的用法：

"运行 ffmpeg -i input.mov -c:v libx264 output.mp4"

好的用法：

"把 input.mov 转成 MP4，画质保持不变，文件尽量小"

让 Claude 来选择最优的参数组合。它比大多数人更了解 FFmpeg 的编码选项。

组合多个工具

CLI 工具之间可以组合使用。比如：

"从这个 YouTube 链接下载视频，然后裁剪前 30 秒，转成 GIF"

如果你安装了 yt-dlp 和 FFmpeg，Claude 会把它们串联起来，给你一个完整的工作流。

用示例提示词起步

不确定怎么用一个工具？打开它的详情页，从示例提示词开始。这些提示词覆盖了最常见的使用场景，是快速上手的好方法。

File: apps/site/content/docs/zh/design-agent.mdx

title: 设计 Agent

设计 Agent

设计 Agent 是 CodePilot 内置的 AI 图片生成功能。它通过 Claude 分析你的需求，然后调用 Gemini Image API 生成图片。

前提条件

使用设计 Agent 需要配置 Google Gemini (Image) 服务商：

  1. 前往 设置 > 服务商
  2. 点击 添加服务商，选择 Google Gemini (Image)
  3. 填写 API 密钥
  4. 点击 保存

单张生成

开启设计 Agent

在对话输入框右侧找到设计 Agent 开关，点击启用。启用后，你发送的消息会被 Claude 分析为图片生成意图。

生成流程

  1. 开启 Design Agent 开关
  2. 用自然语言描述你想要的图片
  3. Claude 分析你的需求，生成结构化的图片描述
  4. 弹出确认面板，你可以调整：
    • Prompt — 编辑生成提示词
    • 宽高比 — 选择比例（1:1、16:9、9:16、3:2、4:3 等 10 种）
    • 分辨率 — 选择 1K / 2K / 4K
  5. 点击生成，等待结果
  6. 生成的图片以卡片形式展示在对话中

参考图（垫图）

你可以上传参考图片来引导生成风格和构图。在输入框中附加图片，设计 Agent 会自动将其作为生成参考。

连续编辑

生成图片后，你可以直接描述修改需求（如"去掉右边的瓶子"），系统会自动将上一张生成结果作为参考图，实现连续迭代。

批量生成

设计 Agent 支持根据文档内容批量生成配图。

流程

  1. 在对话中上传文档或提供内容
  2. 描述你的配图需求和风格要求
  3. Claude 分析文档，生成批量生成计划：
    • 每张图的提示词
    • 宽高比和分辨率
    • 标签和来源引用
  4. 你可以逐一审核和编辑计划中的每一项
  5. 确认后开始批量生成
  6. 进度面板实时显示每张图的生成状态
  7. 失败的项目可以单独重试

查看历史

所有生成的图片会自动保存到素材库中，你可以随时回顾、下载或收藏。

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ai Browse ai catalog → #anthropic Browse anthropic catalog → #claude Browse claude catalog → #claude-code Browse claude-code catalog → #desktop-app Browse desktop-app catalog → #electron Browse electron catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →