用 cc-connect 将 Claude Code 接入飞书机器人

什么是 cc-connect？

cc-connect 是一个桥接工具，将本地 AI 编程助手（Claude Code、Cursor、Gemini CLI 等）连接到各类即时通讯平台（飞书、钉钉、Telegram、Slack、Discord 等）。

核心优势：

• 飞书接入使用 WebSocket 长连接，无需公网 IP
• 支持多项目、多平台同时接入
• 消息实时推送，响应延迟低

---

第一步：安装 cc-connect

方式 A：npm（推荐）

npm install -g cc-connect

方式 B：Homebrew（macOS / Linux）

brew install cc-connect

方式 C：下载二进制

前往 https://github.com/chenhg5/cc-connect/releases 下载对应平台的二进制文件。

# macOS 示例（下载后去除隔离属性）
xattr -d com.apple.quarantine cc-connect
chmod +x cc-connect
sudo mv cc-connect /usr/local/bin/

方式 D：源码编译（需要 Go 1.22+）

git clone https://github.com/chenhg5/cc-connect.git
cd cc-connect
make build

验证安装：

cc-connect --version

---

第二步：确认 Claude Code 已安装

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

---

第三步：创建飞书企业自建应用

3.1 进入飞书开放平台

访问 https://open.feishu.cn，登录飞书账号，点击右上角「控制台」。

个人用户也可以创建企业自建应用，无需企业认证。

3.2 创建应用

1. 点击「创建企业自建应用」
2. 填写应用名称（如 Terry助理）、描述
3. 上传应用图标
4. 点击「确定创建」

3.3 获取凭证

进入应用详情页，左侧导航点击「凭据与基础信息」，记录：

• App ID ：格式为 cli_xxxxxxxxxxxx
• App Secret：妥善保存，忘记后需重置

---

第四步：配置应用能力

4.1 启用机器人

左侧「应用能力」→「机器人」→ 点击「启用机器人」。

4.2 配置权限

左侧「权限管理」→「权限配置」，搜索并添加以下权限：

权限标识	说明
contact:user.base:readonly	获取用户基本信息
im:message.group_at_msg:readonly	接收群组中@机器人的消息
im:message.p2p_msg:readonly	接收用户私聊消息
im:message:send_as_bot	以机器人身份发送消息

---

第五步：配置事件与回调订阅

左侧「事件与回调」。

5.1 事件配置

1. 点击「事件配置」标签
2. 订阅方式选择「使用长连接接收事件」→ 保存
3. 点击「添加事件」，搜索并添加：im.message.receive_v1（接收消息）

5.2 回调配置

1. 点击「回调配置」标签
2. 订阅方式同样选择「使用长连接接收事件」→ 保存
3. 点击「添加回调」，添加：card.action.trigger（响应交互卡片按钮）

如果不添加 card.action.trigger，用户点击卡片按钮时将无响应。若暂时无法配置，可在 config.toml 中设置 enable_feishu_card = false 回退到纯文本模式。

---

第六步：发布应用

1. 左侧「版本管理与发布」→「创建版本」
2. 填写版本号（如 1.0.0）和更新说明
3. 可用范围：选「所有成员」或手动添加自己
4. 点击「保存并发布」

企业版需要管理员审批；个人版发布后立即生效。

---

第七步：配置 cc-connect

cc-connect 默认读取 ~/.cc-connect/config.toml。创建配置文件：

mkdir -p ~/.cc-connect

写入以下内容（替换为你的实际值）：

[log]
level = "info"

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/path/to/your/project"  # 替换为你的项目绝对路径
mode = "default"

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

[projects.platforms.options]
app_id = "cli_xxxxxxxxxxxx"      # 替换为你的 App ID
app_secret = "xxxxxxxxxxxxxxxxx" # 替换为你的 App Secret

agent mode 说明

mode	说明
default	标准模式，工具调用需用户确认
acceptEdits	自动接受文件编辑，其他操作仍需确认
auto	全自动执行，无需确认
plan	仅规划，不执行

---

第八步：多项目配置

如果你有多个项目需要接入飞书，有两种方案。

多项目共用同一个飞书应用（推荐 monorepo）

