CN-Codex 使用指南

概述

CN-Codex 是一款基于 Tauri 2 + React 构建的桌面 AI 编程助手。它内置 Agent 引擎，直接通过 HTTP SSE 与 LLM API 通信，无需依赖外部 CLI 进程。

项目初衷：让普通开发者长期用上“廉价又好用”的 AI 编程 IDE。作者日常用商汤 free coding plan 的 DeepSeek v4 Flash 做全流程开发，并用中转渠道的 Grok 4.5 攻坚复杂任务、持续进化 IDE。因此产品原生支持多模型渠道与中转站。

核心能力：

• 支持 12+ 种 LLM 供应商与自定义中转站（OpenAI、Anthropic、Google、DeepSeek、Grok 中转、火山引擎、通义千问、智谱、Moonshot、硅基流动、百川、Ollama、LM Studio 等）
• 50+ 内置工具（文件、Shell、浏览器、子代理、记忆、MCP、图像、网页搜索等）
• 项目级工作区管理，每个项目拥有独立的对话上下文
• Goal 目标模式，AI 自主多步执行任务
• 可扩展的插件、技能、Hooks 和机器人系统
• 手机远程控制：扫码连接手机，实时监控、远程审批、发送消息，支持局域网直连和公网中转
• SmartBrain 经验知识库：基于 LLM Wiki 模式，AI 自动提取经验、编译知识、BM25 搜索
• 用户规则和项目规则：Markdown 格式，自动注入系统提示词，AI 可在对话中读写
• 子代理引擎：复杂任务自动拆分并行执行
• 操作录制与回放：通过 CDP 协议录制浏览器操作，生成可回放工作流
• 智能网页搜索：DuckDuckGo + Bing 双引擎，内置防循环策略
• 本地资源池：多端点管理、活跃端点检测、智能故障转移（适合多中转容灾）
• 50+ 内置技能，8 大插件

首次启动

1. 启动应用

双击 CN-Codex.exe 启动。首次启动会在同目录创建 codey 运行时文件夹。

主界面：左侧项目列表，中间聊天/目标切换，右侧文件树面板，底部模型选择和自动审批开关

2. 观察状态指示灯

左上角 CN-Codex 标题旁有一个小圆点：

• 绿色 — 引擎就绪，可以发送消息
• 黄色闪烁 — 正在初始化
• 红色 — 初始化失败（此时会出现「重试」按钮）

3. 配置第一个供应商

点击侧边栏底部的 设置 按钮 → 进入 模型提供商 标签页 → 点击 添加供应商，从预设列表中选择一个（如 DeepSeek、OpenAI 等），填写 API Key 和 Base URL，保存后点击 启用。

供应商设置面板：左侧供应商列表，右侧配置表单（名称、API Key、Base URL、传输协议），底部模型列表

4. 添加第一个项目

在侧边栏头部点击 文件夹+ 按钮（添加项目），选择你要操作的代码目录。添加后 AI 在该目录下执行 Shell 命令和文件读写。

5. 运行时目录结构

codey/
├── config.toml       # 主配置文件
├── sessions/         # 会话持久化（每个对话一个 .jsonl）
├── skills/           # 技能指令文件（SKILL.md）
├── plugins/          # 插件目录
├── robots/           # 机器人配置
├── memories/         # AI 记忆存储
└── usage.db          # Token 用量统计（SQLite）

界面布局

CN-Codex 主界面分为四个区域：

• 标题栏（最顶部） — 拖拽移动窗口、二维码、右侧面板开关、窗口控制（最小化 / 最大化 / 关闭）
• 侧边栏（左侧 256px） — 项目列表、通用对话、会话管理、搜索、设置入口
• 聊天区域（中间主体） — 消息列表 + 底部输入栏
• 右侧面板（可选） — 三个标签页：Browser（内嵌浏览器）、Project（文件树）、Terminal（终端）

「项目」与「对话」的区别

这是 CN-Codex 最重要的组织概念。

项目

项目 = 一个本地文件夹。通过侧边栏添加后，CN-Codex 以该目录为工作根路径。每个项目下可以创建多个对话。

