CC Connect 使用教程

这篇笔记的目标，是把 cc-connect 放到一个准确的位置上理解清楚。很多人第一次看到它，会把它理解成“手机上运行 Claude Code”“另一个模型平台”“类似 cc-switch 的 API 切换器”，这些理解都不对。cc-connect 真正解决的问题，是把运行在本机或服务器上的 AI Agent，桥接到日常聊天平台里，让聊天窗口变成一个远程控制入口。

正文会先解释它到底解决什么问题，再拆开 Project、Agent、Platform、Provider 这几个最容易混淆的对象，然后给出一条以 Claude Code + 飞书 为例的最小可用上手路径，最后补充权限模式、会话切换、定时任务、附件回传和常见误区。重点不是“点哪个按钮”，而是把链路和分工讲清楚，这样后续切到 Telegram、微信个人号、企业微信或其他 Agent 时，思路不会乱。

参考资料：

官方总览：cc-connect README.zh-CN 、 cc-connect README

安装与配置：INSTALL.md 、 usage.zh-CN.md

平台接入：Feishu Guide 、 Weixin Guide

站内前文：CC Switch 使用教程 、 Claude Code 使用教程

[TOC]

一、CC Connect 到底解决什么问题

如果只在电脑前打开终端使用 Claude Code，那么整个交互入口只有一个：

• 人坐到电脑前
• 打开终端
• 进入项目目录
• 启动 Agent
• 在当前会话里继续工作

这条链路当然能用，但它有一个非常明显的限制：

Agent 能力在电脑里，控制入口也被锁死在电脑里。

一旦离开工位，很多场景都会变得不顺手：

• 想在手机上让 Agent 跑一次代码审查
• 想临时查一下某个仓库里的配置
• 想让 Agent 继续执行一个较长的任务
• 想通过聊天消息安排定时任务或远程导出文件
• 想在团队常用的 IM 平台里直接和 Agent 协作

cc-connect 解决的，就是这类“Agent 在本地，控制入口太单一”的问题。

它不是把 Agent 迁移到云端，而是把本地 Agent 的控制面桥接到聊天平台：

可以概括为：

cc-connect 的核心价值，不在“让模型更强”，而在“把本地 Agent 的控制入口从终端扩展到聊天平台”。

二、先建立正确的心智模型

开始之前，必须把几个对象分开。很多配置混乱，本质上都是因为把这些层次混成一团。

Agent

Agent 是真正执行任务的一方，例如：

• Claude Code
• Codex
• Gemini CLI
• Cursor Agent
• OpenCode
• Qoder CLI

它负责读仓库、改文件、跑命令、执行工具调用。

Platform

Platform 指消息入口，也就是用户在哪个聊天平台发消息：

• 飞书
• 钉钉
• Telegram
• Slack
• Discord
• 企业微信
• 微信个人号
• QQ

Platform 负责接收用户消息和回传结果，但它本身不执行开发任务。

Project

Project 是 cc-connect 最关键的组织单位。它把下面这些内容绑定在一起：

• 一个项目名称
• 一个 Agent 类型
• 一个默认工作目录
• 一组平台接入配置
• 可选的 Provider 配置
• 会话、权限模式、目录切换等运行期状态

也就是说，Project 不是“Git 仓库本身”，而是“一个可被聊天平台远程控制的 Agent 工作单元”。

Provider

Provider 是 Agent 调用模型时所连接的模型服务端。

这层是否一定要在 cc-connect 里配置，要看具体使用方式：

• 如果 Claude Code 已经走原生登录或已有现成环境配置，cc-connect 可以直接复用
• 如果希望在 cc-connect 中显式管理 API Key、base_url、模型列表和多 Provider 切换，就需要配置 Provider
• 如果前面已经用 cc-switch 管理好了 Provider，还可以导入到 cc-connect

Web UI

Web UI 只是管理面，不是运行面。

