跳转至

快速入门

从零开始，大约 5 分钟内让 Cortex 智能体在聊天工具中回复你，其中大部分时间是在等待 npm 安装和填写聊天平台的应用创建页面。

Cortex 通过 Slack 或飞书（Lark）与你对话——任选其一，或同时运行两者。cortex init 几乎完成所有工作。你不需要手动编辑任何配置文件。本指南告诉你每个提示的预期内容，并精确指示界面中的操作位置。

不想用终端？

桌面应用可以在 macOS、Linux 和 Windows 上替你安装并配置 Cortex。选择安装 Cortex，等待安装与启动自动完成，再登录并选择默认模型。全新安装使用本机 hostname、端口 3004，不安装登录自启服务；已有机器、端口和服务设置会被保留。只有初始化、启动或连接失败才提供修复设置。Slack 与飞书设置会被跳过——应用本身就是交互界面。登录可能需要在浏览器中授权或完成 MFA；macOS 首次打开应用时可能需要 Gatekeeper 确认。

安装包自带 Node.js，Windows 安装包另含 Git Bash，因此不需要终端、另行安装的 Node.js 或 Git、Homebrew 或管理员权限。本机安装支持 macOS 13.5+、glibc 2.28+ 的 x86_64 Linux，以及 x86_64 的 Windows 10/11；详见桌面应用指南。以下内容介绍终端安装与聊天平台设置。

前置条件

以下要求与命令适用于终端安装。

  • Node.js ≥ 22.19.0，服务端内置 PI SDK 要求此版本或更高。
  • 一个 Slack 工作区或一个飞书（Lark）组织，你可以在其中创建应用。
  • 大约 2 GB 空闲磁盘空间，用于后端、插件和日志。

你不需要预先安装编程智能体。PI 引擎随 Cortex 服务器包一起打包。Claude Code 是可选项；选择其登录流程时，若尚未安装，会提供安装选项。macOS/Linux 不要求安装 Git。cortex init 创建目录和 env 文件，仅在已有可用 Git 时初始化版本历史。版本历史和 Git 来源的扩展需要 Git，Windows shell 工具需要 Git Bash。

检查 Node.js 版本

打开终端，运行：

node --version

你应该看到类似 v22.19.0 的输出。如果版本低于 22.19.0，或看到 command not found: node，请使用以下方法安装或升级 Node.js。

安装 Node.js

macOS（Homebrew）：

brew install node@22

Linux（nvm，推荐）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
# 重启终端，然后：
nvm install 22
nvm use 22

Linux（apt，仅适用于软件源提供 Node ≥22.19.0 的系统）：

sudo apt update && sudo apt install nodejs npm

Windows：

从 nodejs.org 下载 LTS 安装包（选择 ≥22.19.0 的 LTS 版本）。运行 .msi 安装程序并按提示操作。安装完成后重启终端。

验证安装：

node --version   # 必须输出 v22.19.0 或更高版本
npm --version    # 应输出 10.x.y 或更高

第一步 — 安装 Cortex

npm install -g @cortex-agent/server

这会在你的 PATH 中放置 cortex 命令，以及三个辅助命令：cortex-signal、cortex-hook 和 cortex-evidence-export。

如果 npm install -g 因权限错误而失败（Linux 上常见），请加 sudo，或更好的做法是配置 npm 使用用户本地前缀：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @cortex-agent/server

第二步 — 运行设置向导

cortex init

向导会遍历以下提示。默认值都是合理的；按回车接受即可。以下是每个提示的作用及如何回答。

2.1 选择语言

Select language / 选择语言
❯ English
  中文 (Simplified Chinese)

第一个提示选择 Cortex 用于系统生成消息以及本向导其余部分的语言。它默认采用你的系统区域设置，所以中文系统会预选 中文。该选择会保存到 config/preferences.json，之后可通过 !lang 命令更改。

2.2 内置 PI 与可选 Claude Code

交互式 cortex init 默认使用 PI，不询问后端选择。PI 随 Cortex 一起打包，只需配置 Provider 凭据，无需单独安装。继续填写平台与机器设置；配置文件写入后，再进入第 2.10 节的凭据检测与登录。

Claude Code 是可选项，与 PI 中的 Anthropic Provider 相互独立。在登录步骤选择 Claude Code 时，会复用已有安装，或在缺失时询问是否允许安装。

