《AtomCode 飞书助手极简配置教程》课程

欢迎使用 AtomCode 飞书渠道插件。通过本教程，你可以将 AtomCode 的 Agent 能力接入飞书 / Lark。

本教程去除了所有复杂的后台配置，只需完成以下四步即可。

部分	主题
前置要求	AtomCode / Node.js / 飞书应用
核心流程	4 步走通
第一步	安装插件
第二步	创建飞书应用（7 小步）
第三步	写入配置文件
第四步	启动 daemon + sidecar
附录 A	飞书渠道优势
附录 B	控制命令
附录 C	常见问题（FAQ）
附录 D	故障排查速查表

前置要求

AtomCode 版本：请确保你的 AtomCode 版本不低于 4.25.1。
Node.js 版本：飞书渠道依赖 @larksuite/channel SDK，需要 Node.js >= 22。
飞书开放平台应用：需要一个已开通机器人能力的飞书应用（下文会引导你创建）。

一句话点睛：3 个硬门槛——AtomCode 4.25.1+、Node.js 22+、一个飞书应用。少一个跑不起来。

核心流程

【第一步：装插件】 ──→ 【第二步：创建飞书应用】 ──→ 【第三步：写入配置】 ──→ 【第四步：启动】

一句话点睛：4 步流水线，按顺序来，别跳。

第一步：安装插件

打开你的 AtomCode TUI（终端界面）

atomcode

根据atomcode引导进行登陆，然后依次运行以下命令：

# 1. 添加插件市场源
/plugin marketplace add https://atomgit.com/atomgit_atomcode/AtomCode-Channel

# 2. 安装飞书插件
/plugin install feishu@atomcode-channel

# 3. 退出AtomCode 
/quit

# 4. 安装飞书 SDK 依赖
cd ~/.atomcode/plugins/marketplaces/atomcode-channel/plugins/feishu/adapter && npm install

国内用户提示：如果 npm install 因为网络原因卡住，可以临时切换到国内镜像源：
npm install --registry=https://registry.npmmirror.com

一句话点睛：3 行命令搞定一半。npm 卡了换国内镜像，一行的事。

第二步：创建飞书应用

飞书渠道用 appId + appSecret 直连飞书 WebSocket，无需公网回调域名，也无需扫码登录。

2.1 创建应用

打开飞书开放平台 → 点击「创建企业自建应用」（或选择已有应用）。

填写应用名称（例如 AtomCode 助手）和描述，上传一个图标，点击创建。

2.2 开通机器人能力

进入应用详情页 → 左侧菜单 「应用能力」→「机器人」。

点击「开启机器人」，按提示完成配置（默认即可）。

2.3 申请权限

进入左侧菜单 「权限管理」→「API 权限」，搜索并开通以下 IM 相关权限：

以下权限可以在权限管理页面搜索 im: 前缀快速筛选。

权限名	权限标识	说明
获取与发送单聊、群组消息	`im:message`	收发消息（必选）
以应用的身份发消息	`im:message:send_as_bot`	机器人身份发送消息（必选）
读取私聊消息	`im:message.p2p_msg:readonly`	接收用户私聊消息（必选）
接收群聊中@机器人消息事件	`im:message.group_at_msg:readonly`	接收群聊 @ 消息（必选）
获取单聊、群组消息（只读）	`im:message:readonly`	只读方式获取消息
获取单聊、群组的历史消息	`im:message.history:readonly`	获取历史消息
获取群组中所有消息	`im:message.group_msg`	获取群组全部消息
上传/下载图片和文件	`im:resource`	发送图片、文件等附件（必选）
获取与更新群组信息	`im:chat`	创建和管理群组
获取群组信息（只读）	`im:chat:readonly`	只读方式获取群信息
查看群成员	`im:chat.members:read`	获取群成员列表
添加、移除群成员	`im:chat.members:write_only`	管理群成员
订阅机器人进出群事件	`im:chat.members:bot_access`	感知机器人被加入/移出群
读取群信息（历史版本）	`im:chat.group_info:readonly`	兼容旧版群信息读取
读取用户和机器人的会话	`im:chat.access_event.bot_p2p_chat:read`	感知用户首次与机器人对话
获取客户端用户代理信息	`im:user_agent:read`	获取客户端 UA 信息
读取用户信息	`contact:user.base:readonly`	解析 @ 机器人时的用户身份（可选）