这一点非常重要，因为很多第一次上手的人会误以为：

执行了 cc-connect web，服务就已经启动了。

实际上不是。

• cc-connect web 的职责是打开和配置管理后台
• 真正处理消息、连接平台、驱动 Agent 的，是 cc-connect 主进程

一张图看清对象关系

graph TB
    U[用户] --> P[聊天平台 Platform]
    P --> C[cc-connect]
    C --> PRJ[Project]
    PRJ --> A[Agent]
    PRJ --> PV[Provider]
    A --> R[代码仓库 / 工作目录]
    PV --> M[模型服务]

这张图表达的是：

• Platform 是入口
• Project 是组织单元
• Agent 是执行者
• Provider 是模型后端
• cc-connect 负责把这几层串起来

三、CC Connect 的工作链路

如果只看“聊天里发一句话，Agent 就执行了”，会很容易忽视它中间真正做了什么。

完整链路可以拆成下面几步：

1. 用户在聊天平台发消息
2. 平台把消息交给 cc-connect
3. cc-connect 根据消息所属平台和项目，找到对应 Project
4. Project 选择对应 Agent、工作目录、权限模式、Provider
5. Agent 在本地代码仓库中执行任务
6. 执行结果再由 cc-connect 格式化后回传到聊天平台

如果用时序图表示，会更直观：

sequenceDiagram
    participant User as 用户
    participant IM as 聊天平台
    participant CC as cc-connect
    participant Agent as Claude Code 等 Agent
    participant Repo as 本地仓库
    participant Provider as 模型 Provider

    User->>IM: 发送任务消息
    IM->>CC: 推送消息事件
    CC->>CC: 定位 Project / Session / 权限模式
    CC->>Agent: 启动或复用 Agent 会话
    Agent->>Repo: 读取文件 / 执行命令 / 修改代码
    Agent->>Provider: 发起模型请求
    Provider-->>Agent: 返回模型结果
    Agent-->>CC: 输出文本 / 引用 / 附件
    CC-->>IM: 回传消息
    IM-->>User: 展示结果

这里最值得注意的点有三个。

它不是聊天机器人 SaaS

cc-connect 自己不生成答案，它只是桥接器和运行控制层。真正“思考”和“执行”的仍然是底层 Agent。

它不是终端复刻

远程聊天窗口并不是把本地终端画面原样投到手机上，而是把 Agent 的能力包装成消息式交互。

它不是简单 webhook 转发器

如果只是收消息再转给某个脚本，那只是“消息触发器”。cc-connect 额外处理了很多运行期问题：

• 会话管理
• 权限模式切换
• 工作目录切换
• Provider / 模型切换
• 附件回传
• 多项目隔离
• 平台适配

所以更准确的理解是：

cc-connect 是一个面向本地 AI Agent 的聊天桥接层和运行控制面。

四、CC Connect、CC Switch、Claude Code 到底怎么分工

这三个名字经常一起出现，但它们根本不是同一层。

可以把三者的关系理解成：

graph LR
    A[聊天入口]
    B[cc-connect]
    C[Claude Code]
    D[cc-switch]
    E[模型 Provider]
    F[代码仓库]

    A --> B
    B --> C
    C --> F
    C --> D
    D --> E

这张图要表达的不是“必须这样串联”，而是分工关系：

• Claude Code 决定怎么完成任务
• cc-connect 决定怎么从聊天入口把任务送到 Agent
• cc-switch 决定 Agent 背后连哪个 Provider、走哪条路由

什么场景更需要 CC Connect

• 经常离开电脑，但仍想远程调度 Agent
• 希望在 IM 里直接与 Agent 协作
• 希望一个进程管理多个项目和多个平台
• 希望把定时任务、附件回传、会话切换都放在同一套入口里

什么场景只需要 CC Switch，不一定需要 CC Connect

• 仍然主要在终端里使用 Agent
• 只是想切 Provider 或统一管理多 CLI 配置
• 不需要聊天平台桥接

