<figure><img src="/uploads/covers/opencode-im-bridge-c9a38de3.jpg" alt="Connecting OpenCode to Telegram and Feishu" loading="eager"><figcaption>OpenCode remote control setup | aposhuang.com</figcaption></figure><p>用 AI 写代码最烦的一件事不是模型不够聪明,而是<strong>你不在电脑前</strong>。</p>
<p>想法冒出来的时候人在电车上看手机,或者在咖啡馆排队。等你回到桌前,那个"要不要让 AI 帮我改一下这段"的念头已经凉了。于是很多人干脆把 OpenCode 扔在服务器上常驻,然后想办法用手机给它发指令——Telegram 和飞书就是最顺手的两条路。</p>
<p>这篇文章把两条路都走一遍。两条都在一台 Linux 机器上实测过:Telegram 大约 15 分钟能通,飞书大约 30 分钟,难点不在机器上,而在飞书开发者后台那几个必须"发布版本"才生效的开关。</p>
<h2>先看整体结构</h2>
<p>理解这张图,后面每一步都不会走丢:</p>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang=""><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0">手机 (Telegram / 飞书)
│ 聊天消息
▼
云端 (Telegram Bot API / 飞书开放平台)
│ 长连接 / 轮询 / 推送
▼
你的机器 ── 机器人进程 (opencode-telegram / opencode-feishu)
│ 本地 HTTP
▼
opencode serve (127.0.0.1:4096)
│
▼
模型 API (OpenCode Zen / Go / 自建)</code></pre>
<p>关键点:<strong>手机永远不直接连你的机器</strong>。是机器主动往外连云端,再把消息转成本地会话。所以你不需要公网 IP、不需要端口映射、不需要 DDNS——这条设计对家庭宽带和笔记本挂机特别友好。</p>
<p>反过来也意味着:机器必须一直醒着、一直有网。笔记本合盖就挂起的默认设置,会让整套东西在你出门第二小时静默失联。</p>
<h2>前置条件</h2>
<ul><li>一台常开的 Linux(或 macOS)机器,能访问外网</li><li>已安装 OpenCode CLI,且 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">opencode run "你好"</code> 能正常回答</li><li>systemd 用户级服务可用(<code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">systemctl --user</code>);macOS 换成 launchd 或 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">tmux</code> 常驻</li><li>你自己的时间:Telegram 15 分钟,飞书 30 分钟</li></ul>
<p>如果 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">opencode run</code> 本身还没通,先别接 IM——两个变量叠在一起排障会非常痛苦。</p>
<h2>路线一:Telegram(15 分钟)</h2>
<h3>1. 找 @BotFather 要一个 token</h3>
<p>在 Telegram 搜 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">@BotFather</code> → <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">/newbot</code> → 起名字 → 拿到形如 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</code> 的 token。</p>
<p>这一步之后,你的机器人已经存在了,但还没有大脑。大脑由下面的进程提供。</p>
<h3>2. 安装机器人进程</h3>
<p>OpenCode 生态里有现成的 Telegram 桥接程序 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">opencode-telegram</code>,它干的事就是:把 Telegram 消息转成 opencode 会话,再把回答发回去。</p>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="bash"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0"># 安装(npm 全局或项目内均可,注意放进入 PATH)
npm install -g opencode-telegram
# 验证可执行
which opencode-telegram</code></pre>
<h3>3. 写配置</h3>
<p>配置文件放在 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">~/.config/opencode-telegram-bot/.env</code>,权限设成 600:</p>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="bash"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0">mkdir -p ~/.config/opencode-telegram-bot
chmod 700 ~/.config/opencode-telegram-bot
cat > ~/.config/opencode-telegram-bot/.env <<'EOF'
TELEGRAM_BOT_TOKEN=1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_ALLOWED_USER_ID=你的Telegram数字ID
BOT_LOCALE=zh
OPENCODE_MODEL_PROVIDER=opencode
OPENCODE_MODEL_ID=deepseek-v4.1-flash
OPENCODE_API_URL=http://127.0.0.1:4096
OPENCODE_SERVER_PASSWORD=一个随机串
EOF
chmod 600 ~/.config/opencode-telegram-bot/.env</code></pre>
<p>两个容易忽略的字段:</p>
<ul><li><strong><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">TELEGRAM_ALLOWED_USER_ID</code></strong>:这是白名单。不填等于把机器人开放给全世界的陌生人,而机器人后面连着你的机器。数字 ID 可以找 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">@userinfobot</code> 拿。</li><li><strong><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">OPENCODE_MODEL_PROVIDER</code> / <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">OPENCODE_MODEL_ID</code></strong>:一定要写全"提供商/模型"两段。只写模型名时,某些版本会静默回落到默认的免费模型,你以为在用付费的强模型,实际用的是最弱的一档。</li></ul>
<h3>4. 让 opencode 常驻</h3>
<p>机器人进程需要一个活着的 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">opencode serve</code> 来转发请求:</p>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="bash"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0">opencode serve --hostname 127.0.0.1 --port 4096</code></pre>
<p>前台跑没问题,但你要的是常驻,所以写成 systemd 用户服务(<code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">~/.config/systemd/user/opencode-serve.service</code>):</p>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="ini"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0">[Unit]
Description=OpenCode headless server
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
WorkingDirectory=%h
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=%h/.local/bin/opencode serve --hostname 127.0.0.1 --port 4096
Restart=always
RestartSec=10
[Install]
WantedBy=default.target</code></pre>
<p>没有 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">WorkingDirectory=%h</code> 的时候,服务启动在 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">/</code> 下,opencode 找不到项目配置,表现是"连上了但一问就报错"。</p>
<h3>5. 启用并验证</h3>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="bash"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0">systemctl --user daemon-reload
systemctl --user enable --now opencode-serve.service
systemctl --user enable --now opencode-telegram-bot.service
systemctl --user status opencode-serve.service
systemctl --user status opencode-telegram-bot.service</code></pre>
<p>然后在 Telegram 里给机器人发一句"你在哪个目录"。它应该回你一个路径——那就说明整条链路通了。</p>
<h2>路线二:飞书(30 分钟)</h2>
<p>飞书多出来的 15 分钟全花在后台。这个平台把"能力"拆成了权限、事件订阅、版本发布三件互相独立的事,缺一件就表现为"消息发出去了,机器人像死了一样"。</p>
<h3>1. 建一个自建应用</h3>
<p>电脑端打开 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">open.feishu.cn</code> → 开发者后台 → 创建企业自建应用。名字随你,比如 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">my-coder</code>。</p>
<p>注意:<strong>自建应用只能在电脑端建</strong>,手机端没有入口。</p>
<p>建完在「应用功能 → 机器人」里确认机器人已启用。</p>
<h3>2. 加三条权限</h3>
<p>在「权限管理」里搜并开通:</p>
<table style="width:100%;border-collapse:collapse;font-size:14px;margin:16px 0"><thead><tr><th style="border:1px solid #d5dbe3;padding:8px 10px;background:#f4f6f9;text-align:left;font-weight:700">权限</th><th style="border:1px solid #d5dbe3;padding:8px 10px;background:#f4f6f9;text-align:left;font-weight:700">作用</th><th style="border:1px solid #d5dbe3;padding:8px 10px;background:#f4f6f9;text-align:left;font-weight:700">少了会怎样</th></tr></thead><tbody><tr><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">im:message:send_as_bot</code></td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">机器人能发消息</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">收得到,回不出</td></tr><tr><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">im:message.p2p_msg:readonly</code></td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">能读用户发给机器人的单聊</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">收不到你的消息</td></tr><tr><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">cardkit:card:write</code>(可选)</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">流式卡片渲染</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">退化成纯文本,功能不受影响</td></tr></tbody></table>
<h3>3. 事件订阅:长连接 + 接收消息</h3>
<p>「事件与回调 → 事件配置」:</p>
<ol><li>订阅方式选 <strong>使用长连接接收事件</strong>(不要填回调地址,除非你有公网 HTTPS)</li><li>添加事件 <strong>接收消息 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">im.message.receive_v1</code></strong></li></ol>
<p>长连接的意思是:你的机器主动连飞书,消息顺着这条连接推下来。同样的好处是不需要公网 IP。</p>
<h3>4. 发布版本——最容易漏的一步</h3>
<p>「版本管理与发布」→ 创建版本 → 填版本号 → 申请发布 → 等状态真正变成 <strong>已发布</strong>。</p>
<p><strong>在飞书上,权限和事件的改动不发布新版本就不生效。</strong> 后台页面看着已经勾上了,实际对外还是旧版本。我们第一次配置时就卡在这里:机器人能发消息(说明发送权限早就在某个已发布版本里),但一条入站事件都收不到,因为接收权限和事件订阅都还躺在"待发布"的草稿里。</p>
<h3>5. 装插件、填凭证</h3>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="bash"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0"># 插件放进 opencode 的配置目录
cd ~/.config/opencode
npm install opencode-feishu</code></pre>
<p>在 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">~/.config/opencode/opencode.jsonc</code> 里挂上:</p>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="json"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0">{
"$schema": "https://opencode.ai/config.json",
"model": "opencode-go/deepseek-v4.1-flash",
"plugin": ["opencode-feishu"]
}</code></pre>
<p>凭证单独存一个文件,别写进主配置(主配置容易进仓库):</p>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="bash"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0">cat > ~/.config/opencode/feishu.env <<'EOF'
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
EOF
chmod 600 ~/.config/opencode/feishu.env</code></pre>
<p>插件的配置 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">~/.config/opencode/plugins/feishu.json</code> 用环境变量占位,这样密钥只存在一个地方:</p>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="json"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0">{
"appId": "${FEISHU_APP_ID}",
"appSecret": "${FEISHU_APP_SECRET}",
"logLevel": "info",
"directory": "/home/you"
}</code></pre>
<h3>6. 常驻</h3>
<p>飞书插件是挂在 opencode 实例上的,需要一个不间断的进程把它带起来:</p>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="ini"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0"># ~/.config/systemd/user/opencode-feishu-gw.service
[Unit]
Description=OpenCode Feishu gateway
After=network-online.target opencode-serve.service
Wants=network-online.target
[Service]
Type=simple
WorkingDirectory=%h/.opencode-feishu
EnvironmentFile=-%h/.config/opencode/feishu.env
ExecStart=/usr/bin/script -qec "%h/.local/bin/opencode --print-logs" /dev/null
Restart=always
RestartSec=5
[Install]
WantedBy=default.target</code></pre>
<p><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">script -qec</code> 这层包装是为了让 opencode 以为自己连着终端,否则它会把自己当成一次性命令跑完就退出。<code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">EnvironmentFile</code> 那一行必须写,否则插件拿到的 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">${FEISHU_APP_ID}</code> 是空字符串。</p>
<pre style="background:#0f172a;color:#e6edf3;padding:16px 18px;border-radius:10px;overflow-x:auto;font-size:13.5px;line-height:1.6;margin:14px 0;white-space:pre;tab-size:2;max-width:100%;box-sizing:border-box" data-lang="bash"><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:13.5px;color:inherit;background:none;padding:0">systemctl --user daemon-reload
systemctl --user enable --now opencode-feishu-gw.service</code></pre>
<p>然后在飞书里搜你的应用名,进单聊发一句"你好"。</p>
<h2>两条路怎么选</h2>
<table style="width:100%;border-collapse:collapse;font-size:14px;margin:16px 0"><thead><tr><th style="border:1px solid #d5dbe3;padding:8px 10px;background:#f4f6f9;text-align:left;font-weight:700"></th><th style="border:1px solid #d5dbe3;padding:8px 10px;background:#f4f6f9;text-align:left;font-weight:700">Telegram</th><th style="border:1px solid #d5dbe3;padding:8px 10px;background:#f4f6f9;text-align:left;font-weight:700">飞书</th></tr></thead><tbody><tr><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">配置时间</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">~15 分钟</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">~30 分钟</td></tr><tr><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">需要什么</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">一个 token</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">企业自建应用 + 后台三项配置</td></tr><tr><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">长连接</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">内置轮询/长轮询</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">WebSocket 长连接</td></tr><tr><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">群聊 @ 机器人</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">支持</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">支持(需额外群聊权限)</td></tr><tr><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">手机上能不能用</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">能</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">能(国内直连,无需任何工具)</td></tr><tr><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">主要坑</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">白名单、模型名写一半</td><td style="border:1px solid #d5dbe3;padding:8px 10px;vertical-align:top">改完不发布版本</td></tr></tbody></table>
<p>如果你人在国内,飞书是更稳的那条路——它不需要任何网络工具就能直连。Telegram 的客户端在国内需要额外手段,但服务端在这一侧完全不受影响。</p>
<h2>排障:症状 → 原因 → 动作</h2>
<p><strong>机器人完全不回,进程是 active</strong></p>
<p>先看日志里有没有 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">ws client ready</code>(飞书)或成功拉取 update(Telegram)。连上了却零入站事件,问题几乎一定在平台后台,不在你的机器上。</p>
<p><strong>飞书:连上了,但日志里没有一条消息进来</strong></p>
<p>按这个顺序查:事件订阅有没有 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">im.message.receive_v1</code>;订阅方式是不是长连接;<strong>版本是不是已发布</strong>。90% 的"没反应"死在这三条上。</p>
<p><strong>飞书:收得到,但回不出</strong></p>
<p>缺 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">im:message:send_as_bot</code>。如果后台明明加了还是不生效,还是那句话——发布新版本。</p>
<p><strong>日志里有一行 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">receive events or callbacks through persistent connection only available in self-build & Feishu app...</code></strong></p>
<p>这不是报错。飞书的 SDK 每次连接都会打印这段说明文字,后面紧跟 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">ws connect success</code> 就是正常的。别被它带着去改网络。</p>
<p><strong>回答以纯文本出现,没有打字机效果</strong></p>
<p>缺 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">cardkit:card:write</code>。加上并发布版本即可,或者就这么用,功能都在。</p>
<p><strong>重启服务后还是老行为</strong></p>
<p>飞书插件的配置在进程启动时读取。改完 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">feishu.json</code> 或 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">feishu.env</code> 必须 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">systemctl --user restart</code>,热更新不生效。</p>
<h2>安全清单</h2>
<p>把 AI 编码员接进聊天软件,等于给它开了一个远程入口。三件事别省:</p>
<ol><li><strong>token 和白名单</strong>。Telegram 的 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">TELEGRAM_ALLOWED_USER_ID</code> 一定要填;飞书的应用只在你的企业内可见,但仍建议只在小范围单聊里用。凭证文件 <code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:.9em;background:#eef1f5;color:#b02a37;padding:2px 5px;border-radius:4px">chmod 600</code>,不要进任何仓库。</li><li><strong>不要在公开群聊里挂这个机器人</strong>。群里任何人都能触发它执行命令,等于把 shell 交给了一个陌生人。</li><li><strong>权限最小化</strong>。飞书那三条权限就够了,不要为了"图省事"开一整套通讯录、文档、云盘权限——机器人被攻破时,能拿到的就是你给过的东西。</li></ol>
<h2>最后</h2>
<p>两条链路搭好之后,日常会变成这样:通勤路上在手机里丢一句话「把那个脚本的日志加上时间戳」,回到桌前,改动已经躺在分支里等你 review。</p>
<p>工具的价值不在于它多强,而在于它出现在你想用它的那一刻。</p>