修改权限后需要重新发布应用版本才会生效。

一句话点睛：17 条权限，4 条必选、12 条只读、1 条可选。im: 前缀一键筛。

2.4 配置事件订阅（WebSocket 模式）

左侧菜单 「事件与回调」→「事件配置」。

选择 「使用长连接接收事件」 模式（不是「请求地址」模式）。
添加事件：接收消息 v2.0（im.message.receive_v1）。

一句话点睛：注意——选"长连接"，不是"请求地址"。AtomCode 是出站 WebSocket，不要公网域名。

2.5 获取 App ID 和 App Secret

左侧菜单 「凭证与基础信息」，页面上会显示 App ID（格式如 cli_xxxxxxxxxxxx）和 App Secret。

2.6 发布应用

左侧菜单 「版本管理与发布」 → 创建版本 → 提交发布。

企业管理员可直接审核通过；否则需要管理员审批。

2.7 在飞书里找到机器人

打开飞书客户端 → 搜索栏输入你的应用名（例如 AtomCode 助手），私聊发消息即可。

一句话点睛：7 小步——建应用、开机器人、申权限、配事件、拿凭证、发版本、找机器人。发版本前不生效。

第三步：写入配置文件

配置外置在 ~/.atomcode/feishu/config.json，不随插件丢失。

# 1. 创建配置目录
mkdir -p ~/.atomcode/feishu

# 2. 复制示例配置
cp ~/.atomcode/plugins/marketplaces/atomcode-channel/plugins/feishu/config.example.json ~/.atomcode/feishu/config.json

# 3. 编辑配置文件
vim ~/.atomcode/feishu/config.json

填入你在第二步获取的 App ID 和 App Secret：

{
  "appId": "cli_xxxxxxxxxxxx",
  "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "domain": "Feishu",
  "daemonBaseUrl": "http://127.0.0.1:13456",
  "workingDir": "/opt/atomgit",
  "allowlist": [],
  "provider": "",
  "thinkingAck": true,
  "daemonCmd": "atomcode daemon",
  "policy": {
    "requireMention": true,
    "dmMode": "open"
  }
}

# 4. 设置权限
chmod 600 ~/.atomcode/feishu/config.json

配置字段说明

字段	必填	说明
`appId`	✅	飞书开放平台 App ID（格式如 `cli_xxxxxxxxxxxx`）
`appSecret`	✅	飞书开放平台 App Secret
`domain`	选填	`"Feishu"`（国内默认）/ `"Lark"`（海外），默认 `"Feishu"`
`daemonBaseUrl`	选填	atomcode daemon 地址，默认 `http://127.0.0.1:13456`
`workingDir`	选填	默认工作目录（沙箱），建议设为项目根目录
`allowlist`	选填	聊天 ID 白名单，空数组 `[]` = 放行所有
`provider`	选填	指定模型 provider，空字符串 = daemon 默认
`thinkingAck`	选填	turn 开始发「🤔 正在思考…」，默认 `true`
`daemonCmd`	选填	未起 daemon 时自动拉起命令
`policy.requireMention`	选填	群聊中是否要求 @机器人才响应，默认 `true`
`policy.dmMode`	选填	私聊策略：`"open"`（所有私聊响应）/ `"allowlist"`（仅白名单）

一句话点睛：11 个字段，2 个必填、9 个选填。chmod 600 别忘——appSecret 明文存盘。

第四步：启动

配置写好后，手动启动 daemon 和 sidecar（需要开两个终端，或使用 disown 后台运行）：

启动 daemon

atomcode daemon --port 13456 --idle-timeout 0 &
disown

daemon 是 atomcode 的 HTTP 服务端，sidecar 通过它转发消息给 AI 模型。

启动飞书 sidecar

cd ~/.atomcode/plugins/marketplaces/atomcode-channel/plugins/feishu/atomcode
nohup node src/launch.js > /tmp/atomcode-feishu.log 2>&1 &
disown

加了 disown 后，进程不会因终端退出而被杀死，确保长期运行。

验证启动状态

tail -f /tmp/atomcode-feishu.log

