摘要： 本文使用 Linco Bridge 的官方在线 Demo，完整走一遍“手机端生成连接配置→电脑安装并启动 linco-connect→确认 Codex 在线→发送第一条只读任务”的流程。文末附常见排障方法和安全边界。

关键词： Codex CLI、Linco Bridge、linco-connect、AI Agent、跨设备会话、WebSocket

1. 这篇教程要跑通什么？

Codex 在电脑上跑任务时，人不一定能始终守着终端。比如任务执行到一半，你只想看看进度、补充一句要求，或处理一个权限确认，这时再打开远程桌面并不算轻便。

Linco Bridge 的思路是：Codex 继续在你的电脑上执行，linco-connect 负责把会话、流式输出、权限请求和文件引用桥接到手机、H5 或自定义客户端。

这篇不展开讲协议和二次开发，目标很具体：

使用在线 Demo，从零安装 linco-connect，让手机端看到本机 Codex，并发送第一条只读任务。

2. 开始前的环境检查

先确认两件事：

1. 电脑上的 Codex CLI 已经能正常启动和登录。
2. Node.js 版本在 Linco Bridge 当前支持范围内。

打开电脑终端，执行：

node -v
codex --version

当前的 Node.js 支持范围是 20 或 22–26，推荐使用 Node.js 22 LTS。Node.js 21 不在当前支持范围内，因为连接器依赖原生模块 better-sqlite3。

截至 2026-07-28，项目文档中记录的 Codex CLI 已验证版本为：

codex-cli 0.142.5

这表示项目对该版本做过验证，不代表其他版本必然不能使用。如果正好在排查兼容性问题，请先对齐文档记录的已验证版本。

3. 打开手机端体验入口

有两个公开入口：

• 在线 H5：https://bridge-demo.lincotalk.com
• 微信小程序：搜索 agent桥接器

打开后进入底部的“桥接”页面，选择 从 Codex 导入。

这个页面同时会显示 Claude Code、Hermes 和 OpenClaw，本文只演示 Codex。它们的操作都是一样的，大家可以根据自己平时使用的是哪个选择性的去连接就行，都能做到随时随地的续聊。

4. 生成并复制本机连接配置

进入“连接 Codex”页面后，会看到三条命令：

1. 全局安装 linco-connect；
2. 使用页面生成的 Token、Account 和 WSS 地址初始化 Codex 连接；
3. 在后台启动连接器。

命令的结构大致如下。下面只是脱敏格式，不要直接复制这个示例：

npm install -g linco-connect

linco-connect init \
  --token "<页面生成的-app-id:app-secret>" \
  --agent codex \
  --channel linco-demo \
  --account "<页面生成的-account-id>" \
  --ws-url wss://bridge-demo.lincotalk.com/bridge/ws/codex

linco-connect start --daemon

请点击页面上的“复制”，把页面实际生成的完整命令复制到运行 Codex CLI 的电脑上。

注意：命令中包含动态 App Secret。不要把完整命令发到公开群聊、论坛、Issue 或未脱敏截图中。

如果你在手机上复制命令，请通过自己可信的方式传到目标电脑，不要经过公开聊天或可被他人访问的协作文档。

5. 在电脑上执行三条命令

把页面生成的命令粘贴到电脑终端中执行。

第一条命令安装连接器：

npm install -g linco-connect

第二条命令会将当前 Codex 账号的桥接配置写入本机。默认配置位置在用户目录下的：

.linco/config.json

普通用户不需要手动修改这个文件。

第三条命令在后台启动连接器：

linco-connect start --daemon

如果想先在前台看启动输出，也可以使用：

linco-connect start

前台模式便于第一次排查问题；确认没问题后，再使用 --daemon 转到后台。

6. 检查连接器是否正常

执行：

linco-connect status
linco-connect doctor

status 用于查看连接器当前运行状态，doctor 用于检查本机环境和 CLI 状态。

然后回到手机或 H5 页面。完成本机配置并连接成功后，Codex 会自动出现在 Agent 列表中。

建议在这一步确认三个结果：

• 桥接状态显示在线；
• 能够进入 Codex 的项目或会话列表；
• 发送消息后能收到流式回复。