什么场景只需要 Claude Code 原生形态

• 单机使用
• 需求简单
• 不需要远程控制
• 不需要多平台消息接入

五、安装前先想清楚的三件事

cc-connect 安装本身不复杂，真正复杂的是“装完之后到底想让它接什么”。

开始前先回答三个问题：

用哪个 Agent

第一轮上手只选一个就够了，最常见的是：

• Claude Code
• Codex
• Gemini CLI

不要第一次就同时绑四五个 Agent，否则一旦出问题，很难判断是哪个层次出错。

用哪个 Platform

不同平台的接入方式差异非常大，有的平台不需要公网，有的平台需要回调地址。

如果只是先跑一条最小链路，优先选：

• 飞书
• Telegram
• 钉钉

Provider 由谁管理

这一点非常容易漏掉。

模型后端有三种常见管理方式：

1. 交给 Agent 自己原生登录或环境变量
2. 交给 cc-connect 项目内的 Provider
3. 交给 cc-switch 管理，再导入到 cc-connect

如果这层没有先想清楚，后面很容易出现“消息已经打通，但 Agent 请求模型失败”的情况。

六、正确的安装顺序

推荐按下面顺序准备：

1. 先安装目标 Agent，例如 Claude Code
2. 验证 Agent 本体可在终端中正常运行
3. 再安装 cc-connect
4. 配置聊天平台
5. 最后做一次最小可用验证

原因很简单：

• cc-connect 不是 Agent 的替代安装器
• 它桥接的是“已经可运行的 Agent”
• 如果 Agent 本体都没跑通，后面的桥接根本没有验证基础

常见安装方式

通过 npm

1
2
npm install -g cc-connect
cc-connect --version

通过 Homebrew

1
2
brew install cc-connect
cc-connect --version

macOS 二进制下载后的一个细节

如果是从 Releases 直接下载二进制，在 macOS 上可能还需要移除隔离属性：

1
xattr -d com.apple.quarantine cc-connect

先验证 Agent 本体

以 Claude Code 为例，至少先确认：

1
claude --version

如果还没安装，可以先安装：

1
npm install -g @anthropic-ai/claude-code

如果连 claude 都无法正常启动，就不要急着碰 cc-connect 的平台接入。

七、配置方式有两条线，但推荐先走 Web UI

官方现在明确推荐优先使用 Web UI，而不是上来手写 config.toml。

路线一：Web UI

这是更适合第一次上手的方式。

1
cc-connect web

这个命令的作用是：

• 配置并打开 Web 管理后台
• 可视化创建项目
• 管理平台
• 管理 Provider
• 在浏览器里直接和 Agent 聊天

但要再强调一遍：

cc-connect web 只负责管理面，不等于服务已经启动。

真正启动服务，仍然需要：

1
cc-connect

路线二：手动 TOML 配置

如果更喜欢显式配置，也可以直接维护 config.toml。

常见位置顺序是：

1. -config <path> 指定路径
2. 当前目录 ./config.toml
3. 全局 ~/.cc-connect/config.toml

如果没有配置文件，首次运行 cc-connect 会自动生成一个初始模板。

一个最小结构长什么样

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/absolute/path/to/your/project"
mode = "default"

[[projects.platforms]]
type = "feishu"

[projects.platforms.options]
app_id = "cli_xxxxxxxxxxxx"
app_secret = "xxxxxxxxxxxxxxxx"

这段配置最重要的不是字段本身，而是表达了 cc-connect 的组织方式：

• 一个 Project
• 一个 Agent
• 一个默认工作目录
• 至少一个 Platform

如果还需要多 Provider，再继续补：

1
2
3
4
5
6
7
8
[projects.agent.options]
provider = "relay"

[[projects.agent.providers]]
name = "relay"
api_key = "sk-xxx"
base_url = "https://api.example.com"
model = "claude-sonnet-4-20250514"