2.3 选择交互平台

? 你想使用哪些交互平台？（空格切换，回车确认，留空跳过）
❯ ◯ Slack（推荐）
  ◯ Feishu (飞书)

这是一个多选项。用空格切换，回车确认。可以选 Slack、飞书，或两者都选——Cortex 会组合你选择的平台并同时连接到所有平台。你选择的每个平台都会触发各自的凭据收集步骤（先 Slack，后飞书）。

留空则跳过平台设置。稍后可编辑 $CORTEX_HOME/config/.env 来配置某个平台，然后重启服务器。

2.4 Slack 应用设置（在浏览器中逐步操作）

如果你没有选择 Slack，跳过本节。

Cortex 首先打印完整的 Slack 应用清单，并询问是否要复制到剪贴板。按 c 键 — 清单 JSON 现在已复制到剪贴板。

a) 打开 Slack API 应用页面

前往 https://api.slack.com/apps。

b) 从清单创建新应用

点击绿色的 Create New App 按钮，然后点击 From a manifest。如果还没有工作区，需要先创建一个。

Create New App → From a manifest

c) 选择工作区并粘贴清单

  1. 从下拉菜单中选择你的 Slack 工作区。
  2. 将清单 JSON 粘贴到文本区域（Ctrl+V / Cmd+V）。清单已由 cortex init 复制到剪贴板，直接粘贴即可。
  3. 点击 Next。
  4. 查看摘要后点击 Create。

粘贴清单并选择工作区

d) 复制 Signing Secret

创建完成后，Slack 会将你带到应用的 Basic Information 页面。在 App Credentials 下方，找到 Signing Secret。点击 Show 并复制。

回到终端，将其粘贴为 SLACK_SIGNING_SECRET。

复制 Signing Secret

e) 生成 App-Level Token（xapp-…）

在同一 Basic Information 页面向下滚动到 App-Level Tokens 部分。点击 Generate Token and Scopes。

  • Token Name：cortex-socket
  • Add Scope：connections:write
  • 点击 Generate

复制出现的令牌（以 xapp- 开头）。注意：令牌只显示一次，请立即复制。

回到终端，将其粘贴为 SLACK_APP_TOKEN。

生成 App-Level Token

f) 安装到工作区并复制 Bot Token（xoxb-…）

在左侧边栏中点击 OAuth & Permissions。滚动到 OAuth Tokens 部分，点击 Install to Workspace。在授权页面上点击 Allow。

安装完成后，页面顶部会显示 Bot User OAuth Token（以 xoxb- 开头）。复制它。

回到终端，将其粘贴为 SLACK_BOT_TOKEN。

OAuth & Permissions → Install to Workspace

复制 Bot User OAuth Token

g) 启用 Messages Tab

在左侧边栏中点击 App Home。向下滚动到 Show Tabs 部分：

  • 勾选 Messages Tab（使其出现在机器人的 App Home 中）。
  • 勾选 Allow users to send Slash commands and messages from the messages tab（以便你可以给机器人发私信）。

如果不勾选此项，你可以在频道中 @cortex 机器人，但无法给它发私信。

在 App Home 中启用 Messages Tab

h) 管理频道

Cortex 会把启动通知、审批请求和其他运维消息发送到管理频道。设置过程中无需输入任何内容——Cortex 会在你第一次给机器人发私信时自动检测管理频道并持久化。

如果你想把管理消息发送到指定频道（例如共享的运维频道），从 Slack 获取频道 ID（右键点击频道名称 → View channel details → 在对话框底部复制 Channel ID），然后在 $CORTEX_HOME/config/settings.json 中设置 adminChannel 键（见 configuration.md）。.env 中的旧变量 SLACK_ADMIN_CHANNEL / CORTEX_ADMIN_CHANNEL 仍作为已弃用的回退可用。

2.5 飞书应用设置（在浏览器中逐步操作）

如果你没有选择飞书，跳过本节。Cortex 会打印设置指南，然后收集你的应用凭据。

a) 创建飞书应用

前往 https://open.feishu.cn/app，点击 创建 agentic 应用（Create Agentic App）。输入应用名称（例如 CortexAgent），选择头像，然后点击 创建。