正常启动时输出类似：

feishu 桥已启动。bot=AtomCode 助手 daemon=http://127.0.0.1:13456 workingDir=/opt/atomgit

看到这行日志后，打开飞书客户端搜索你的机器人名称（如 AtomCode 助手），即可开始对话。

一句话点睛：2 个进程——daemon 是 AI 大脑，sidecar 是飞书桥。disown 不加就白干。

附录 A · 飞书渠道优势

特性	说明
交互式卡片审批	工具执行审批用按钮点击，无需手动输入 y/n
无需扫码登录	appId + appSecret 直连，无登录步骤
WebSocket 长连接	SDK 内置自动重连 + keepalive 看门狗
消息归一化	SDK 处理文本/图片/文件/表情等，统一格式
安全管道	SDK 内置去重、防重放、策略门
无需公网域名	WebSocket 出站连接，无需回调 URL

一句话点睛：6 大优势——卡片审批 + WebSocket + 无扫码 + 无域名。光这 4 条就比大多数渠道少装 1 小时。

附录 B · 控制命令

命令	说明
`/pwd`	查看当前工作目录
`/cd <path>`	切换工作目录（切换后开新会话）
`/cd`	无参回到默认工作目录

一句话点睛：3 个命令只管目录，不管别的——AtomCode 自己的 /plan /build /goal /bg 全部继承。

附录 C · 常见问题 (FAQ)

Q：每次启动 atomcode 都要重新配置吗？

不需要。配置写在 ~/.atomcode/feishu/config.json，重装插件、重启 atomcode 都不会丢失。

Q：如果飞书机器人没有反应怎么办？

按以下顺序排查：

检查 sidecar 日志：tail -f /tmp/atomcode-feishu.log
检查 daemon 是否在跑：curl http://127.0.0.1:13456/health
检查应用是否发布上线
检查事件订阅配置（使用长连接模式 + im.message.receive_v1）
检查群聊 @ 设置

Q：海外 Lark 用户怎么配？

把 "domain": "Feishu" 改为 "domain": "Lark"，其他配置不变。

Q：多个人同时和机器人聊天会串会话吗？

不会。sidecar 用 chatId 或 userId 作为会话 key，每个聊天上下文相互独立。

Q：可以限制只响应特定群/用户吗？

可以。把对应的 ID 填入 allowlist 数组，空数组 [] 表示放行所有。

一句话点睛：5 个 FAQ，90% 的"机器人不响应"问题都在"先看日志、再查健康检查、然后看事件订阅"这条线。

附录 D · 故障排查速查表

现象	可能原因	排查方法
sidecar 启动报 `Cannot find package '@larksuite/channel'`	依赖未安装	`cd ~/.atomcode/plugins/marketplaces/atomcode-channel/plugins/feishu/adapter && npm install`
启动报飞书 WebSocket 连接失败	appId/appSecret 错误或网络不通	检查配置、`curl https://open.feishu.cn`
sidecar 启动后终端退出就停了	未使用 `disown` 或 `nohup`	启动时加上 `disown`（见第四步）
飞书里发消息无响应	应用未发布 / 事件订阅未配 / requireMention 未 @	见上方 FAQ
daemon 健康检查超时	daemonBaseUrl 端口不对 / daemon 未启动	`curl http://127.0.0.1:13456/health`
群聊 @ 机器人无响应	机器人未被加入群 / 没有发消息权限	把机器人加入群，检查群权限

一句话点睛：6 类故障、6 行排查命令。3 条高频——"飞书包找不到"、"WebSocket 连不上"、"机器人不响应"。

《AtomCode 飞书助手极简配置教程》课程

欢迎使用 AtomCode 飞书渠道插件。通过本教程，你可以将 AtomCode 的 Agent 能力接入飞书 / Lark。

本教程去除了所有复杂的后台配置，只需完成以下四步即可。

部分	主题
前置要求	AtomCode / Node.js / 飞书应用
核心流程	4 步走通
第一步	安装插件
第二步	创建飞书应用（7 小步）
第三步	写入配置文件
第四步	启动 daemon + sidecar
附录 A	飞书渠道优势
附录 B	控制命令
附录 C	常见问题（FAQ）
附录 D	故障排查速查表

前置要求