八、以 Claude Code + 飞书为例走通最小可用链路

这一节只追求一件事：

让一条完整链路真正跑起来，而且能定位问题、能回退、能复现。

第一步：确认 Claude Code 本体可用

先在终端里确认：

1
claude --version

必要时先手动启动一轮 Claude Code，确保账号、权限和本地环境没有问题。

第二步：启动 Web UI，创建项目

1
cc-connect web

进入后台后，先只创建一个项目，例如：

• Project Name: my-backend
• Agent Type: claudecode
• work_dir: 本地项目绝对路径
• mode: default

第一轮不要急着加很多项目，先只保留一个。

第三步：决定 Provider 怎么接

这一步有三种典型方式。

方式一：先复用 Claude Code 现有可用配置

适合已经能在终端里正常使用 Claude Code 的情况。这样可以先验证桥接链路，不把问题复杂化。

方式二：在 cc-connect 中直接加 Provider

适合想在 cc-connect 里统一管理 API Key、base_url 和模型列表的情况。

方式三：从 cc-switch 导入

如果前面已经用 cc-switch 管好了模型服务和路由，最省事的方式通常是直接导入：

1
cc-connect provider import --project my-backend

这条命令的价值很直接：

• 避免重复录入 Provider
• 保持 cc-switch 和 cc-connect 的配置一致
• 方便后续做模型切换和统一管理

第四步：为项目接入飞书

官方为飞书提供了统一入口命令：

1
cc-connect feishu setup --project my-backend

如果已经有现成的 App ID 和 App Secret，也可以直接绑定：

1
cc-connect feishu setup --project my-backend --app cli_xxx:sec_xxx

这个过程本质上会做几件事：

• 如果项目不存在，就自动创建项目
• 如果项目中还没有 feishu 平台配置，就自动补上
• 把飞书凭证写回 config.toml

第五步：在飞书开放平台核验关键项

即便通过 CLI 完成了配置，也建议在飞书开放平台再核对一次：

• 已启用 Bot 能力
• 已授权 im:message.receive_v1
• 已授权 im:message:send_as_bot
• 已配置事件 im.message.receive_v1
• 已发布版本

如果这里漏掉，表面上看像是 cc-connect 没反应，实际上是平台侧根本没有把消息送过来。

第六步：真正启动服务

1
cc-connect

这里一定要记住：

• cc-connect web 不是服务主进程
• 真正接收飞书消息、驱动 Agent 的，是这个主进程
• 如果这个进程停掉，聊天入口就会失效

第七步：做一次最小验证

建议不要一上来就让它改一堆代码，而是先发一条非常短的消息：

1
读取当前仓库根目录，概括项目结构，不要修改文件

验证时观察四件事：

1. 飞书里是否能收到回复
2. Agent 是否真的在正确的 work_dir 里工作
3. 回复是否体现出当前仓库的真实结构
4. 是否出现权限审批提示

只有这一步通过，才说明整条链路真的通了：

• 平台接入是通的
• cc-connect 主进程是活的
• Project 绑定是对的
• Claude Code 本体是可用的
• 当前 Provider 配置没有拦路

九、运行期最常用的不是安装命令，而是聊天命令

cc-connect 真正进入日常工作流之后，最高频使用的通常不是安装命令，而是会话内控制命令。

会话管理

这里有一个很重要的特点：

cc-connect 不是“每条消息都起一个全新 Agent”，而是维护项目级会话。

因此，会话切换直接决定上下文是否延续。

权限模式切换

对 Claude Code 来说，常用模式包括：

聊天里可以直接切：

1
2
3
/mode
/mode yolo
/mode default

这层在手机远程使用时尤其重要，因为一旦权限策略过松，远程入口就可能变成“任何消息都能直接改本地仓库”的高风险通道。

Provider 和模型切换

如果项目里配置了 Provider 和模型列表，就可以在聊天里直接切：