适合同一个代码仓库下的多个子服务，只需一个飞书机器人：

[log]
level = "info"

[[projects]]
name = "project-a"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/path/to/project-a"
mode = "default"

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

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


[[projects]]
name = "project-b"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/path/to/project-b"
mode = "default"

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

[projects.platforms.options]
app_id = "cli_xxxxxxxxxxxx"      # 同一个飞书应用
app_secret = "xxxxxxxxxxxxxxxxx"

多项目共用同一机器人时，在飞书中通过 /dir 命令切换当前操作的项目。

---

第九步：后台运行 cc-connect

方式一：nohup（最简单）

nohup cc-connect > ~/.cc-connect/cc-connect.log 2>&1 &
echo $! > ~/.cc-connect/cc-connect.pid

查看日志：

tail -f ~/.cc-connect/cc-connect.log

停止服务：

kill $(cat ~/.cc-connect/cc-connect.pid)

方式二：launchd（macOS 推荐，开机自启）

先确认 cc-connect 路径：

which cc-connect

创建 plist 文件（替换路径为实际值）：

cat > ~/Library/LaunchAgents/com.ccconnect.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.ccconnect</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/cc-connect</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/terry/.cc-connect/cc-connect.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/terry/.cc-connect/cc-connect.log</string>
    <key>WorkingDirectory</key>
    <string>/Users/terry/.cc-connect</string>
</dict>
</plist>
EOF

加载并启动：

launchctl load ~/Library/LaunchAgents/com.ccconnect.plist
launchctl start com.ccconnect

常用命令：

launchctl stop com.ccconnect                                    # 停止
launchctl unload ~/Library/LaunchAgents/com.ccconnect.plist    # 卸载（取消开机自启）
tail -f ~/.cc-connect/cc-connect.log                           # 查看日志

launchd 支持开机自启和崩溃自动重启，生产环境推荐使用。

方式三：screen / tmux（保持终端会话）

# 使用 screen
screen -S ccconnect
cc-connect
# Ctrl+A D 脱离会话，服务继续运行

# 重新接入会话
screen -r ccconnect

---

第十步：启动 cc-connect

cc-connect
# 或指定配置文件
cc-connect -config ~/.cc-connect/config.toml

成功启动的日志特征

feishu: bot identified open_id=ou_xxxxxxxxxxxxxxxx
feishu: interactive card mode enabled
platform ready project=my-project platform=feishu
engine started project=my-project agent=claudecode platforms=1
cc-connect is running projects=1
[Info] connected to wss://msg-frontier.feishu.cn/ws/v2?...

关键指标：

• bot identified --- 机器人身份验证成功
• connected to wss://msg-frontier.feishu.cn --- WebSocket 长连接建立成功

---

第九步：在飞书中找到并使用机器人

私聊

飞书 App → 搜索栏输入机器人名称 → 点击进入 → 发送消息。

群聊

进入目标群聊 → 群设置 → 「群机器人」→ 添加你的机器人 → 在群里 @ 机器人发消息。

---

使用示例

你：帮我分析一下当前项目的目录结构

Terry助理：🤔 思考中...
Terry助理：🔧 执行: Bash(ls -la)
Terry助理：✅ 这是一个 Spring Boot 项目，包含以下模块...

---

常见问题

Q：找不到机器人？

检查「版本管理与发布」中应用状态是否为「已上线」，以及可用范围是否包含自己。

Q：启动报 api code=11205？

缺少机器人相关权限，去权限管理添加 contact:user.base:readonly 后重新发布版本。

Q：点击卡片按钮无响应？

确认已在「回调配置」中添加 card.action.trigger 并重新发布版本。或在配置中设置 enable_feishu_card = false 关闭卡片模式。

Q：消息发出后没有回复？

1. 确认 cc-connect 正在运行
2. 查看日志是否有 connected to wss:// 字样
3. 确认事件订阅中已添加 im.message.receive_v1

---

架构示意

飞书 App（手机/PC）
       │
       ▼
飞书开放平台 WebSocket Gateway
       │
       │  长连接（无需公网 IP）
       ▼
cc-connect（本地运行）
       │
       ▼
Claude Code CLI
       │
       ▼
你的项目代码

---