AtomCode 版本：请确保你的 AtomCode 版本不低于 4.25.1。
Node.js 版本：飞书渠道依赖 @larksuite/channel SDK，需要 Node.js >= 22。
飞书开放平台应用：需要一个已开通机器人能力的飞书应用（下文会引导你创建）。

一句话点睛：3 个硬门槛——AtomCode 4.25.1+、Node.js 22+、一个飞书应用。少一个跑不起来。

核心流程

【第一步：装插件】 ──→ 【第二步：创建飞书应用】 ──→ 【第三步：写入配置】 ──→ 【第四步：启动】

一句话点睛：4 步流水线，按顺序来，别跳。

第一步：安装插件

打开你的 AtomCode TUI（终端界面）

atomcode

根据atomcode引导进行登陆，然后依次运行以下命令：

# 1. 添加插件市场源
/plugin marketplace add https://atomgit.com/atomgit_atomcode/AtomCode-Channel

# 2. 安装飞书插件
/plugin install feishu@atomcode-channel

# 3. 退出AtomCode 
/quit

# 4. 安装飞书 SDK 依赖
cd ~/.atomcode/plugins/marketplaces/atomcode-channel/plugins/feishu/adapter && npm install

国内用户提示：如果 npm install 因为网络原因卡住，可以临时切换到国内镜像源：
npm install --registry=https://registry.npmmirror.com

一句话点睛：3 行命令搞定一半。npm 卡了换国内镜像，一行的事。

第二步：创建飞书应用

飞书渠道用 appId + appSecret 直连飞书 WebSocket，无需公网回调域名，也无需扫码登录。

2.1 创建应用

打开飞书开放平台 → 点击「创建企业自建应用」（或选择已有应用）。

填写应用名称（例如 AtomCode 助手）和描述，上传一个图标，点击创建。

2.2 开通机器人能力

进入应用详情页 → 左侧菜单 「应用能力」→「机器人」。

点击「开启机器人」，按提示完成配置（默认即可）。

2.3 申请权限

进入左侧菜单 「权限管理」→「API 权限」，搜索并开通以下 IM 相关权限：

以下权限可以在权限管理页面搜索 im: 前缀快速筛选。

权限名	权限标识	说明
获取与发送单聊、群组消息	`im:message`	收发消息（必选）
以应用的身份发消息	`im:message:send_as_bot`	机器人身份发送消息（必选）
读取私聊消息	`im:message.p2p_msg:readonly`	接收用户私聊消息（必选）
接收群聊中@机器人消息事件	`im:message.group_at_msg:readonly`	接收群聊 @ 消息（必选）
获取单聊、群组消息（只读）	`im:message:readonly`	只读方式获取消息
获取单聊、群组的历史消息	`im:message.history:readonly`	获取历史消息
获取群组中所有消息	`im:message.group_msg`	获取群组全部消息
上传/下载图片和文件	`im:resource`	发送图片、文件等附件（必选）
获取与更新群组信息	`im:chat`	创建和管理群组
获取群组信息（只读）	`im:chat:readonly`	只读方式获取群信息
查看群成员	`im:chat.members:read`	获取群成员列表
添加、移除群成员	`im:chat.members:write_only`	管理群成员
订阅机器人进出群事件	`im:chat.members:bot_access`	感知机器人被加入/移出群
读取群信息（历史版本）	`im:chat.group_info:readonly`	兼容旧版群信息读取
读取用户和机器人的会话	`im:chat.access_event.bot_p2p_chat:read`	感知用户首次与机器人对话
获取客户端用户代理信息	`im:user_agent:read`	获取客户端 UA 信息
读取用户信息	`contact:user.base:readonly`	解析 @ 机器人时的用户身份（可选）

修改权限后需要重新发布应用版本才会生效。

一句话点睛：17 条权限，4 条必选、12 条只读、1 条可选。im: 前缀一键筛。

2.4 配置事件订阅（WebSocket 模式）

左侧菜单 「事件与回调」→「事件配置」。

选择 「使用长连接接收事件」 模式（不是「请求地址」模式）。
添加事件：接收消息 v2.0（im.message.receive_v1）。

一句话点睛：注意——选"长连接"，不是"请求地址"。AtomCode 是出站 WebSocket，不要公网域名。