1
2
3
4
5
/provider
/provider list
/provider switch relay
/model
/model switch sonnet

这说明 cc-connect 不只是消息桥，它还把运行期控制动作也搬到了聊天窗口中。

工作目录切换

很多人把项目和工作目录理解成同一件事，但运行时它们并不完全等价。

1
2
3
/dir
/dir ../another-repo
/dir -

/dir 影响的是当前项目下一次会话所使用的工作目录。也就是说，一个 Project 可以在受控范围内切换到不同目录工作。

这很强大，但也意味着必须做好权限控制。

引用查看

如果 Agent 回答里提到了某个文件、某段代码，可以直接看：

1
2
3
/show src/main.ts
/show src/main.ts:20
/show docs/

这个能力的意义，在远程场景里尤其大，因为不需要重新回到终端手敲 cat、sed、less。

十、长期运行时要补上的两层配置

如果只是临时试用，跑通一次就可以。

但只要真的准备把 cc-connect 当成日常入口，就有两层配置迟早要补。

让主进程稳定常驻

远程桥接有一个天然前提：

cc-connect 主进程必须活着，聊天入口才是真的活着。

如果服务跑在本地终端，终端一关、机器一睡眠、进程一退出，平台入口就会中断。

因此实际使用时，通常至少要考虑其中一种方式：

• 在长期在线的开发机或服务器上运行
• 配合系统守护进程保持常驻
• 明确区分“临时调试环境”和“长期可达环境”

如果只是偶尔本机调试，手动执行 cc-connect 足够；如果希望它成为稳定入口，就不能把它当成一次性命令。

避免会话无限漂移

远程聊天和本地终端不同，一个很常见的问题是会话越聊越长，最后上下文开始漂移。

官方提供了 reset_on_idle_mins，可以在项目空闲一段时间后，下一条普通消息自动进入新会话：

1
2
3
[[projects]]
name = "demo"
reset_on_idle_mins = 60

这项配置适合解决两类问题：

• 长时间不用后继续沿用旧上下文，导致判断失真
• 远程聊天跨度太大，一个会话塞进了太多无关任务

它不会删除旧会话，旧会话仍然可以通过 /list 找回，但新的普通消息会自动落到一个更干净的上下文里。

十一、远程场景下最需要重视的是权限边界

cc-connect 一旦接入飞书、微信、Telegram 这类高可达平台，权限问题就不再只是“本地点不点确认”的问题，而是“谁可以远程驱动本地 Agent”。

不要默认把远程入口当成安全环境

本地终端前通常只有一个人，但聊天平台未必。

风险往往来自：

• 群聊误触发
• 平台机器人被其他成员使用
• 手机端随手切成 yolo
• 工作目录切到了不该动的仓库
• Agent 获得了过宽的工具权限

admin_from 的意义

官方文档里，像 /dir、/shell、/show 这类命令可以通过 admin_from 控制。

它解决的是：

• 哪些用户可以执行高权限命令
• 哪些用户只能发普通任务，不允许做环境级操作

如果准备长期使用远程控制，建议尽早把这层收紧，而不是等出问题再补。

远程模式建议从保守权限起步

推荐的起步方式是：

十二、定时任务、附件回传、多项目，分别解决什么问题

如果只把 cc-connect 用成“手机上发一句话给 Agent”，其实只用了它一部分能力。

定时任务解决的是“持续触发”

官方文档里，cc-connect 支持通过自然语言或相关命令配置 cron 任务。

适合的场景包括：

• 每天定时总结某个仓库变更
• 定时检查构建状态
• 定时生成日报或周报
• 定时抓取某个公开信息源并让 Agent 做整理

这里要理解的重点不是“多了个 cron 命令”，而是：

cc-connect 把 Agent 从“被动回答消息”扩展成“可被持续调度的本地执行单元”。

附件回传解决的是“结果交付”

当 Agent 在本地生成：

• 图片
• PDF
• 报表
• 日志包
• Markdown 导出