项目对话界面：「项目」标签页选中，聊天/目标模式切换，机器人选择器下拉菜单（无机器人、已创建的机器人、新建机器人）

• 支持 目标模式（Goal）和 聊天模式（Chat）切换
• 支持 机器人（Robot）选择
• 右侧面板可浏览该项目的 文件树
• AI 执行 Shell 命令时，工作目录为该项目文件夹
• 移除项目会同时清除该项目下的所有对话

通用对话

不绑定任何项目的独立对话区域，适合泛聊、翻译、写作等不涉及代码工程的场景。

• 只有 聊天模式，不支持目标模式
• 不支持机器人选择
• 右侧文件树不适用
• 工作目录为应用根目录或用户 Home 目录

聊天模式

默认的对话模式。你发一条消息，AI 回复一条消息，必要时会自动调用工具（读文件、执行命令等）。每次操作需要你手动审批（除非开启了自动审批）。

通用对话聊天模式：仅「聊天」标签，底部状态栏显示连接状态、模型选择器、自动审批开关

在项目对话的输入栏左上方可以看到 聊天 / 目标 切换按钮，点击 聊天 即为此模式。通用对话下只有聊天模式，没有切换按钮。

目标模式（Goal）

仅在项目对话中可用。设置一个目标后，AI 自主多步执行，不需要你一轮一轮地手动发送消息。

启用方式

• 在输入栏切换到 目标 标签，然后输入目标内容发送
• 或直接输入 /goal set 你的目标描述

目标状态

输入栏右侧的徽章显示当前目标状态：

Goal 命令

Token 预算

可以限制目标执行时的最大 Token 消耗：

/goal set --tokens=50k 重构这个模块的错误处理逻辑

支持 k（千）和 m（百万）后缀。

机器人（Robot）

机器人是由 AI 自动创建的专业角色，每个机器人有自己的名称、描述、技能和工作流配置。选中机器人后发送的消息会自动以目标模式运行。

使用方法

1. 在项目对话的输入栏上方点击 机器人下拉菜单（显示「无机器人」）
2. 选择已有机器人，或点击 + 新建机器人
3. 新建时在输入框中描述你想要的机器人功能，AI 会自动创建
4. 选中机器人后，后续发送的消息都将由该机器人角色处理

修改机器人

选中一个机器人后，输入 /modify，然后在输入框中描述要修改的内容即可。

管理机器人

设置面板 → 机器人 标签页可以查看所有机器人的详情（技能、工作流步骤），也可以删除不需要的机器人。

标题栏

最顶部的窄条，从左到右依次是：

侧边栏

左侧固定宽度 256px，包含以下区域（从上到下）：

头部按钮

搜索栏

输入关键词可以按对话标题和内容预览过滤所有对话。

通用对话分组

• 点击 通用对话 标题可展开/折叠
• 标题右侧数字显示对话数量
• 悬停标题时出现 + 按钮可快速新建通用对话
• 无对话时显示 「点击此处开始通用对话」 引导文字

项目分组

• 每个项目显示 文件夹图标 + 项目名称 + 对话数量
• 点击项目名称会 选中该项目 + 展开对话列表
• 悬停时右侧出现 删除按钮（删除前需确认，会清除关联对话）
• 右键菜单：在资源管理器中打开 / 新建对话 / 移除项目
• 无项目时显示虚线框「暂无项目 —— 点击此处添加一个项目文件夹」

对话条目

• 显示 对话标题（取第一条消息的前 60 个字符）和 时间
• 点击加载该对话
• 悬停时隐藏时间、显示 删除按钮
• 右键菜单：删除对话

底部设置按钮

点击打开全屏设置面板。

聊天区域

空状态

没有消息时显示欢迎信息，包括：

• 应用标题和描述
• 当前使用的 模型名称 卡片
• 配置来源（codey/config.toml 路径）卡片

如果没有选中任何项目，整个区域显示「点击此处添加一个项目开始对话」引导。

消息列表