2.5 获取 App ID 和 App Secret

左侧菜单 「凭证与基础信息」，页面上会显示 App ID（格式如 cli_xxxxxxxxxxxx）和 App Secret。

2.6 发布应用

左侧菜单 「版本管理与发布」 → 创建版本 → 提交发布。

企业管理员可直接审核通过；否则需要管理员审批。

2.7 在飞书里找到机器人

打开飞书客户端 → 搜索栏输入你的应用名（例如 AtomCode 助手），私聊发消息即可。

一句话点睛：7 小步——建应用、开机器人、申权限、配事件、拿凭证、发版本、找机器人。发版本前不生效。

第三步：写入配置文件

配置外置在 ~/.atomcode/feishu/config.json，不随插件丢失。

# 1. 创建配置目录
mkdir -p ~/.atomcode/feishu

# 2. 复制示例配置
cp ~/.atomcode/plugins/marketplaces/atomcode-channel/plugins/feishu/config.example.json ~/.atomcode/feishu/config.json

# 3. 编辑配置文件
vim ~/.atomcode/feishu/config.json

填入你在第二步获取的 App ID 和 App Secret：

{
  "appId": "cli_xxxxxxxxxxxx",
  "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "domain": "Feishu",
  "daemonBaseUrl": "http://127.0.0.1:13456",
  "workingDir": "/opt/atomgit",
  "allowlist": [],
  "provider": "",
  "thinkingAck": true,
  "daemonCmd": "atomcode daemon",
  "policy": {
    "requireMention": true,
    "dmMode": "open"
  }
}

# 4. 设置权限
chmod 600 ~/.atomcode/feishu/config.json

配置字段说明

字段	必填	说明
`appId`	✅	飞书开放平台 App ID（格式如 `cli_xxxxxxxxxxxx`）
`appSecret`	✅	飞书开放平台 App Secret
`domain`	选填	`"Feishu"`（国内默认）/ `"Lark"`（海外），默认 `"Feishu"`
`daemonBaseUrl`	选填	atomcode daemon 地址，默认 `http://127.0.0.1:13456`
`workingDir`	选填	默认工作目录（沙箱），建议设为项目根目录
`allowlist`	选填	聊天 ID 白名单，空数组 `[]` = 放行所有
`provider`	选填	指定模型 provider，空字符串 = daemon 默认
`thinkingAck`	选填	turn 开始发「🤔 正在思考…」，默认 `true`
`daemonCmd`	选填	未起 daemon 时自动拉起命令
`policy.requireMention`	选填	群聊中是否要求 @机器人才响应，默认 `true`
`policy.dmMode`	选填	私聊策略：`"open"`（所有私聊响应）/ `"allowlist"`（仅白名单）

一句话点睛：11 个字段，2 个必填、9 个选填。chmod 600 别忘——appSecret 明文存盘。

第四步：启动

配置写好后，手动启动 daemon 和 sidecar（需要开两个终端，或使用 disown 后台运行）：

启动 daemon

atomcode daemon --port 13456 --idle-timeout 0 &
disown

daemon 是 atomcode 的 HTTP 服务端，sidecar 通过它转发消息给 AI 模型。

启动飞书 sidecar

cd ~/.atomcode/plugins/marketplaces/atomcode-channel/plugins/feishu/atomcode
nohup node src/launch.js > /tmp/atomcode-feishu.log 2>&1 &
disown

加了 disown 后，进程不会因终端退出而被杀死，确保长期运行。

验证启动状态

tail -f /tmp/atomcode-feishu.log

正常启动时输出类似：

feishu 桥已启动。bot=AtomCode 助手 daemon=http://127.0.0.1:13456 workingDir=/opt/atomgit

看到这行日志后，打开飞书客户端搜索你的机器人名称（如 AtomCode 助手），即可开始对话。

一句话点睛：2 个进程——daemon 是 AI 大脑，sidecar 是飞书桥。disown 不加就白干。

附录 A · 飞书渠道优势

特性	说明
交互式卡片审批	工具执行审批用按钮点击，无需手动输入 y/n
无需扫码登录	appId + appSecret 直连，无登录步骤
WebSocket 长连接	SDK 内置自动重连 + keepalive 看门狗
消息归一化	SDK 处理文本/图片/文件/表情等，统一格式
安全管道	SDK 内置去重、防重放、策略门
无需公网域名	WebSocket 出站连接，无需回调 URL