创建飞书智能体应用

b) 复制 App ID 和 App Secret

创建后，应用页面会显示 App ID 和 App Secret。复制它们。

复制飞书 App ID 和 App Secret

回到终端，在 FEISHU_APP_ID 和 FEISHU_APP_SECRET 提示处粘贴。

c) 订阅消息事件

在应用的事件配置中，启用机器人事件并订阅 im.message.receive_v1。如果不订阅，机器人永远收不到你的消息。

d) 域名（可选）

? FEISHU_DOMAIN（可选，"feishu" 或 "lark"）：
  feishu（留空使用默认值）

输入 feishu 使用飞书（中国大陆）域名，或输入 lark 使用国际 Lark 域名。留空则使用默认值。

e) 文档操作的身份

? MCP 文档操作的身份：
  bot   —— 文档由应用拥有
❯ user（推荐）—— 文档由你的飞书账号拥有

Cortex 的 MCP 工具可以创建和编辑飞书文档（docx、wiki、bitable、sheets、drive）。此提示决定这些文档的归属。选择 bot 使应用成为拥有者。选择 user 使你自己的飞书账号成为拥有者，文档会保留在你的个人空间中——这是推荐选项。

如果选择 user，cortex init 会立即运行飞书用户登录（OAuth 设备流程），让你一次性完成授权。它会打印一个 URL——在任意浏览器中打开，批准访问，Cortex 会自动轮询获取令牌，无需重定向 URI。如果你跳过或中止登录，凭据仍会被保存，之后可用 cortex feishu login 完成授权。

2.6 机器名称

默认为你的主机名。除非你想要自定义标签，否则直接按回车。

2.7 GPU 检测

Cortex 运行 nvidia-smi 并打印数量。无需输入。如果没有 NVIDIA GPU，它会打印 0 — 对于大多数使用场景完全没问题。

2.8 aistatus 令牌使用报告？

可选，且这一项默认为「是」。选择是会把你的 token 用量放到 aistatus.cc 公开排行榜上，排行榜显示你的名称、组织和 token 数；不想上榜请选否。加入时需要填写名称和邮箱，组织可选；邮箱只用于识别身份，不会公开显示。

桌面应用的 Provider 设置页也以可选的公开用量排行榜卡片提供同一选项，之后可随时在设置 → 用量中开启或关闭。关闭后会保留已填写的名称、组织和邮箱，再次开启时沿用。

2.9 注册为系统服务？

  • macOS — 在 ~/Library/LaunchAgents/cc.cortex.agent-server.plist 创建 launchd plist。运行打印的启用命令后，守护进程会在登录时自动启动。
  • Linux — 创建 systemd --user 单元（无需 sudo）。运行打印的启用命令后，守护进程会在登录时自动启动。如需登出后继续运行，再执行 loginctl enable-linger。
  • Windows — 不支持。需手动运行 cortex daemon。

2.10 检测凭据、登录并配置模型

写入配置文件后，Cortex 自动检测本地 Claude Code 与 PI 凭据。这是凭据检测，不是在线推理测试：不会发起付费推理请求，也不保证模型调用一定成功。

终端提供以下操作：

  • 使用已配置的服务商继续（Continue with configured providers）——检测到凭据后才出现。使用这些凭据，从发现的端点配置 gateway 路由与 models.json。先单选默认模型（预选推荐模型），再多选收藏。即使在此步骤取消勾选默认模型，它也会包含在收藏中。
  • 登录 / 安装并登录 Claude Code（Login / install and login Claude Code）——选择后端、Provider 及其支持的 OAuth 或 API key 方式。PI 已内置；Claude Code 已安装时直接复用，只有选择其登录路径时才会询问是否安装缺失的程序。登录后返回凭据检测。
  • 重新扫描凭据（Rescan credentials）——重新检测凭据（例如在其他终端配置的凭据），然后回到这个菜单。
  • 稍后配置（Configure later (Agent may be unavailable)）——不配置 Provider 直接完成初始化；配置好凭据与默认模型 前，Agent 不可用。

也可直接从终端登录，无需运行 daemon：

cortex auth login
cortex auth login --backend pi --provider anthropic --auth-type api_key
cortex auth login --backend claude --provider anthropic --auth-type oauth
cortex auth status