• 用户消息和 AI 消息交替显示，支持 Markdown / GFM 渲染 和 代码高亮
• AI 回复时有 流式输出光标，实时显示生成内容
• 工具调用显示为 可展开的卡片（命令名、参数、输出内容）
• 一轮对话结束后显示 运行摘要卡片（耗时、Token 用量、修改的文件列表，可点击在资源管理器中打开）

复制全部按钮

消息列表顶部右侧的复制按钮可以将整个对话内容复制到剪贴板。

输入栏

位于聊天区域底部，是最核心的交互区域。

模式切换（仅项目对话）

左上方有一个 聊天 / 目标 胶囊切换器：

• 聊天 — 普通一问一答模式
• 目标 — 设置目标后 AI 自主多步执行

通用对话下固定显示「聊天」标签，无法切换。

机器人选择器（仅项目对话）

模式切换器右侧的下拉按钮，可选择：

• 无机器人 — 默认状态
• 已创建的机器人列表（显示名称和描述）
• + 新建机器人 — 在输入框中描述后发送即可创建

Goal 状态徽章

目标模式下且未选择机器人时，右侧会显示当前目标的状态徽章（进行中 / 已暂停 / 预算受限 等）。

附件预览区

已添加的附件显示在输入框上方，每个附件卡片显示文件名、大小，图片附件有缩略图。悬停时出现删除按钮。

主输入框

左侧按钮 — 附件