就不该只回复一句“文件已经生成”。更好的交付方式，是直接把文件回传到当前聊天里。

官方提供了：

1
2
cc-connect send --image /absolute/path/to/chart.png
cc-connect send --file /absolute/path/to/report.pdf

这类命令的意义在于，聊天平台不只是控制入口，也可以变成结果交付出口。

多项目模式解决的是“隔离”

一个 cc-connect 进程可以管理多个项目，每个项目都可以有自己的：

• work_dir
• Agent
• Platform
• Provider
• 会话历史

这对于同时维护多个仓库的人非常重要，否则所有任务都混在一个 Agent 里，长期一定会失控。

十三、几个非常容易踩的坑

1. 以为 cc-connect web 就等于服务已经启动

这是最常见的问题。

正确理解是：

• cc-connect web 负责管理面
• cc-connect 负责服务主进程

如果只开了 Web UI，没有开主进程，平台消息是不会被处理的。

2. 以为它会替 Agent 完成安装

不会。

cc-connect 桥接的是“已经存在的 Agent”。如果 Claude Code 本身就不可用，桥接层不可能替它补齐。

3. 以为所有平台都不需要公网 IP

也不对。

很多平台确实可以通过 WebSocket 或 Long Polling 工作，不需要公网，但不是全部都这样。像某些 Webhook 型接入就需要公网 URL。

4. 以为 Project 就等于 Git 仓库

并不完全等价。

Project 是 cc-connect 的管理单元，仓库只是它默认绑定的工作目录之一。

5. 以为切模型不会影响当前运行状态

官方文档明确提到，某些模型切换作用于共享的 Agent 实例。如果多个平台共用同一个项目，那么模型切换会影响所有这些入口。

6. 远程场景上来就开 yolo

这通常不是一个好主意。

远程入口一旦开放，风险面本来就比本地终端大。第一次上手更适合先用 default 或 acceptEdits，把链路和权限边界摸清楚之后再放开。

十四、什么人最适合用 CC Connect

cc-connect 非常适合下面几类人：

• 重度使用 Claude Code、Codex、Gemini CLI 等 Agent
• 希望通过手机或 IM 平台随时触发任务
• 同时维护多个项目，希望统一管理远程控制入口
• 需要把分析结果、截图、报表直接回传到聊天平台
• 已经在用 cc-switch，想把 Provider 管理和聊天桥接组合起来

但它未必适合所有人。

下面这些场景，收益通常没那么明显：

• 只在电脑前短时使用 Agent
• 不需要远程控制
• 不想维护机器人凭据和平台接入
• 对权限、安全和运行稳定性没有精力额外管理

因此，是否值得上 cc-connect，本质上不是“功能多不多”，而是：

本地 Agent 的控制入口，是否已经需要从终端扩展到消息平台。

十五、总结

cc-connect 可以概括为一个 把本地 AI Agent 桥接到聊天平台的运行控制层。

理解它时，最重要的不是记住某个命令，而是记住下面几条主线：

• 它管理的是 Project，不是单个命令
• 它桥接的是 Platform 和 Agent，不是替代 Agent
• Provider 可以由 Agent、cc-connect 或 cc-switch 管理
• cc-connect web 是管理面，cc-connect 才是运行面
• 会话、权限、目录、模型、附件回传，决定了它不是简单消息转发器

如果只是做最小上手，最稳妥的路径通常是：

1. 先把一个 Agent 跑通，例如 Claude Code
2. 只创建一个 Project
3. 只接一个平台，例如飞书
4. 先跑一条只读型验证消息
5. 确认链路稳定后，再逐步开启 Provider 切换、定时任务和更高权限模式

这样理解和使用 cc-connect，通常会比“照着命令一路复制”更稳，也更容易真正把它放进日常 AI 工程工作流里。

• Previous
  MQ 消息场景题思考
• Next
  CC Switch 使用教程