7. 发送第一条跨端任务

第一次连接，建议不要马上让 Codex 改代码。先发送一条只读任务，确认项目、会话和流式输出都正常：，

请只读取当前项目，告诉我它的主要技术栈、启动入口和顶层目录作用。
这一轮不要修改文件，也不要安装依赖。

这条任务足够验证：

• 手机端消息能否送达电脑上的 Codex；
• Codex 能否正确读取当前项目；
• 回复能否流式返回手机端；
• 当前项目与会话路由是否正确。

如果手机端开始持续显示 Codex 输出，并最终返回项目概览，第一个跨端会话就跑通了。

8. 五个常见问题

8.1 终端提示 linco-connect: command not found

先确认全局安装命令执行成功：

npm install -g linco-connect

如果安装成功但命令仍找不到，检查 npm 全局可执行目录是否已加入当前 Shell 的 PATH。

8.2 升级 Node.js 后出现 better-sqlite3 或 NODE_MODULE_VERSION 报错

优先切换到 Node.js 22 LTS，然后重新安装 linco-connect。如果是在源码目录中运行，也可以在对应安装目录重新执行 npm install，或重建 better-sqlite3。

8.3 连接器在运行，页面仍显示离线

按这个顺序检查：

1. 执行 linco-connect status 和 linco-connect doctor；
2. 回到当前桥接页，重新复制最新的 setupCommands；
3. 确认 --agent codex、--channel linco-demo 和 --account 没有被手动改动；
4. 检查本机防火墙、代理或公司网络是否拦截了页面生成的 WSS 连接。

访客凭证可能变化，不要长期复用以前截图或文档中的旧命令。

8.4 会话列表为空

先确认电脑上的 Codex 已经有本地项目或会话记录。还需要确认当前 Codex 版本处于连接器适配范围内，且会话索引刷新没有失败。

8.5 提示凭证已占用

每套凭证通常只绑定一个桥接实例。可以停止原来的桥接，或者在页面中点击“新增连接”，生成新的 Account 和 Token。

9. 停止或重载连接器

停止后台服务：

linco-connect stop

修改账号配置后手动重载：

linco-connect reload

重新启动：

linco-connect start --daemon

10. 不要忽略在线 Demo 的边界

在线 Demo 使用签名匿名访客 Session，用来快速验证桥接流程。它不提供正式账号、持久跨设备恢复或生产级多租户保证。

因此：

• 不要输入敏感数据或正式业务数据；
• 不要分享 Token、App Secret 和带凭证的 URL；
• 公网链路使用 TLS/WSS 不等于系统已实现端到端加密；
• 需要接入真实数据时，应评估并部署自己的参考平台或自定义通道。

11. 开发者扩展：本地部署参考平台

如果已经跑通在线 Demo，下一步想看源码或自己联调，可以在两个终端分别启动服务端和 H5。

终端一：

cd linco-bridge-platform/server
npm install
npm run start:dev

终端二：

cd linco-bridge-platform/web
npm install
npm run dev:h5

打开 H5 页面，再次进入“桥接→从 Codex 导入”，以页面生成的 setupCommands 为准。

本地 linco-demo 默认通常使用：

ws://127.0.0.1:3300/bridge/ws/codex

这个地址只适合可信的本地开发环境，因此本地生成的初始化命令中可能包含 --allow-insecure-ws。公网部署不应使用这个参数。

12. 项目入口

• GitHub：https://github.com/lincotalk/linco-bridge
• 在线 Demo：https://bridge-demo.lincotalk.com
• 小程序：搜索 agent桥接器
• 快速开始：https://github.com/lincotalk/linco-bridge/blob/main/docs/zh-CN/quick-start.md
• 排障文档：https://github.com/lincotalk/linco-bridge/blob/main/docs/zh-CN/troubleshooting.md
• 安全与隐私：https://github.com/lincotalk/linco-bridge/blob/main/docs/zh-CN/security-and-privacy.md

《Linco Bridge 开源：在手机端续接 Codex、Claude Code 、Hermes等本地 AI Agent（架构与实践）》