回形针按钮，点击打开文件选择器。支持图片（image/*）和文档（.pdf, .md, .txt, .docx, .doc, .csv, .json, .yaml, .yml, .toml, .xml, .html）。也支持从右侧文件树 拖拽文件 到输入框。

右侧按钮 — 发送 / 停止

• 绿色圆形箭头 — 发送消息（输入为空或禁用时变灰）
• 红色圆形方块 — 流式输出中或目标运行中时显示，点击可中断

底部状态栏

输入框下方的小字区域，从左到右：

右侧面板

通过标题栏的侧边面板按钮切换显示/隐藏。面板顶部有三个标签页可切换：

Browser（浏览器）

内嵌 WebView 浏览器，由 AI 的 browser_run 工具控制。当 AI 需要访问网页（如打开 URL、点击元素、截图等）时，页面会在此面板中实时渲染。顶部显示当前 URL 和状态信息。

Project（文件树）

• 展示当前项目目录的文件结构
• 顶部有 刷新 和 在资源管理器中打开 两个按钮
• 点击目录展开/折叠
• 点击文件可 预览（Markdown 渲染 / 代码高亮）
• 右键菜单：加入对话（作为附件）/ 在资源管理器中打开
• 可以 拖拽文件到输入框，自动读取内容作为附件

Terminal（终端）

内置真实的交互式终端面板，基于 xterm.js 实现。可以直接在 CN-Codex 内操作系统命令行，无需切换到外部终端窗口。

主要功能

• 多标签页 — 支持同时打开多个终端会话，每个标签页独立运行一个 Shell 进程
• 自动定位 — 如果当前选中了项目，新建终端的工作目录自动设为该项目文件夹
• 系统原生 Shell — Windows 下为 PowerShell / CMD，Linux / macOS 下为默认 Shell
• 实时输出 — 通过 PTY（伪终端）技术，支持完整的终端交互，包括颜色高亮、光标移动、快捷键等
• 自适应大小 — 面板大小变化时自动调整终端行列数

操作说明

审批弹窗

当 AI 需要执行敏感操作（执行命令、修改文件、请求权限等）或向你提问时，会弹出审批弹窗。

审批类型

• 命令执行审批 — 显示要执行的命令内容
• 文件修改审批 — 显示要修改的文件和补丁内容
• 权限请求 — 请求额外操作权限
• 用户输入 — AI 向你提问，可能有多选/文本输入选项

操作

• 批准 — 允许 AI 执行该操作
• 拒绝 — 拒绝该操作

多条审批请求会排队，依次处理。

SmartBrain — AI 经验知识库

SmartBrain 是 CN-Codex 内置的知识管理系统，基于 LLM Wiki 模式（由 Andrej Karpathy 提出）。核心理念：让 AI 提前将原始资料"编译"为结构化知识，而非查询时临时检索。

三层架构

经验系统

• 自动提取 — 每次对话结束后，AI 自动从会话中提取关键经验、失败教训和最佳实践
• 合并摘要 — 多次经验自动合并为精炼摘要，注入后续新会话的系统提示
• 越用越聪明 — AI 不再反复犯同样的错误，历史经验持续积累

知识库

• 上传文档自动分块、组织到 codey/memories/knowledge/
• 支持格式：PDF、Word、PPT、Excel、Markdown、文本等
• 内置 BM25 全文检索引擎，跨经验和知识库统一搜索，无需外部向量数据库

AI 记忆工具

AI 在对话中可通过以下工具主动管理知识：

用户规则 / 项目规则

通过 Markdown 格式的规则文件精准控制 AI 行为，规则会自动注入系统提示词。

用户规则（全局）

• 存储位置：codey/user-rules.md
• 设置方式：设置 → 规则 标签页，直接在文本编辑器中编写
• 作用范围：所有会话中生效
• 示例：偏好语言、代码风格、常用框架等

项目规则（每项目独立）

• 存储位置：项目根目录下的 .rule.md 文件
• 设置方式：右侧文件树 → 右键项目文件夹 → 编辑项目规则
• 作用范围：仅在该项目的对话中生效
• AI 工具：AI 可通过 edit_project_rules 工具在对话中直接读写项目规则

子代理引擎

当 AI 面对复杂任务时，可以将其拆分为多个独立子代理并行执行。每个子代理有自己的系统提示、模型配置和工作目录。

工作流程

1. AI 通过 spawn_agent 工具启动子代理，指定任务描述和工作目录
2. 子代理独立执行，拥有完整的工具调用能力
3. 主代理通过 wait_agent 等待结果，或用 send_input 发送补充指令
4. 子代理完成后，结果汇总到主对话流继续推进

子代理工具

特性

• 并行执行 — 多个子代理可同时运行
• 超时控制 — 可配置子代理超时时间
• Hook 集成 — on-subagent-stop 事件钩子在子代理完成时触发

操作录制与回放

CN-Codex 支持通过外部浏览器的 CDP（Chrome DevTools Protocol）协议录制用户操作，并生成可回放的工作流。

工作原理

1. CN-Codex 自动检测本地安装的 Chrome（优先）或 Edge 浏览器
2. 以远程调试模式启动浏览器（--remote-debugging-port）
3. 通过 CDP WebSocket 连接建立双向通信
4. 注入录制脚本，使用 Runtime.addBinding 实时推送事件到 Rust 后端

使用方法

1. 在聊天界面顶部找到 录制按钮（红色圆点图标）
2. 点击 开始录制，系统会自动启动外部浏览器
3. 在浏览器中正常操作（点击、输入、导航等），所有操作会被实时捕获
4. 完成后点击 停止录制，系统显示录制的操作数量
5. 录制结果自动保存为工作流 JSON 文件，可在后续对话中引用和回放

录制的事件类型

智能网页搜索

CN-Codex 内置网页搜索引擎，AI 可自主搜索互联网获取实时信息。搜索策略参照 OpenAI Codex 的设计，内置防循环机制。

搜索引擎架构

采用多层降级策略，确保搜索成功率：

1. DuckDuckGo Instant Answer API — 首选，无需浏览器，直接 HTTP 请求
2. Bing 浏览器搜索（cn.bing.com）— API 失败时的第一备选，通过内嵌 WebView 抓取搜索结果
3. DuckDuckGo 浏览器搜索 — 第二备选

防循环策略

系统提示词中内置以下规则防止 AI 无限搜索：

• 每次搜索后 立即分析结果，如果摘要已包含答案，直接回复
• 同一问题 最多搜索 3 次（使用不同关键词），3 次后总结已有信息回复
• 不重复访问返回错误或空内容的 URL
• 中文问题自动使用中文关键词搜索

搜索工具

本地资源池

本地资源池允许为同一供应商配置多个 API 端点，系统自动选择活跃端点，实现智能故障转移。

使用场景

• 同一供应商有多个 API 密钥或端点需要轮换
• 部分端点不稳定（频繁 502、超时），需要自动切换到可用端点
• 需要在不同端点之间做负载均衡

配置方式

在设置面板 → 模型提供商 中，选择供应商类型为 本地资源池（local-pool）：

• 添加多个端点，每个端点包含 Base URL 和 API Key
• 为每个端点标记 活跃 或 非活跃 状态
• 系统自动使用当前标记为活跃的端点进行 API 调用

端点选择逻辑

1. 检查供应商是否为 local-pool 类型
2. 从该供应商的端点列表中筛选当前 活跃端点
3. 使用活跃端点的 Base URL 和 API Key 发起请求
4. 如果请求失败，可在设置中手动切换到其他端点

配置文件

主配置文件位于 codey/config.toml，包含以下核心字段：

# 当前模型 ID
model = "l-deepseek-v4-flash"

# 供应商标识（对应 [model_providers.xxx] 中的 key）
model_provider = "openai"

# 推理强度：low / medium / high / xhigh
model_reasoning_effort = "medium"

# 单次最大输出 token 数
max_output_tokens = 65535

# 审批策略：on-request / on-failure / untrusted / never
approval_policy = "on-request"

# 联网搜索：live / cached / disabled
web_search = "live"

# 额外系统指令（可选）
# instructions = "回复使用中文"

# 上下文压缩阈值（可选）
# model_auto_compact_token_limit = 115000

# 移动端中转服务器（可选）
# relay_server_url = "http://your-server.com:8080"

# ─── 供应商配置 ───

[model_providers.openai]
base_url = "https://api.openai.com/v1"
experimental_bearer_token = "sk-..."
wire_api = "chat"           # chat / responses / anthropic / google
requires_openai_auth = true

[model_providers.deepseek]
base_url = "https://api.deepseek.com"
experimental_bearer_token = "sk-..."
wire_api = "chat"
requires_openai_auth = false

[model_providers.zhipu]
base_url = "https://open.bigmodel.cn/api/paas/v4"
experimental_bearer_token = "your-key.here"
wire_api = "chat"
requires_openai_auth = false

# ─── MCP 服务配置 ───

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]

# ─── Hooks 配置 ───

[hooks]

供应商配置

CN-Codex 内置 12+ 种供应商预设模板：

传输协议说明

• chat — 标准 OpenAI Chat Completions 格式，适用于大多数 OpenAI 兼容供应商
• responses — OpenAI Responses API 格式
• anthropic — Anthropic Claude 原生 API 格式
• google — Google Gemini 原生 API 格式

供应商面板操作流程

1. 设置 → 模型提供商 → 点击 添加供应商
2. 从预设列表选择类型（同一类型可创建多个实例）
3. 填写 名称、API Key、Base URL、默认模型 ID
4. 选择 传输协议（大多数国内供应商选 chat）
5. 可选：设置 推理强度、联网搜索、最大输出 Token
6. 点击 保存
7. 点击实例右上角的 启用 按钮将其设为默认供应商

模型列表

每个供应商可以配置多个模型。在供应商面板底部的「模型列表」区域添加模型 ID 和显示名称。如果模型支持图片分析，勾选 支持图片/视觉。添加后可在输入栏底部的模型选择器中快速切换。

中转站 / free plan 配置（推荐）

CN-Codex 特别适合接中转站和 free plan。官方源、商汤 free coding plan、中转 Grok 可同时存在，随时切换。

1. 设置 → 模型提供商 → 添加供应商
2. 选择 OpenAI 兼容 或 自定义（也可复制 DeepSeek 预设后改 Base URL）
3. 填写：
   • 名称：如 商汤 DeepSeek / 中转 Grok
   • Base URL：中转站或 free plan 提供的 API 地址
   • API Key：对应渠道 Key
   • Wire API：通常选 chat
4. 在模型列表添加模型 ID，例如 deepseek-v4-flash、grok-4.5
5. 保存后启用该供应商；输入栏底部可随时切换模型

# 示例：商汤 free plan / 中转站（OpenAI 兼容）
[model_providers.sensetime-deepseek]
name = "商汤 DeepSeek"
base_url = "https://your-free-plan-or-relay.example/v1"
wire_api = "chat"
# api_key 建议在设置面板填写，不必明文写入仓库

[model_providers.relay-grok]
name = "中转 Grok 4.5"
base_url = "https://your-relay.example/v1"
wire_api = "chat"

推荐组合：日常开发用 DeepSeek v4 Flash（官方或商汤 free plan）；复杂推理 / 架构设计切中转 Grok 4.5；需要高可用时，给同一模型配置本地资源池多端点做容灾。

审批策略

除了配置文件中的全局策略，输入栏底部的 自动审批开关 也可以临时覆盖审批行为。

MCP 服务配置

MCP（Model Context Protocol）允许连接外部工具服务器来扩展 AI 能力。

在 config.toml 中配置

# stdio 类型
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]

# HTTP 类型
[mcp_servers.my-api]
url = "http://localhost:8080/mcp"

# 可选字段
# type = "stdio"
# cwd = "/working/dir"
# env = { FOO = "bar" }
# headers = { Authorization = "Bearer xxx" }
# disabled = false

通过设置面板导入

设置 → 工作区 / MCP → 点击 导入 JSON，粘贴 MCP 配置 JSON 即可批量添加。格式为：

{ "server-name": { "command": "...", "args": ["..."] } }

设置 — 通用

• 语言 — 中文 / English 切换
• 主题 — 深色 / 浅色 / 跟随系统
• Web 服务（手机同步） — 开关控制，开启后在局域网起 HTTP + WebSocket 服务，手机扫码访问
• 中转服务器 — 配置公网 relay 地址后，手机无需与 PC 在同一局域网。留空使用直连模式

设置 — 模型提供商

左右分栏布局：左侧是供应商实例列表，右侧是选中实例的配置表单。详见上方供应商配置章节。

设置 — 用量追踪

显示 Token 使用统计，支持按 7 天 / 30 天 / 全部 时间范围筛选。包括：

• 总计输入/输出 Token 数
• 每日用量趋势
• 按模型分组的用量统计

设置 — 工作区 / MCP

查看当前运行时路径和已配置的 MCP 服务列表。显示的路径包括：配置文件路径、配置目录、技能目录、插件目录、工作目录。

MCP 服务支持删除和导入操作。

设置 — 插件管理

管理 codey/plugins/ 下的插件。每个插件包含 .codex-plugin/plugin.json 元数据文件。

• 启用/禁用 — 切换插件的激活状态
• 卸载 — 从磁盘移除插件目录
• 导入 Codex — 从本地 Codex CLI 的插件缓存（~/.codex/plugins/cache）一键导入插件

设置 — Skills

查看 codey/skills/ 下的所有技能。每个技能是一个包含 SKILL.md 的文件夹。技能按分类展示：

• 代码审查
• GitHub / CI
• 浏览器 / 测试
• 项目工具
• 诊断 / 运维
• 文档 / 招标
• 多媒体 / 设计

点击技能可预览其内容。

设置 — 机器人管理

展示所有 AI 创建的机器人列表。每个机器人卡片显示：名称、描述、技能数量、工作流步骤数。点击可展开查看详细的技能列表和工作流配置。支持删除操作。

设置 — SmartBrain

管理 SmartBrain 经验知识库系统：

• 开关 — 启用/禁用 SmartBrain 功能
• 经验面板 — 浏览、展开、删除 AI 自动提取的经验条目
• 知识库面板 — 上传文档到知识库、浏览已有文档、删除、迁移到 OKF 格式、重建搜索索引
• 搜索 — 在经验和知识库中进行 BM25 全文搜索

设置 — 规则

编辑全局用户规则文件（codey/user-rules.md）。支持 Markdown 格式的自由文本编辑器。

项目规则不在此处管理，而是通过右侧文件树的右键菜单 → 编辑项目规则 来操作。

设置 — Hooks

查看已配置的自动化钩子。Hooks 在特定事件触发时自动执行命令：

Hooks 可在 codey/config.toml 的 [hooks] 部分或 hooks.json 中配置。

斜杠命令

在输入框中输入 / 会弹出命令面板，支持模糊搜索。

附件功能

支持的文件类型

• 图片 — 所有 image/* 类型（需要模型支持视觉能力）
• 文档 — PDF、Word（.docx/.doc）、Excel（.xlsx/.xls）、PowerPoint（.pptx/.ppt）
• 文本 — Markdown、纯文本、CSV、JSON、YAML、TOML、XML、HTML

添加方式

1. 点击输入框左侧的 回形针按钮，通过系统文件选择器添加
2. 从右侧 文件树拖拽 到输入框区域
3. 从系统文件管理器直接 拖放文件 到输入框区域

移动端

CN-Codex 内置 Web 服务，可以通过手机浏览器实时同步 PC 端的对话、查看 AI 回复、甚至直接从手机发送消息让 PC 上的 AI 执行任务。支持两种连接模式：局域网直连和公网中转。

局域网模式（手机和 PC 在同一 WiFi）

第一步：在 PC 端开启 Web 服务

1. 点击侧边栏底部的 设置 按钮，进入 通用 标签页
2. 找到「Web 服务（手机同步）」区域
3. 点击 开关 打开 Web 服务
4. 开启成功后，下方会显示局域网 URL（如 http://192.168.1.100:19527）

第二步：手机扫码连接

1. 在 PC 端点击标题栏右上角的 二维码按钮（QR 图标）
2. 弹出窗口中会显示一个二维码和对应的 URL 地址
3. 用手机的 相机 或任意 扫码 App（微信扫一扫、浏览器扫码等）扫描该二维码
4. 手机浏览器会自动打开 CN-Codex 移动端页面

第三步：使用手机端

手机端页面功能包括：

• 顶部状态栏 — 显示「已连接」（绿色圆点）或「断开」状态，以及返回按钮
• 对话列表 — 显示 PC 端的最近 20 个对话，当前活跃的对话有高亮标记，如果 PC 端正在某个对话中，手机端会自动跳转到该对话
• 聊天界面 — 用户消息以气泡形式显示，AI 回复支持 Markdown 渲染和代码高亮，流式输出时有打字动画效果
• 工具调用卡片 — 当 AI 调用工具时，手机端显示工具名称卡片（如 shell、read_file 等）
• 发送消息 — 底部输入框可以直接发送消息，消息会传到 PC 端的 AI 引擎执行

公网模式（中转服务器远程控制）

如果你的手机和 PC 不在同一局域网（例如在外面用手机远程控制家里的 PC），需要部署一台中转服务器（Relay Server）。

工作原理

中转服务器的通信架构如下：

手机浏览器  ←→  中转服务器（公网）  ←→  PC 端 CN-Codex
                  ↑                        ↑
            访问 /m/{房间ID}       WebSocket 连接到 /pc/{房间ID}
            HTTP 请求代理到 PC      广播 Agent 事件给手机

• PC 端启动 Web 服务时，与中转服务器建立 WebSocket 长连接，注册一个唯一的「房间 ID」
• 手机访问中转服务器的 /m/{房间ID} 页面，加载移动端 SPA
• 手机发送的 HTTP 请求由中转服务器代理转发给 PC 端处理
• PC 端的 AI 执行结果通过中转服务器广播给手机的 WebSocket 连接
• 断开时自动重连（PC 端 5 秒重试，手机端 3 秒重试）

中转服务器部署

CN-Codex 项目自带 relay-server 程序，部署到任意一台有公网 IP 的 Linux 服务器即可实现远程控制。

服务器要求

• 一台有公网 IP 的 Linux 服务器（阿里云、腾讯云、AWS 等均可）
• 开放 8080 端口（默认端口，可修改）
• 最低配置：1 核 1GB 内存足够（中转服务器只做消息转发，不运行 AI）

方案一：Windows 交叉编译 + 上传（推荐）

在你的 Windows 开发机上编译出 Linux 可执行文件，然后上传到服务器部署。

第一步：构建移动端前端

cd mobile-web
pnpm install
pnpm build

构建完成后，项目根目录会生成 mobile-dist/ 文件夹，包含移动端 SPA 的静态文件。

第二步：交叉编译 Relay Server

进入 relay-server/ 目录，运行 publish.bat：

cd relay-server
publish.bat

此脚本会：

1. 使用 cargo-zigbuild 或 cross 交叉编译出 Linux x86_64 的可执行文件
2. 将编译产物、mobile-dist/、部署脚本打包到 relay-server/publish/ 目录

第三步：上传到服务器

scp -r relay-server/publish/* root@你的服务器IP:/tmp/cn-codex-relay/

第四步：在服务器上执行部署

ssh root@你的服务器IP
cd /tmp/cn-codex-relay
chmod +x deploy.sh
./deploy.sh

deploy.sh 会自动完成以下步骤：

1. 复制可执行文件到 /opt/cn-codex-relay/
2. 复制 mobile-dist/ 静态文件
3. 安装 systemd 服务单元
4. 启动服务并设置开机自启

方案二：直接在服务器上编译

如果你的服务器本身有 Rust 开发环境，可以直接在服务器上编译。

第一步：上传源代码

# 上传 relay-server 目录和 mobile-web 目录到服务器
scp -r relay-server mobile-web root@你的服务器IP:/tmp/cn-codex-src/

第二步：构建移动端前端

# 需要服务器有 Node.js 和 pnpm
cd /tmp/cn-codex-src/mobile-web
pnpm install && pnpm build
# 将 mobile-dist 放到 relay-server 目录下
cp -r ../mobile-dist /tmp/cn-codex-src/relay-server/mobile-dist

第三步：一键编译+部署

cd /tmp/cn-codex-src/relay-server
chmod +x deploy/setup.sh
sudo ./deploy/setup.sh

setup.sh 是全自动脚本，会自动安装 Rust（如需）、编译 release 版本、安装到 /opt/cn-codex-relay/、配置 systemd 服务、开放防火墙端口。

验证部署

# 查看服务状态
systemctl status cn-codex-relay

# 查看实时日志
journalctl -u cn-codex-relay -f

# 在浏览器中访问测试
curl http://你的服务器IP:8080/health

服务管理命令

在 PC 端配置中转服务器

服务器部署完成后，需要在 PC 端的 CN-Codex 中配置中转地址：

1. 打开 CN-Codex → 设置 → 通用
2. 找到「中转服务器（公网访问）」区域
3. 填入服务器地址，格式为 http://你的服务器IP:8080
4. 点击 保存
5. 如果 Web 服务已开启，需要 关闭后重新开启 Web 服务才能生效
6. 重新开启后，二维码将指向中转服务器地址（如 http://你的服务器IP:8080/m/xxxxxxxxxxxx）

手机远程使用流程

配置完成后，使用流程与局域网模式完全一致：

1. 确保 PC 端 Web 服务已开启（且配置了中转服务器地址）
2. 点击标题栏的 二维码按钮
3. 手机扫描二维码（此时 URL 指向公网中转服务器）
4. 手机浏览器打开移动端页面，即可远程查看和操作 PC 上的 AI 对话

此时手机无需与 PC 在同一网络。你可以在外出时用手机监控 AI 执行情况，或直接从手机发送新指令让 PC 上的 AI 处理。

通过配置文件设置中转地址

除了在设置面板 GUI 中配置，也可以直接编辑 codey/config.toml：

# 中转服务器地址（不需要尾部斜杠）
relay_server_url = "http://你的服务器IP:8080"

保存后重启 Web 服务即可生效。

内置工具一览

AI 在对话中会根据需要自动调用这些工具（50+）。以下按类别列出常用工具。

文件与目录

命令执行

浏览器与录制

子代理

记忆与知识

MCP

其他

常见问题

获取帮助