一句话点睛：6 大优势——卡片审批 + WebSocket + 无扫码 + 无域名。光这 4 条就比大多数渠道少装 1 小时。

附录 B · 控制命令

命令	说明
`/pwd`	查看当前工作目录
`/cd <path>`	切换工作目录（切换后开新会话）
`/cd`	无参回到默认工作目录

一句话点睛：3 个命令只管目录，不管别的——AtomCode 自己的 /plan /build /goal /bg 全部继承。

附录 C · 常见问题 (FAQ)

Q：每次启动 atomcode 都要重新配置吗？

不需要。配置写在 ~/.atomcode/feishu/config.json，重装插件、重启 atomcode 都不会丢失。

Q：如果飞书机器人没有反应怎么办？

按以下顺序排查：

检查 sidecar 日志：tail -f /tmp/atomcode-feishu.log
检查 daemon 是否在跑：curl http://127.0.0.1:13456/health
检查应用是否发布上线
检查事件订阅配置（使用长连接模式 + im.message.receive_v1）
检查群聊 @ 设置

Q：海外 Lark 用户怎么配？

把 "domain": "Feishu" 改为 "domain": "Lark"，其他配置不变。

Q：多个人同时和机器人聊天会串会话吗？

不会。sidecar 用 chatId 或 userId 作为会话 key，每个聊天上下文相互独立。

Q：可以限制只响应特定群/用户吗？

可以。把对应的 ID 填入 allowlist 数组，空数组 [] 表示放行所有。

一句话点睛：5 个 FAQ，90% 的"机器人不响应"问题都在"先看日志、再查健康检查、然后看事件订阅"这条线。

附录 D · 故障排查速查表

现象	可能原因	排查方法
sidecar 启动报 `Cannot find package '@larksuite/channel'`	依赖未安装	`cd ~/.atomcode/plugins/marketplaces/atomcode-channel/plugins/feishu/adapter && npm install`
启动报飞书 WebSocket 连接失败	appId/appSecret 错误或网络不通	检查配置、`curl https://open.feishu.cn`
sidecar 启动后终端退出就停了	未使用 `disown` 或 `nohup`	启动时加上 `disown`（见第四步）
飞书里发消息无响应	应用未发布 / 事件订阅未配 / requireMention 未 @	见上方 FAQ
daemon 健康检查超时	daemonBaseUrl 端口不对 / daemon 未启动	`curl http://127.0.0.1:13456/health`
群聊 @ 机器人无响应	机器人未被加入群 / 没有发消息权限	把机器人加入群，检查群权限

一句话点睛：6 类故障、6 行排查命令。3 条高频——"飞书包找不到"、"WebSocket 连不上"、"机器人不响应"。

《AtomCode 飞书助手极简配置教程》课程

目录

前置要求

核心流程

第一步：安装插件

第二步：创建飞书应用

2.1 创建应用

2.2 开通机器人能力

2.3 申请权限

2.4 配置事件订阅（WebSocket 模式）

2.5 获取 App ID 和 App Secret

2.6 发布应用

2.7 在飞书里找到机器人

第三步：写入配置文件

配置字段说明

第四步：启动

启动 daemon

启动飞书 sidecar

验证启动状态

附录 A · 飞书渠道优势

附录 B · 控制命令

附录 C · 常见问题 (FAQ)

附录 D · 故障排查速查表

需要登录后查看

《AtomCode 飞书助手极简配置教程》课程

目录

前置要求

核心流程

第一步：安装插件

第二步：创建飞书应用

2.1 创建应用

2.2 开通机器人能力

2.3 申请权限

2.4 配置事件订阅（WebSocket 模式）

2.5 获取 App ID 和 App Secret

2.6 发布应用

2.7 在飞书里找到机器人

第三步：写入配置文件

配置字段说明

第四步：启动

启动 daemon

启动飞书 sidecar

验证启动状态

附录 A · 飞书渠道优势

附录 B · 控制命令

附录 C · 常见问题 (FAQ)

附录 D · 故障排查速查表

需要登录后查看