登录要求交互式 TTY。密钥与授权响应通过提示输入，不能作为命令参数传入。命令将 JSON 结果写入 stdout，将面向人的提示与指引写入 stderr。cortex auth login --help 列出选项，详见 CLI 参考。

使用 --answers <file> 或 --json 时，init 检测凭据并报告状态，不会启动 Provider 登录或等待输入。省略 backends 时默认使用 PI；显式提供 backends 时保留所指定的后端选择与安装行为。即使尚未配置 Provider，这类运行也能完成。之后可用 cortex auth login 或设置 → 账号登录；cortex auth login 成功后也会配置 gateway 路由、默认模型与收藏。cortex setup-gateway 可单独重新执行这一配置。Slack 或飞书中也可通过 !login 远程登录，参见后端：远程登录。

非交互式模型选择可通过 --answers 的 defaultChoice 和 favorites 指定，每个选择都是包含 mode 与 model 的对象。显式 defaultChoice 会替换已保存的默认值，否则保留它；收藏合并并包含所选默认模型。按位置读取的 stdin 协议末尾有两行模型选择：第一行为默认模型的 mode:model，第二行为逗号分隔的收藏 mode:model。

2.11 后端登录过期怎么办

后端凭据会在一段时间后过期。过期后智能体运行会失败并报认证错误，例如：

Failed to authenticate. API Error: 401 OAuth access token has expired.
Re-authenticate to continue.

使用 cortex auth login 重新登录，或使用 Slack/飞书中的 !login 或设置 → 账号。Claude Code 也支持 claude 加 /login。

后端登录提示

Cortex 也会主动提醒。运行中的智能体一旦撞上认证过期，就会发出点名 provider 的通知卡，卡上带一键重登按钮；每日扫描还会对临近过期的凭据发出预警。

登录完成后，刷新的凭据会在下一次智能体运行时被识别。如果端点或模型发生了变化，重新运行 cortex setup-gateway 刷新网关与模型列表，再在设置 → 模型中选择所需默认模型。同步保留已有默认值。

向导完成后你会看到：

Cortex initialized at /home/you/.cortex. Run `cortex daemon` to launch.

cortex init 创建了什么

所有内容都位于 CORTEX_HOME（默认 ~/.cortex/）下：

~/.cortex/
├── .git/                       # 可选：已有可用 Git 时创建
├── .gitignore                  # 把运行时状态和密钥排除在版本历史之外
├── AGENTS.md                   # 根智能体上下文（从默认值初始化）
├── config/
│   ├── .env                    # CORTEX_PLATFORM 列表 + 平台令牌 + CORTEX_MACHINE
│   ├── feishu-user-token.json  # 飞书用户身份令牌（仅当 FEISHU_AUTH_MODE=user 时）
│   ├── preferences.json        # 操作者界面语言
│   ├── budget.json             # 每日/每月预算限制
│   ├── machines.json           # 本机能力（gpuCount、路径）
│   ├── mcp-config.json         # 直接会话 MCP 服务器
│   ├── mcp-config-core.json    # 远程执行/时间分层
│   ├── mcp-config-empty.json   # 不含 MCP 服务器
│   ├── mcp-config-interaction.json # 共享交互分层
│   ├── models.json             # 默认引擎与收藏，检测到凭据后生成
│   └── environments/           # 执行环境：main.json、creative.json
├── data/
│   ├── agent-state.json        # 频道选择、模型记忆、新会话选择、默认智能体
│   └── schedules.json          # 初始化的内置定时任务
├── context/                    # 项目日志存放在这里
│   ├── AGENTS.md、projects/、decisions/、scans/、ideas/、retrospectives/、user/
├── plugins/                    # 你的插件（内置插件从安装目录读取）
├── prompts/                    # 你的指令、系统提示、模板
├── hooks/                      # 你的钩子脚本（.mjs）
├── .claude/                    # Claude Code 设置
└── logs/                       # 守护进程 + LLM 日志

正常使用时你不应该手动编辑任何这些文件。再次运行 cortex init 时，已有的 .env、machines.json、Agent 状态、语言偏好、计划任务和预算保持不变，MCP 配置会重新生成。cortex init --force 会重置 machines.json、Agent 状态、语言偏好、计划任务和预算，并更新 init 写入 .env 的键，同时保留已有的客户端与 webhook token 以及你手动添加的键。两种情况下，已有的执行环境和脚手架文件都会保留，交互式设置会在替换已有默认模型前询问，收藏则与已有列表合并。使用 --force 前请备份自定义文件。要给已经可用的安装添加平台，把该平台的键加入 .env 并重启守护进程即可（见 2.3）。

Cortex 的内置插件、钩子、规则、子智能体角色与系统提示词从安装目录读取，不会复制到这里，所以 plugins/、prompts/ 和 hooks/ 一开始是空的。你放进去的文件会替换同名的内置文件，或新增一个；见内置资源与你的覆盖。

~/.aistatus/ 单独存放：

~/.aistatus/
├── gateway.yaml                # 网关路由配置（检测到凭据后生成）
└── config.yaml                 # aistatus 上传器设置（你的姓名/组织/邮箱）

第三步 — 启动服务器

cortex daemon         # 在后台受监督运行，崩溃重启 + 热重载
# 或
cortex start          # 前台运行，Ctrl-C 停止

cortex daemon 会立即返回，服务器留在后台运行；cortex daemon stop 停止它。

如果你在第二步 2.9 中选择了注册系统服务，init 会写入服务文件并打印启用命令。需要运行该命令才能启动服务：

# Linux 用户服务
systemctl --user enable --now cortex
# macOS
launchctl load ~/Library/LaunchAgents/cc.cortex.agent-server.plist

用 cortex daemon status 检查守护进程状态；cortex config 显示解析后的路径和初始化状态；cortex doctor 检查运行时、登录、平台和 gateway（--fix 修复能修复的部分）。

打开 Web 工作台

浏览器工作台以及桌面和 Android 应用都连接服务器的 Web UI 端点，终端安装默认不开启它。用以下命令开启：

cortex ui enable
cortex daemon restart   # 仅当守护进程已在运行时需要

cortex ui enable 会在需要时生成客户端 token，在 $CORTEX_HOME/config/.env 中设置 CORTEX_UI_HTTP=1 与 CORTEX_UI_PORT=3004，放行原生应用的 origin，并打印本地地址。在服务器上用浏览器打开 http://127.0.0.1:3004，用 .env 中 CORTEX_CLIENT_TOKEN 的值登录；或在桌面应用中填入同样的地址和 token。要从其他电脑访问工作台，见浏览器访问。

第四步 — 发送你的第一条消息

现在进入有趣的部分。打开 Slack 或飞书，找到你刚安装的 Cortex 机器人，发起私信（DM）。在 Web 工作台中，则在新会话的输入框里发送同样的消息。

4.1 打个招呼

给机器人发私信：

hello

第一条私信是 Cortex 用来自动检测管理频道的（除非你在 config/settings.json 中显式设置了 adminChannel）。你应该在几秒钟内收到回复。

4.2 创建你的第一个项目

给 Cortex 一个使命。Cortex 会创建项目、设置目录结构并回复确认：

创建一个叫"天气仪表盘"的项目，我想做一个显示我所在城市天气的简单网页仪表盘

Cortex 会回复它创建的项目结构，以及它对使命的理解。

4.3 查看项目状态

天气仪表盘项目进展如何

Cortex 会读取项目的 STATUS.md、使命和最近的实验记录，然后给你一个当前状况的摘要。

当工作分给多个 worker 或要持续很多小时时，Cortex 会在 Web UI 里开一个看板：显示在对话旁边的状态页，展示任务的状态、计划和决策。你也可以直接要求开一个。参见看板。

  • 创建 Slack 应用时出了问题，或想在运行 cortex init 之前先完成设置 — 阅读 slack-setup.md。
  • 想了解 Cortex 识别的每个配置文件和环境变量，或覆盖某个自动生成的路径 — 阅读 configuration.md。
  • 想了解每个 CLI 子命令和标志 — 阅读 cli-reference.md。
  • 想切换后端或添加其他提供商 — 阅读 backends.md。
  • 想让 Cortex 把工作交给子智能体，或带领持久的 worker 会话 — 阅读 backends.md 和 team.md。
  • 想将远程机器连接到 Cortex — 阅读 cross-machine.md。
  • 想了解项目日志结构（实验、知识、模式）— 阅读 memory.md。