# 指南

介绍 OpenChatly 各个部分的功能、工作原理以及配置方法。

Canonical page: https://openchatly.com/docs/zh/guide

OpenChatly，以全场景 AI 工作台为核心的公司操作系统（CompanyOS）：专为打造云原生智能体（Agent）而生的企业级工具。你的智能体、它们的技能以及可访问的权限，都以文件的形式统一存放在一个 Git 仓库中。OpenChatly 会在云端运行这些智能体，每个会话（Session）都在独立的云计算机上执行。你的团队可以通过网页、桌面端和移动端应用，或者借助 Slack、Microsoft Teams、Telegram、Discord 和微信等协作平台与它们进行交互。

本指南将按照你接触到的顺序，逐一介绍 OpenChatly 的各个组成部分，并说明如何在网页应用中进行配置。如果你想了解 OpenChatly 的技术原理等相关内容，请阅读 [开发者文档](/docs/zh/developers)。

## 工作原理

1. **项目包含一切**

    一个项目就是一个 Git 仓库。其中的智能体、技能、记忆和连接器设置都以文件的形式存在。OpenChatly 可以为你提供仓库托管服务，或者你也可以直接连接你在 GitHub或者 Gitee 上的仓库。

2. **你开启一个会话**

    一个会话代表智能体的一项具体工作。你只需描述任务，智能体就会接手处理。该会话在独立的云计算机上运行，因此它绝不会触及你的本地电脑或其他会话。

3. **智能体执行工作**

    智能体会遵循其指令和技能，调用相关工具和连接器，最终产出结果。当它需要做出决策时，会向你询问。

4. **人工审批项目变更**

    当智能体对项目本身（例如某项技能或记忆）进行修改时，它会发起一个变更请求（Change Request）。团队成员可以在 **Review（审核）** 页面上进行审查并合并该变更。

围绕这一工作循环：

- **你与 My OpenChatly 对话。** 它会将每个任务分发给专门负责该任务的智能体，并在其专属的会话中执行，随后向你反馈结果。在工作运行期间，你可以继续与它交流。请参阅 [内置智能体](#内置智能体)。
- **智能体可自动启动。** 通过定时任务、Webhook 或其他应用中的事件，可以在无人在键盘前操作的情况下自动启动一个会话。请参阅 [触发器](#触发器triggers)。
- **智能体并行运行。** 每个会话都拥有独立的云计算机，因此多个智能体可以同时工作而互不干扰。请参阅 [多智能体同时运行](#多智能体同时运行)。
- **长任务保留完整细节。** 当某个会话的上下文空间用尽时，智能体会在一个全新的上下文中继续工作，并从该会话的完整记录中精确查找所需的早期信息。没有任何内容会被摘要或丢弃。
- **人工始终掌握控制权。** 对项目的任何更改都会在 **Review（审核）** 页面等待，直到人工完成合并。如果某个连接器规则设置为 **Ask（询问）**，该操作会暂停，直到获得人工批准。

## 各组件如何协同工作

| 组件 | 说明 | 阅读 |
| --- | --- | --- |
| Agents（智能体） | 包含指令、模型以及智能体可使用的资源列表。每个会话运行一个智能体。 | [Agents](#智能体agents) |
| Skills（技能） | 智能体为执行某类特定任务而加载的书面操作程序。 | [Skills](#技能skills) |
| Apps（应用） | 由智能体构建并由 OpenChatly 托管的网站、内部工具和后端。 | [Apps](#应用apps) |
| Drive（云盘） | 跨越会话持久存在的文件，包括智能体关于你的记忆。 | [Drive](#云盘drive) |
| Artifacts（交付物） | 从云盘共享的文档和网页，具有唯一链接、版本历史记录和评论功能。 | [Artifacts](#交付物artifacts) |
| Connectors（连接器） | 对团队使用的应用和 API 进行受控访问的管理机制。 | [Connectors](#连接器connectors) |
| Triggers（触发器） | 用于启动智能体或唤醒会话的定时任务、Webhook、事件以及已合并的变更请求。 | [Triggers](#触发器triggers) |
| Computers（计算机） | 每个会话所运行的云计算机，以及你连接的个人计算机。 | [Computers](#计算机computers) |
| Models（模型） | 智能体运行的 AI 模型：可由 OpenChatly 托管，也可使用你自己的提供商密钥，或使用你的 ChatGPT 或 Claude 订阅。 | [Models](#模型models) |
| Outcomes（目标） | 智能体持续努力直至通过独立检查确认已完成的目标。 | [Outcomes](#目标outcomes) |
| Channels（渠道） | 包括 Slack、Microsoft Teams、Telegram、Discord 和微信，用户可通过向 OpenChatly 机器人发送消息来启动工作。 | [Channels](#频道channels) |
| Everywhere（全平台） | 涵盖网页、桌面和移动端应用、终端以及其他 AI 工具。 | [Everywhere](#全平台everywhere) |
| People and access（人员与权限） | 包含账户、成员、角色，以及谁有权运行哪个智能体。 | [People and access](#teams) |
| Security（安全） | 包含隔离机制、密钥管理、审计日志和单点登录（SSO）。 | [Security](#安全性) |
| Billing（计费） | 包含套餐、积分及其消耗情况。 | [Billing](#计费billing) |

## 快速上手

<video src="/media/guide/get-started.mp4" aria-label="Getting started in OpenChatly: open a project and start its first session" controls muted playsInline preload="metadata" style={{ width: '100%', borderRadius: '8px', border: '1px solid var(--border)' }} />

创建一个项目、运行一个会话、连接一个应用并邀请你的团队加入。所有这些操作都在网页应用中完成。

### 你需要准备什么

- 一个 OpenChatly 账户。请在 [openchatly.com](https://openchatly.com) 注册。
- 无需其他任何准备。OpenChatly 可以为你托管项目的仓库，因此你不需要拥有 GitHub 账户。

### 创建你的第一个项目

一个项目就是一个 Git 仓库。它存放着你的智能体、技能、记忆和连接器设置。新账户没有任何项目，OpenChatly 也不会自动为你创建。

1. **打开“创建项目”**

    在项目页面，选择 **Create a new project（新建项目）**。如果你已经在某个项目内部，打开侧边栏顶部的项目菜单，选择 **Switch Project（切换项目）** → **Create a project…（创建项目…）**。

2. **为其命名**

    输入一个 **Project name（项目名称）**。如果你隶属于多个账户，还需要选择相应的 **Account（账户）**。

3. **选择仓库存放位置**

    在 **Git account（Git 账户）** 下，选择 **OpenChatly managed（OpenChatly 托管）** 可获得最简单的起步方式：OpenChatly 会为你创建并管理一个私有仓库。如果你的公司使用 GitHub 或 Gitee，则改为选择你的 GitHub 或 Gitee 账户。

4. **完成创建**

    点击 **Create project（创建项目）**。项目创建后会自带 My OpenChatly、一个名为 `worker` 的通用智能体，以及一套现成的技能（ready-made skills）。

### 运行你的第一个会话

1. **开启新会话**

    在侧边栏中选择 **New session（新建会话）**。项目主页会随之打开，并显示一个空白的消息输入框（即编辑器 composer）。

2. **提出一个实际的任务**

    像给同事布置任务一样描述你的需求。如果有帮助，可以附上文件：点击附件按钮、粘贴文件，或者直接将文件拖拽到页面上。

3. **实时跟进**

    智能体在其专属的云计算机上工作，你可以在会话中随时查看它的进度。在它工作期间，你可以发送新的消息来引导它的方向。

4. **查看结果**

    侧边面板会显示智能体的计划和输出内容。如果智能体修改了你项目中的文件，标题栏中的 **Changes（变更）** 会显示具体的修改内容。

> **注意：** 在免费版（Free plan）下，运行会话需要你自行连接模型：可以使用你自己的模型提供商密钥或 ChatGPT 订阅。而积分版（Credits plan）和企业版（Enterprise）则还可以使用由 OpenChatly 托管的模型。请参阅 [Models（模型）](#模型models)。

### 连接你的第一个应用

当智能体能够访问你团队正在使用的应用时，它们将变得更加实用。连接器（Connector）可以在你设定的规则下赋予智能体这种访问权限。登录凭证会安全地保存在 OpenChatly 服务器上，绝不会进入智能体的运行计算机中。

1. **打开“连接器”**

    在侧边栏中选择 **Customize（自定义）**，然后点击 **Connectors（连接器）**。

2. **添加应用**

    找到目标应用，选择 **Install（安装）**，并完成登录。

3. **检查哪些智能体可以使用该应用**

    `worker` 智能体默认可以使用所有的连接器。对于其他智能体，只有在你明确授权后才能使用：请打开 **Customize（自定义）** → **Agents（智能体）** → 选择目标智能体 → **Connectors（连接器）**，然后开启相应的连接器开关。

关于 [Connectors（连接器）](#连接器connectors) 的更多详细信息（包括共享账户和审批规则），请参阅相关文档。

### 邀请你的团队

你可以在账户设置中管理项目成员。

1. **打开成员列表**

    依次打开 **Account settings（账户设置）** → **Projects（项目）**，或者在命令面板（command palette）中输入 "members"。

2. **邀请人员**

    邀请你的队友加入项目。他们可以在自己的项目列表中看到邀请，或者在移动端应用的 **Invites（邀请）** 页面中查看。

3. **允许他们运行智能体**

    成员只能使用分配给他们个人、他们所属的群组或整个项目的智能体来开启会话。你可以通过以下两种方式进行分配：
    - 打开 **Customize（自定义）** → **Agents（智能体）**，在目标智能体的 **People（人员）** 页面进行分配。
    - 依次打开 **Account settings（账户设置）** → **Projects（项目）** → 选择目标项目 → **Grant access（授予访问权限）**。

关于角色和群组的详细说明，请参阅 [People and access（人员与权限）](#teams)。

### 熟悉网页应用界面

| 位置 / 入口 | 功能说明 |
| --- | --- |
| **New session（新建会话）** | 开启一个新的会话。 |
| **Customize（自定义）** | 管理你的智能体及其相关配置，包括：**Agents（智能体）**、**Skills（技能）**、**Connectors（连接器）**、**Triggers（触发器）**、**Loops（循环）**、**Models（模型）**、**Secrets（密钥）**、**Repo（仓库）**、**Review（审核）** 和 **Settings（设置）**。其中，**Settings** 会打开 **Project admin（项目管理员）** 页面，包含项目的各项设置（包括 **Feature flags / 功能开关**）。 |
| **Drive（云盘）** | **My files（我的文件）**：包含你个人的文件，以及智能体关于你的记忆。 |
| **Apps（应用）** | 当前项目下的应用。 |
| **Artifacts（交付物）** | 项目中共享的文档和网页。 |
| **Sessions（会话）** | 你的所有会话列表。 |
| Search（搜索） | 命令面板：Mac 系统使用 `Cmd+K`，Windows 和 Linux 系统使用 `Ctrl+K`。 |
| Project menu（项目菜单，位于左上角） | 包含 **Switch Project（切换项目）**、**Account settings（账户设置）**、个人 **Settings（设置）** 以及 **Log out（退出登录）**。 |

桌面应用（支持 macOS、Windows、Linux）和移动应用（支持 iPhone、iPad、Android）可以访问相同的项目和会话。请参阅 [Everywhere（全平台）](#全平台everywhere)。

## 智能体（Agents）

<video src="/media/guide/agents.mp4" aria-label="Agents in OpenChatly: the agent list, an agent's instructions, adding an agent" controls muted playsInline preload="metadata" style={{ width: '100%', borderRadius: '8px', border: '1px solid var(--border)' }} />

智能体由一组指令、一个模型以及一份可用资源列表组成。指令规定了智能体要做什么、怎么做，以及绝对不能做什么。每个会话都会运行一个智能体。OpenChatly 的智能体运行在 pi（一个开源的智能体框架）之上，开发者可以通过 pi 扩展（extensions）来扩展它们的功能。

### 智能体的构成

一个智能体由两部分组成：

- **行为（Behavior）：** 包括它的指令、模型，以及关于工具使用的规则（哪些可以自由使用、哪些需要询问后使用、哪些绝对禁止使用）。
- **访问权限（Access）：** 包括它可以使用的连接器、密钥、技能、应用、OpenChatly 权限以及项目仓库。

访问权限默认是拒绝的。在你明确授予之前，智能体无法获得任何连接器、密钥、技能、应用或项目仓库的访问权。

### 内置智能体

**My OpenChatly** 是你直接与之对话的智能体。如果在开启会话时没有指定具体的智能体，系统就会默认运行它。My OpenChatly 会将每个任务分发给项目中专门负责该任务的智能体，并且它会以你的权限来执行操作。

- **它仅拥有你的权限，不会越权。** 在当前项目中，My OpenChatly 能做的事情受限于你的角色权限：例如创建和修改智能体、连接器、定时任务以及人员配置。如果你的角色不允许执行某项操作，它会如实告知，并指出哪些人有权限授予该操作。
- **它会先征求同意。** 在执行会影响他人的操作（如发送邀请、更改角色）、删除内容，或赋予智能体更多权限之前，它都会先向你确认。它会展示操作前后的具体变更内容。
- **它会进行任务交接。** 写作、调研、代码编写以及任何需要使用已连接应用的工作，都会被移交给专门负责该任务的智能体，且每项工作都在其独立的会话中进行。你可以在当前会话的卡片中点击打开那个专属会话。
- **每个操作都是一张卡片。** 卡片会展示它做了什么、哪些内容发生了变更，并提供一个链接，带你跳转到可以查看该变更的页面。
- **账户设置归你个人管理。** 计费、账户成员以及其他项目等设置超出了它的能力范围。遇到这类需求时，它会告诉你应该去哪里点击操作。

每个新项目还会自带一个项目级智能体 `worker`。它是一个通用智能体，当没有其他更合适的智能体时，My OpenChatly 就会将工作交接给它。它可以使用项目中所有的连接器、密钥、技能和 OpenChatly 权限，并且它会在项目仓库的一个副本上进行工作。你可以根据公司的实际需求修改它的指令。

当项目的 `kortix.yaml` 文件中设置了 `builtin_agents.my_kortix: true` 时（所有新项目默认均为开启状态），My OpenChatly 智能体即处于启用状态。

### 多智能体同时运行

My OpenChatly 会在后台为你处理工作，同时你可以继续与它交流。如果你连续提出三个需求，三个智能体就会同时开始工作。每个任务都在其专属的会话中运行，并在侧边栏中列在你的当前会话下方。My OpenChatly 会立即告诉你它选择了哪个智能体，并在该智能体完成任务后告知结果，同时提供指向该工作的链接。点击 **Worker complete（工作完成）** 或 **Worker failed（工作失败）** 卡片即可打开相应的会话。

要引导工作进程，只需告诉 My OpenChatly 你的需求：

| 你的指令 | 系统响应 |
| --- | --- |
| "How's the post writer doing?"（文章撰写智能体进展如何？） | My OpenChatly 会立即告诉你当前状态，无需等待任务结束。 |
| "Tell the post writer to keep it under 500 words."（告诉文章撰写智能体控制在500字以内。） | 该智能体会收到这条消息。 |
| "Stop the research."（停止调研。） | 该智能体会停止工作。 |
| "Ask the post writer to add a summary too."（让文章撰写智能体也加个摘要。） | 同一个智能体会在其专属会话中继续工作，并保留它已掌握的所有信息。My OpenChatly 仅在处理全新独立工作时才会启动新智能体。 |
| "Tell the session working on the pricing page that the copy is approved."（告诉正在处理定价页面的会话，文案已批准。） | 该会话会收到此消息。你可以输入 `@` 来按名称选择特定的会话。 |
| "Tell me when it's done."（完成后告诉我。） | 当该会话结束时，你会收到一条通知。 |

当工作等待他人处理时（例如等待回复智能体发送的邮件），智能体会自行设置定期检查（check-ins），My OpenChatly 会向你汇报每次检查的发现。请参阅 [Loops（循环）](#reminders)。

**来自其他会话的消息。** 来自其他会话的消息会显示为一行提示，例如 **Message from @reviewer（来自 @reviewer 的消息）**。My OpenChatly 绝不会擅自替你批准任何事项。如果你想亲自决定每条消息的处理方式，可以将该会话设置为 **Hold messages（挂起消息）**：此时每条消息都会等待 5 分钟，直到你点击 **Approve（批准）** 或 **Deny（拒绝）**。如果选择 **Refuse messages（拒绝所有消息）**，则会拒收所有此类消息。

**工作流（Workflows）。** 对于大型任务（例如检查网站的每个页面），My OpenChatly 会提出一个工作流建议：这是一个能同时运行多个智能体的计划。你需要先批准该计划。工作流卡片会显示每个智能体的进度，并提供 **Pause（暂停）**、**Restart（重启）**、**Stop（停止）** 和 **Save（保存）** 按钮。如需请求工作流，请在消息中输入 `ultracode`。单个工作流最多可同时运行 50 个智能体，同一时刻最多并行 8 个，最长运行时间为 2 小时。包含超过 25 个智能体的工作流会显示 **Large workflow（大型工作流）** 标签。

**单次任务的辅助智能体（Helpers）。** 你可以要求创建一个拥有独立指令、更快/更强模型或只读权限的辅助智能体，例如：“用一个快速模型阅读这 40 页内容，然后用最强的模型来写摘要。” My OpenChatly 会仅为当前任务配置该辅助智能体，不会修改任何现有智能体。而添加新工具或扩展属于对项目的更改：智能体会提出建议，在你批准后才会生效。

**智能体团队（Agent teams）。** 团队是一组共享待办事项列表并能相互沟通的智能体。你可以这样要求：“启动一个三人团队：一个负责调研，一个负责撰写，一个负责核实事实。” 团队负责人会将工作拆分为具体事项，每个团队成员领取下一个空闲事项，最后由负责人将结果汇总给你。每个团队成员都会运行你现有的一个智能体，且其角色仅在当前会话中生效：不会创建或修改任何智能体，团队也不会被保存。智能体团队是一项实验性功能，默认处于关闭状态。你可以在 **Project admin（项目管理员）** → **Feature flags（功能开关）** → **Agent teams（智能体团队）** 中将其开启。

**看板视图（The board view）。** 会话列表的看板视图会按状态对所有会话进行分组：working（运行中）、needs you（等待处理）、idle（空闲）、done（已完成）、failed（失败）和 stopped（已停止）。处于“等待处理”状态的会话会显示它正在等待什么：是一个问题还是一个审批请求。

### 创建你自己的智能体

1. **打开智能体列表**

    在侧边栏中选择 **Customize（自定义）**，然后点击 **Agents（智能体）** → **New（新建）**。

2. **选择创建方式**

    选择 **Create in chat（在对话中创建）** 会开启一个会话，由一个智能体协助你编写新智能体：你只需描述工作需求并回答它的提问即可。选择 **Set up manually（手动设置）** 则会直接打开项目文件进行配置。

3. **设置基本信息和模型**

    打开该智能体并编辑其 **Basics（基本信息）** 和 **Model（模型）**。指令（Instructions）规定了智能体要做什么、怎么做，以及绝对不能做什么。

4. **授予访问权限**

    在 **Access（访问权限）** 下，开启该工作所需的资源：**Skills（技能）**、**Connectors（连接器）**、**Secrets（密钥）**、**Apps（应用）** 和 **OpenChatly permissions（OpenChatly 权限）**。如果智能体需要处理项目中的文件，还需在其 **Workspace（工作区）** 页面开启 **Project repository access（项目仓库访问权限）**。

5. **分配给相关人员**

    在该智能体的 **People（人员）** 页面，选择哪些人可以运行它。

对智能体的更改会在其落地到项目中时生效。新开启的会话将使用该智能体，而正在运行的会话也会自动应用更新后的智能体。

### 智能体能访问什么

| 访问项 | 允许的操作 |
| --- | --- |
| **Connectors（连接器）** | 调用你所连接的应用，例如你的服务台（help desk）或 CRM。 |
| **Secrets（密钥）** | 加密的凭证，例如 API 密钥。 |
| **Skills（技能）** | 该智能体可以加载的操作规程。 |
| **Apps（应用）** | 项目中访问受限或私有的应用。 |
| **OpenChatly permissions（OpenChatly 权限）** | 在 OpenChatly 本身中执行的操作，例如开启会话或合并变更。 |
| **Project repository access（项目仓库访问权限）** | 在会话计算机的 `/workspace` 目录下、位于该会话专属分支上的项目仓库副本。`worker` 拥有此项权限。在 `kortix.yaml` 中对应 `workspace.project_repository: true`。 |
| **Tools（工具）** | 内置能力，例如网页搜索、图片搜索、图片生成、读取网页以及项目记忆。请参阅 [OpenChatly 工具](/docs/zh/developers#openchatly-工具)。 |

**智能体以它自己的身份行动，而不是以你的身份。** OpenChatly 在每个项目中为每个智能体赋予独立的身份，因此无论由谁来运行，该智能体所做的都是同一件事。你的角色不会额外赋予它任何权限。

**你的个人账户始终保持私有。** 个人连接器账户、个人密钥或你自己的计算机，只有在会话是私有的、并且代表你运行时，才会被该会话访问到。共享会话或按计划运行的任务都不会访问到这些内容。

要准确查看某个智能体能做什么，打开它的 **OpenChatly permissions（OpenChatly 权限）** 页面：**What this agent can do（该智能体能做什么）** 面板会将其列出。

### 智能体如何在风险操作前先征求同意

由你决定智能体可以在无人参与的情况下做什么。它的每个工具都遵循以下三条规则之一：

| 规则 | 发生的情况 |
| --- | --- |
| Allow（允许） | 该工具直接运行。 |
| Ask（询问） | 智能体会等待，直到有人批准或拒绝该操作。 |
| Deny（拒绝） | 智能体无法使用该工具。 |

连接器同样可以把操作挂起以等待审批。连接器规则可以把某个操作（例如发送电子邮件）挂起，直到有人批准它。被挂起的操作会出现在会话标题栏的 **Approvals（审批）** 下方以及 **Review（审核）** 页面上，由你在其中逐项批准或拒绝。

对项目本身的更改同样需要经过审核。当智能体修改了某项技能、它的记忆或另一个智能体时，它会发起一个变更请求（change request）。有人在 **Review（审核）** 页面上审查它，并选择 **Ship it（合并发布）** 将其合并。

> **警告**
>
> `worker` 拥有所有 OpenChatly 权限，因此它被允许合并自己发起的变更请求。它的固定指令（standing instructions）要求它只在你明确要求时才进行合并。如果你希望每次都由人来完成合并，请从该智能体的 **OpenChatly permissions（OpenChatly 权限）** 中移除它的合并权限。

### 当 kortix.yaml 出现问题时

`kortix.yaml` 中可能存在错误，例如拼写错误的键或未注册的技能。此时项目会显示一条横幅（banner），列出这些问题。选择 **Fix with My OpenChatly（用 My OpenChatly 修复）**：My OpenChatly 会修复该文件，并为你发起一个供你审阅的变更请求。如果 My OpenChatly 处于关闭状态，该按钮会显示为 **Fix in a new session（在新会话中修复）**。每个会话的智能体也会收到这份问题清单，因此你可以让任意智能体来修复它。

在文件存在错误期间，项目会继续运行。OpenChatly 只会关闭出问题的部分（例如某一个智能体或某一个触发器），绝不会赋予某个智能体超出该文件所授权限的访问权。当错误出现在整个项目所依赖的部分时，只有 My OpenChatly 会继续运行，直到该文件被修复。相关规则见 [kortix.yaml 参考](/docs/zh/developers#当-kortixyaml-出现问题时)。

## 技能（Skills）

<video src="/media/guide/skills.mp4" aria-label="Skills in OpenChatly: the skill list and one skill opened" controls muted playsInline preload="metadata" style={{ width: '100%', borderRadius: '8px', border: '1px solid var(--border)' }} />

技能是一个 Markdown 文件，它逐步地告诉智能体如何做好某一项任务。技能承载着贵公司做事的方法，因此智能体每次都会以同样的方式完成某项任务。只有当任务与某项技能的描述相匹配时，智能体才会加载该技能。

### 技能是什么

- **一份存放于你项目中的简短文档。** 它包含名称、描述和具体步骤。参考文件（例如模板或检查清单）可以存放在它旁边。
- **按需加载。** 智能体会阅读每项技能的描述，并自行决定何时加载该技能。请把描述写成"何时使用本技能"，而不仅仅是"本技能是什么"。
- **可共享。** 一项技能可以服务于多个智能体。由你决定哪些智能体可以加载它。
- **有版本记录。** 技能是存放于项目 git 仓库中的文件，因此每一次改动都会被记录下来，并注明是谁做出的改动。

### 内置技能

一个新项目会自带一系列现成的技能，涵盖文档、电子表格、PDF、演示文稿、设计、网站、Web 应用、发布、网页浏览，以及将文档转换为 Markdown。

OpenChatly 还会为每个项目添加系统技能（system skills）。它们教会智能体如何使用 OpenChatly 本身，例如其记忆、连接器和应用。你无法更改或删除它们。与任何其他技能一样，智能体只有在拥有相应访问权限时才会加载它们。

更多技能可在 [应用市场](https://openchatly.com/marketplace) 中找到。安装某项技能会开启一个会话，把该技能添加到你的项目中，并为你发起一个供你审阅的变更请求。

### 添加技能

1. **打开“技能”页面**

    在侧边栏中选择 **Customize（自定义）**，然后点击 **Skills（技能）** → **New（新建）**。

2. **选择编写方式**

    选择 **Create in chat（在对话中创建）** 会开启一个会话，由一个智能体协助你编写该技能：你只需描述这项任务以及你们团队的具体做法即可。选择 **Create with a form（通过表单创建）** 则允许你自行编写。

3. **授予智能体访问权限**

    `worker` 智能体默认可以加载所有技能。对于其他智能体，请打开 **Customize（自定义）** → **Agents（智能体）** → 选择目标智能体 → **Skills（技能）**，然后开启该新技能的开关。

4. **进行测试**

    开启一个会话并提出该任务。当任务与技能的描述相匹配时，智能体就会加载该技能。

如需移除某项技能，请在 **Customize（自定义）** → **Skills（技能）** 下打开该技能卡片，然后选择 **Remove（移除）**。

### 智能体自主优化技能

智能体可以提出对某项技能的修改建议，但最终是否落地由人工决定。

1. **智能体编辑技能**

    智能体会在其专属会话中编辑该技能。此时，该修改尚未影响其他人。

2. **发起变更请求**

    变更请求会准确显示该技能中具体修改了哪些行。

3. **人工审核**

    该变更会出现在 **Review（审核）** 页面上。你可以选择 **Ship it（合并发布）** 将其合并，或者要求进一步修改。你的备注会反馈给提出该建议的智能体。

4. **所有智能体使用新版本**

    合并完成后，新开启的会话将使用优化后的技能，而正在运行的会话也会自动应用更新。

你还可以添加一个反思智能体（reflection agent）：通过定时任务运行它，来审查近期的会话并优化技能、指令、工具和记忆。所有的优化都会汇总在一个变更请求中，且它永远不会自行合并。新项目默认不包含此智能体。系统技能 `kortix-harness-refinement` 详细介绍了它的工作原理。

## 应用（Apps）

<video src="/media/guide/apps.mp4" aria-label="Apps in OpenChatly: the Apps page and adding an App" controls muted playsInline preload="metadata" style={{ width: '100%', borderRadius: '8px', border: '1px solid var(--border)' }} />

应用（App）是你的项目托管在 OpenChatly 上的网站、内部工具或后端服务。智能体会在会话中完成它的构建和部署。每个应用都有一个固定的 URL、一个访问权限设置，以及带版本号的发布记录。OpenChatly 会在你的应用运行前自动完成用户的身份验证，因此私有应用无需自行编写登录代码。

### 工作原理

项目侧边栏中的 **Apps（应用）** 页面列出了你可以打开的所有应用，并展示它们的运行状态、预览图和访问设置。点击某个应用即可查看其发布版本。

你可以通过会话、命令行或代码来创建和部署应用。大多数情况下，用户只需向智能体描述应用的需求，智能体就会在其 [云计算机](#计算机computers) 上完成构建并部署。

#### 谁可以打开应用

| 访问权限 | 可以打开该应用的人员 |
| --- | --- |
| Private（私有，默认） | 仅限创建者本人 |
| Project（项目） | 所有拥有项目读取权限的人 |
| Restricted（受限） | 你指定的成员和群组 |
| Password（密码） | 任何知道密码的人 |
| Public（公开） | 任何人，无需登录 |

项目管理员（Project managers）、账户所有者（account owners）和账户管理员（account admins）可以打开项目中的每一个应用，因此即使创建者离开，私有应用依然可以被管理。当你更改了应用的访问权限时，所有人都需要重新登录该应用。

#### 始终运行 或 按需运行

运行服务器的应用（App）有两种运行模式：

- **始终运行（Always on）：** 全天候运行，如果停止，OpenChatly 会自动将其重启。适用于需要实时更新、后台任务和数据库的场景。
- **按需运行（On demand）：** 在一段静默期后会自动停止，直到下一个访问者或触发器将其唤醒。处于停止状态的应用不消耗计算资源。

新建的应用默认处于“始终运行”模式。静态应用没有服务器，因此不适用上述两种模式。

#### 发布版本与回滚

每次部署都会创建一个带版本号的新发布，且已发布的版本内容不可更改。如果新版本未通过检查，访问者将继续使用上一个版本。回滚操作会基于旧版本创建一个新发布，它只会更改代码和设置，绝不会更改应用的已存储数据。此外，OpenChatly 还会每天对应用的已存储数据进行快照备份。

### 设置应用

1. **向智能体描述应用需求**

    开启一个会话并说明你的需求：谁在使用它、它展示什么内容，以及它需要保留什么数据。

2. **让智能体构建并部署应用**

    智能体会在其云计算机上构建应用并完成部署。新创建的应用默认为私有：只有你可以打开它。

3. **打开并检查应用**

    在项目侧边栏的 **Apps（应用）** 中打开该应用，请确保你使用的是已登录 OpenChatly 的浏览器。

4. **分享应用**

    设置谁可以打开该应用（例如整个项目或某个群组），然后将链接发送给他们。

托管在其他地方的工具也可以列在应用页面上。你可以让智能体为你添加，或者由开发者通过命令行（CLI）添加。请参阅 [Show an App hosted elsewhere（显示托管在其他地方的应用）](/docs/zh/developers#展示托管在其他地方的应用show-an-app-hosted-elsewhere)。

## 云盘（Drive）

<video src="/media/guide/drive.mp4" aria-label="Drive in OpenChatly: My files and the New menu" controls muted playsInline preload="metadata" style={{ width: '100%', borderRadius: '8px', border: '1px solid var(--border)' }} />

云盘用于保存在会话结束后依然存在的文件。每个人都有自己专属的文件夹 **My files（我的文件）**。当智能体为你生成文件时，它会将其保存在这里；智能体关于你的记忆也存放在这里。你可以在侧边栏打开 **Drive（云盘）** 来浏览、上传和编辑你的文件。

### 文件夹

- **My files（我的文件）：** 你的专属文件夹，仅你可见。在你开启的私有会话中，它会作为 `/drives/me` 和 `~/Desktop` 打开，这样智能体就能读取你的上下文，并将工作成果保存在你能找到的地方。
- **Shared Drives（共享云盘）：** 开启共享云盘功能后，项目管理员可以创建一个云盘并向其中添加智能体。这些智能体的所有会话都会打开该云盘，且任何有权使用这些智能体的人都可以从云盘中打开它。管理员还可以看到 **All files（所有文件）**，即完整的文件夹树。共享云盘是一项实验性功能，默认处于关闭状态。你可以在 **Project admin（项目管理员）** → **Feature flags（功能开关）** → **Shared drives（共享云盘）** 中将其开启。
- **会话打开的内容：** 你开启的私有会话会打开 **My files（我的文件）**。在私有频道帖子中开启的会话也会打开该频道的文件夹。如果开启了共享云盘，会话还会打开其所属智能体的云盘。会话中的 `/drives/README.md` 文件会列出当前已打开的内容。
- **Search（搜索）：** `kortix search <words>` 命令可以根据文件名或文本内容，在你有权访问的所有文件夹（包括会话未打开的文件夹）中查找文件。在会话中使用时，它仅搜索该会话有权使用的文件夹。
- **Large files（大文件）：** 云盘支持任意大小的文件，上限为项目的存储配额：你可以通过网页应用、使用 `kortix drive put <local> <path>` 命令或通过 API 进行上传。对于超过 64 MiB 的文件，系统会以 1 MiB 的块进行上传，且仅发送云盘中尚未存在的块。当最后一个块传输完成后，该文件才会显示。

每个项目都有一个云盘。其文件存储在运行会话的 Platinum 环境中。

### 记忆（Memory）

记忆是存放在云盘中的 Markdown 文件：记录了关于你、你的工作、你的惯例和决策的事实。记忆文件夹的访问权限与其所在文件夹的权限相同。

| 记忆文件夹 | 读取权限 |
| --- | --- |
| **My files（我的文件）** 中的 `Memory` | 仅限你和你的会话。每个智能体都会在专属的子文件夹中保存关于你的笔记。 |
| 频道文件夹中的 `Memory` | 频道的成员。频道是一项实验性功能，默认处于关闭状态。 |

智能体通过其会话打开的文件夹来读写记忆文件。OpenChatly 不会将记忆内容直接粘贴到每个提示词中：而是通过一个系统技能，指示每个智能体在任务开始时主动读取记忆。

**My OpenChatly 会记住你。** 你可以告诉 My OpenChatly “记住我喜欢简短的回复”，或者纠正它的行为方式，它会为此保存一个简短的页面。如果你说“忘掉我正在负责发布工作”，它就会删除该页面。它会用一行文字进行确认，例如“已记录：你喜欢简短的回复”。My OpenChatly 会在该项目的每个会话开始时读取这些页面。它们位于 **My files（我的文件）** 下的 `Memory/mykortix` 目录中，且仅你可见。你可以询问“你对我有什么了解？”来查看这些内容。

项目仓库也可以保存记忆：一个以 `MEMORY.md` 作为索引的 `memory/` 文件夹，用于记录项目的背景及运作方式。智能体使用其文件工具来编辑它，且每次编辑都会通过变更请求落地。

> **警告**
>
> 绝不要在记忆中存放密码、API 密钥或个人数据。请将凭证作为项目密钥（project secrets）进行存储。

### 你的文件还存储在哪里

除了云盘（Drive），还有两个地方会保存会话的文件：

| 存储位置 | 保存的内容 |
| --- | --- |
| 你的项目仓库（Repository） | 智能体已提交（committed）的内容。你可以通过 **Customize（自定义）** → **Repo（仓库）** 打开它。 |
| 会话附件（Session attachments） | 用户附加的文件，以及智能体向你展示过的文件副本。OpenChatly 会在每一轮对话结束时保存它们，因此即使会话处于休眠状态，你也可以随时下载。 |

在会话专属的计算机上，只有 `/workspace` 和 `/drives` 目录会被保留。请参阅 [What is kept（保留的内容）](#保留的内容)。

当你删除一个会话时，OpenChatly 会将其消息和存储的文件保留 30 天，以便你可以随时恢复。

## 交付物（Artifacts）

交付物是用户和智能体通过云盘共享的文档或网页：例如报告、计划、演示文稿或仪表盘。它拥有一个专属链接、版本历史记录和独立的分享设置。用户可以阅读文档并直接进行编辑。智能体负责发布交付物、阅读反馈并保存新版本。

交付物目前处于测试阶段（Beta），默认处于开启状态。

### 交付物的概念

- **文档（Doc）：** 云盘中包含 `index.md` 的文件夹。它在编辑器中打开。停止输入 2 秒后会自动保存，每次保存都会生成一个版本。**Export as PDF（导出为 PDF）** 会将其打印出来。
- **网页（Page）：** 包含 `index.html` 及其相关文件（样式、脚本、图片）的文件夹。它在沙盒环境中打开：其脚本可以运行，但无法访问 OpenChatly 或你的账户。
- **存储位置：** 新建的交付物是 **My files（我的文件）** 下 `Artifacts` 目录中的一个文件夹。智能体也可以分享云盘中已有的文件夹。**Stop sharing（停止分享）** 会移除该交付物及其链接，但其文件仍会保留在云盘中。
- **可见性：** 分为 **Private（私有）**（仅限你和你添加的人）、**Project（项目）**（项目中的所有人）或 **Public（公开）**（任何拥有链接的人，无需登录）。创建者和项目管理员可以通过 **Share（分享）** 更改此设置。要编辑交付物，你需要拥有其在云盘中对应文件夹的写入权限。
- **版本：** 标题栏中的时钟图标 **History（历史记录）** 会按天列出保存的版本。间隔不到 5 分钟的保存会显示在同一行。打开某个版本即可阅读。**Restore（恢复）** 会将其作为新版本写回。
- **Ask AI（询问 AI）：** 标题栏中的此按钮会在交付物旁边打开一个聊天窗口。你的第一条消息会开启一个专门编辑该交付物的会话，你可以实时看到修改过程。

在侧边栏打开 **Artifacts（交付物）** 即可查看你可以访问的所有交付物。你可以按 **All（全部）**、**Yours（我的）**、**Shared with you（与我共享）** 或 **Pinned（已置顶）** 进行筛选，通过标题和描述进行搜索，或选择 **New doc（新建文档）** 来创建一个文档。

### 评论（Comments）

用户和智能体可以在交付物的评论线程（threads）中进行讨论，评论会显示在相关段落旁边。交付物评论是一项实验性功能，默认处于关闭状态。你可以在 **Project admin（项目管理员）** → **Feature flags（功能开关）** → **Artifact comments（交付物评论）** 中将其开启。该功能需要依赖交付物使用。

| 评论对象 | 操作方法 |
| --- | --- |
| 文档中的某段文字 | 选中文字，然后点击 **Comment（评论）**，或在 Mac 上按 `Cmd+Option+M`，在 Windows/Linux 上按 `Ctrl+Alt+M`。 |
| 网页上的文本 | 选中文本，然后点击 **Comment（评论）** 标签，或按下相同的快捷键。 |
| 网页上的某个位置或区域 | 在标题栏选择 **Pin a comment（钉选评论）**，然后点击某个元素或拖拽框选一个区域。 |
| 网页上的绘图 | 在标题栏选择 **Draw feedback（绘制反馈）**，使用画笔、箭头或矩形工具，以黑色、红色或蓝色进行绘制。评论会附带你绘制区域的截图。 |
| 整个交付物 | 在评论面板顶部选择 **New comment（新建评论）**（**+** 图标）。 |

选中的段落最多可包含 500 个字符。

- **评论面板：** 标题栏中的 **Show comments（显示评论）** 会打开面板并显示当前打开的线程数量。包含未关闭线程的交付物在打开时会自动显示该面板，且在 **Artifacts（交付物）** 页面的卡片上也会显示未关闭线程的数量。面板按文档顺序列出线程。你可以按 **Open（打开）**、**Resolved（已解决）** 或 **All（全部）** 进行筛选。点击线程中的引用文字可显示其对应的段落；点击交付物中的高亮文字可打开对应的线程。
- **回复与解决：** 每个线程都有一个回复框。**Resolve（解决）** 会关闭线程，随后的提示中包含 **Undo（撤销）** 按钮。已解决的线程会显示是谁将其解决的。**Reopen（重新打开）** 可再次开启该线程。
- **编辑与删除：** 你只能编辑和删除自己的评论，项目管理员可以删除任何人的评论。被删除的评论会显示为 **Comment deleted（评论已删除）**。
- **提及与通知：** 输入 `@` 可以提及某个人或智能体。新建线程会通知交付物的创建者。回复会通知线程中的所有参与者，被提及的人也会收到通知。OpenChatly 仅通知有权打开该交付物的人，且绝不会通知发表评论的人自己。
- **活动记录（Activity）：** **Activity（活动）** 标签页会按时间倒序列出所有的发布、保存、重命名、分享更改、恢复和线程事件，并注明操作者：用户、智能体或 **System（系统）**。
- **文本变更：** 当线程下方的文本被修改时，高亮标记会跟随编辑后的文本。如果 OpenChatly 找不到原文本，该线程会移至 **Outdated（已过期）** 并保留其原始引用。

### 向智能体发送反馈

- **提及智能体：** 输入 `@`，选择一个智能体并写下你的请求，例如“缩短这段文字”。智能体会编辑交付物，用一句话回复修改内容，并解决该线程。如果需要人工介入，它会以提问的方式回复。
- **回复遵循线程：** 智能体收到的线程中的回复，也会发送给该智能体。
- **发送未关闭的线程：** 在评论面板底部的 **Send N open threads to（将 N 个未关闭的线程发送给）**，会在一次操作中把由用户发起且尚未被智能体接收的所有未关闭线程移交给智能体。单次发送最多支持 100 个线程。接收反馈的智能体默认是创建该交付物的会话所属的智能体，否则为项目的默认智能体。你可以通过 **Choose agent（选择智能体）** 指定其他智能体。
- **会话归属：** 如果该智能体的某个会话创建了该交付物，且你有权向该会话写入，则反馈会延续该会话。否则，会启动该智能体的一个新会话。
- **绘图反馈：** 如果智能体使用的是支持图像读取的模型，它会收到每张绘图的截图。其他模型则会收到文本段落及指向截图的链接。
- **状态：** 每个线程都会显示反馈的当前状态：**Sending to agent…（正在发送给智能体…）**、**Sent to agent（已发送给智能体）**（附带 **Open session / 打开会话**）、**Waiting for a person（等待人工处理）**，或 **Not delivered（未送达）**（附带 **Send again to / 重新发送给** 该智能体）。
- **防止死循环：** 用户之间的评论不会触发智能体的操作。如果智能体在一个线程中连续写了 6 条评论，第 6 条将不会发送给任何智能体，线程会显示 **Waiting for a person（等待人工处理）**，直到有人回复为止。

智能体也可以通过命令行使用相同的线程功能。完整列表请参阅 [Artifact commands（交付物命令）](/docs/zh/developers#产物命令artifact-commands)。

| 命令 | 功能说明 |
| --- | --- |
| `kortix artifacts publish <file\|dir>` | 上传并分享文档或网页。 |
| `kortix artifacts comments <id>` | 读取未关闭的线程。加上 `--all` 参数可包含已解决的线程。 |
| `kortix artifacts comment <id> "text" --quote "text"` | 在最多 500 个字符的精确段落上开启一个线程。如果不加 `--quote`，则针对整个交付物开启线程。 |
| `kortix artifacts reply <thread_id> "text"` | 在某个线程中进行回复。 |
| `kortix artifacts resolve <thread_id>`, `reopen <thread_id>` | 关闭或重新打开某个线程。 |
| `kortix artifacts activity <id>` | 读取活动记录流。 |

> **警告**
>
> 评论属于项目数据。**Stop sharing（停止分享）** 会删除该交付物的评论及其截图。删除项目则会删除所有的评论截图。网页永远不会接收评论文本或用户名，它只会接收其钉选标记的编号。

## 连接器（Connectors）

<video src="/media/guide/connectors.mp4" aria-label="Connectors in OpenChatly: the catalog and the approval rules" controls muted playsInline preload="metadata" style={{ width: '100%', borderRadius: '8px', border: '1px solid var(--border)' }} />

连接器赋予智能体访问外部应用的权限，例如 Gmail、Linear、Notion 或 Stripe。OpenChatly 负责存储登录凭证、为每次调用选择合适的账户、应用你设定的规则，并记录每一次调用。登录凭证绝不会进入智能体的运行计算机中。

### 工作原理

一次连接器调用涉及三个要素：

| 要素 | 决定内容 | 示例 |
| --- | --- | --- |
| **Connector（连接器）** | OpenChatly 如何连接到该应用。 | 通过其专属服务器连接 Linear |
| **Account（账户）** | 该调用使用谁的登录凭证。 | 团队公共收件箱，或你自己的收件箱 |
| **Rules（规则）** | 智能体在该应用中可以做什么。 | 客服智能体仅拥有“只读”权限 |

只有在被明确授予访问权限后，智能体才能使用某个连接器。同时，该人员或智能体还必须被允许使用相应的账户。

#### 谁可以使用某个账户

- **仅限你本人（Only you）：** 私有账户。只有你可以使用，且仅限于你自己的私有会话中。这是默认设置。
- **项目中的所有人（Everyone in the project）：** 共享账户。项目中的每个成员和每个被授权的智能体都可以使用。
- **特定人员、群组或智能体（Specific people, groups, or agents）：** 为你指定的受众提供的共享账户。

触发器（Triggers）绝不会使用私有账户，它们需要使用与整个项目共享的账户。请参阅 [Triggers（触发器）](#触发器triggers)。

### 设置连接器

1. **查找应用**

    打开 **Customize（自定义）** → **Connectors（连接器）**。在 **All（全部）** 标签页下找到目标应用。默认开启的 **One-click only（仅限一键连接）** 会列出你只需登录即可连接的应用。

2. **安装**

    选择 **Install（安装）** 并选择 **Who can use it（谁可以使用）**。默认选中 **Only you（仅限你本人）**。

3. **登录**

    登录该应用，或输入其 API 密钥。完成后，你将返回连接器页面，此时其工具已加载。

4. **检查规则**

    打开连接器的 **Tools（工具）** 标签页。这里会显示每个操作的状态：是直接运行、需要审批，还是被阻止。

即使应用不在目录中，依然可以进行连接。选择 **New（新建）** → **MCP server（MCP 服务器）** 并粘贴其地址；或者选择 **New（新建）** → **Add a custom connector（添加自定义连接器）** 以接入其他类型的 API。选择 **New（新建）** → **Create in chat（在对话中创建）**，可以让智能体协助你完成设置，并为你发起一个供审阅的变更请求。

当智能体需要一个尚未有人连接的应用时，会话中会显示一个 **Connect（连接）** 按钮。点击它会打开相同的登录流程，并默认创建一个私有账户。

目录中列出的是当前实例实际能够连接的应用。平台管理员可以在 `/admin/connectors` 路径下隐藏那些从你的网络无法访问其登录页面的供应商；请参阅 [Hiding connector apps users cannot connect（隐藏用户无法连接的应用）](/docs/zh/developers#隐藏用户无法连接的连接器应用)。无论是否隐藏，已安装的连接器都会继续正常工作。

### 允许、询问、阻止（Allow, Ask, Block）

每个操作都遵循以下三条规则之一：

- **Allow（允许）：** 立即执行该操作。
- **Ask（询问）：** 挂起该操作，直到有人批准。
- **Block（阻止）：** 永远不执行该操作。

你也可以将整个连接器标记为敏感（sensitive）。此时，所有没有独立规则的操作（包括读取操作）都需要审批。项目也可以采用谨慎的默认策略：读取操作直接运行，而写入或删除操作需等待审批。

#### 审批被挂起的操作

1. **找到它**

    打开 **Review（审核）** → **Needs you（等待处理）**，点击审批链接，或者在 Slack 线程 / Teams 聊天中使用审批卡片。在你的列表中，该会话会显示 **Needs you（等待处理）** 状态。

2. **检查内容**

    页面会显示应用将接收到的内容，同时隐藏私密信息。

3. **做出决定**

    选择 **Approve（批准）** 或 **Deny（拒绝）**，并可附上给智能体的备注。**Approve（批准）** 会让该操作以发起请求的智能体身份执行一次，随后 OpenChatly 会将结果返回给该智能体并恢复其运行。

- 一次审批仅针对一个确切的操作。如果任何细节发生变化，该操作需要重新审批。
- 已批准的操作仅执行一次，智能体不会重复发送。OpenChatly 在执行操作时会重新检查项目规则，因此 **Block（阻止）** 规则依然具有最高优先级。
- 由项目管理员或发起该会话的人员负责审批。
- 除非项目另有设置，否则如果在 24 小时内无人处理，被挂起的操作将过期。
- 没有“批准此会话中的所有操作”选项。如果某个操作必须在无人值守的情况下运行，需要为其设置 **Allow（允许）** 规则。
- 使用项目令牌（project token）登录的脚本也会受到相同处理：**Approve（批准）** 会执行其调用，脚本随后读取结果。而使用其他令牌的脚本，必须在审批后的 15 分钟内重新发送相同的调用。

### 从 Claude、ChatGPT 或 Cursor 中使用 OpenChatly

连接器也支持反向操作：你的 AI 工具可以启动 OpenChatly 会话、读取其结果，并在你的权限范围内通过 OpenChatly 调用你的连接器。请参阅 [Other AI tools (MCP)（其他 AI 工具 (MCP)）](#其他-ai-工具mcp)。

## 触发器（Triggers）

<video src="/media/guide/automations.mp4" aria-label="Triggers in OpenChatly: creating a daily scheduled trigger" controls muted playsInline preload="metadata" style={{ width: '100%', borderRadius: '8px', border: '1px solid var(--border)' }} />

触发器能够在无人值守（无人在键盘前）的情况下启动智能体工作。它由两部分组成：**source（触发源）**，决定何时触发；以及 **target（执行目标）**，决定触发后执行什么操作。

| 触发源（Source） | 触发时机 | 适用场景 |
| --- | --- | --- |
| **Schedule（定时计划）** | 到达指定时间，或经过固定周期（支持 `cron`、`every`、`at`、`in`）。 | 每日报告、每周复盘、定期检查。 |
| **App event（应用事件）** | 你的某个 OpenChatly 应用（App）报告了某事。 | 适用于不符合其他触发源的场景。请参阅 [Apps（应用）](#应用apps)。 |
| **Connector event（连接器事件）** | 已连接的应用中发生了某事。 | 新增工单、新消息、新订单。 |
| **Webhook（网络钩子）** | 其他系统向触发器的地址发送了签名请求。 | 表单工具、支付系统、代码托管平台。 |
| **Change request merged（变更请求已合并）** | 项目的某个变更请求被合并到指定分支或任意分支。 | 生成发布说明、部署后的检查。 |

连接器事件是一项实验性功能，默认处于关闭状态。你可以在 **Project admin（项目管理员）** → **Feature flags（功能开关）** → **Composio event triggers（Composio 事件触发器）** 中将其开启。

| 执行目标（Target） | 触发后的动作 | 调用方式 |
| --- | --- | --- |
| **Agent（智能体）** | 在该智能体专属的云计算机上启动一个全新的会话。 | 触发器（Trigger） |
| **Session（会话）** | 唤醒一个已存在的会话，并保留其完整历史记录。 | 循环（Loop） |

任何触发源都可以与上述任一执行目标搭配使用。若要对 OpenChatly 外部的事件做出反应，当外部系统支持发送 Webhook 时，请使用 Webhook；否则，请使用定时计划进行轮询检查。

触发器存在于以下两个位置之一：

- **在 `kortix.yaml` 中**，位于 `triggers:` 节点下。它通过代码提交（commit）进行更改，因此像代码一样经过审核。**Triggers（触发器）** 页面和 API 会将其标记为 **kortix.yaml**。
- **在运行时创建**，存储在数据库中。由智能体或人员通过单条命令或 API 调用创建，无需代码提交，删除后即消失。每个循环（Loop）都属于此类。**Triggers（触发器）** 页面会将其标记为 **Created at runtime（运行时创建）**。

### 触发器触发后会发生什么

1. OpenChatly 会使用事件的详细信息（例如 Webhook 请求中的字段）填充你的指令。
2. 它会在专属的云计算机上，使用你选择的智能体和模型启动一个新会话。
3. 智能体使用其被授权的连接器完成工作。
4. **Triggers（触发器）** 页面会显示该触发器的上次运行时间和状态，同时该会话会出现在你的列表中。

以下规则确保了这一过程的安全性：

- **应用事件会被标记。** 由应用事件启动的会话在打开时，会显示一行提示，说明该内容是自动生成的，而非人工输入。智能体会将其视为数据，而非指令。
- **仅限共享账户。** 私有连接器账户绝不会为触发器提供服务。请使用与整个项目共享的账户。
- **无人可问。** 如果由触发器启动的会话在等待人工处理，它最多等待 30 分钟，随后便会停止。请设置连接器规则，允许所需的操作直接运行。请参阅 [Connectors（连接器）](#连接器connectors)。
- **谁可以查看运行记录。** 默认情况下，只有管理触发器的人员、账户所有者和管理员可以打开这些会话。你也可以选择 **Selected teammates（选定的队友）** 或 **Whole project（整个项目）**。
- **同时仅运行一次。** 如果上一次运行尚未结束，定时计划会跳过本次运行。

### 设置触发器

1. **打开“触发器”页面**

    打开 **Customize（自定义）** → **Triggers（触发器）**。标签页包括 **All（全部）**、**Schedules（定时计划）**、**Webhooks（网络钩子）**，以及项目使用的其他触发源对应的标签页。运行时创建的触发器列在 **Created at runtime（运行时创建）** 下。

2. **创建触发器**

    选择 **New trigger（新建触发器）**，然后点击 **Set up manually（手动设置）**。在 **When（触发时机）** 下，选择 **Schedule（定时计划）**、**App event（应用事件）**、**Connector event（连接器事件）**、**Webhook（网络钩子）** 或 **Change request merged（变更请求已合并）**。如果项目当前无法使用某个触发源，系统会说明原因并提供修复链接：当没有应用发送事件时指向 **Apps（应用）**，当连接器事件未开启时指向 **Feature flags（功能开关）**。该触发器会被添加到 `kortix.yaml` 中。

3. **编写指令**

    在 **Then（执行操作）** 下，编写智能体应执行的操作，并选择智能体和模型。

4. **创建并测试**

    选择 **Create（创建）**，然后点击 **Run now（立即运行）** 进行一次测试。

Webhook 还需要一个签名密钥，该密钥需作为项目密钥（project secret）存储。**Change request merged（变更请求已合并）** 触发器支持可选的分支参数；如果不指定，则会在每次合并时触发。在 `kortix.yaml` 中的配置如下：

```yaml
triggers:
  - slug: verify-prod
    type: change_request
    filter: { base: main }   # 可选：仅当合并到 main 分支时触发
    agent: worker
    prompt: "Change request #{{ change_request.number }} merged into {{ change_request.base_ref }}. Verify prod."
```

若要在运行时创建触发器，请使用命令行（CLI）：执行 `kortix triggers add "<prompt>"` 命令，并附带触发源标志（如 `--runtime --every 1h`、`--on webhook --secret-env NAME`、`--on cr-merged --cr <id>`）以及执行目标标志（如 `--session <id>`（在会话内时的默认值）或 `--agent <name>`）。

`kortix triggers ls` 命令会列出这两种类型的触发器。而 `pause`（暂停）、`resume`（恢复）、`run`（运行）和 `rm`（删除）命令则需要传入运行时 ID（`trigger.<hex>`）或 `kortix.yaml` 中的 slug（标识符）。

### 循环（Loops）

循环是一种特殊的触发器，它会唤醒创建它的会话，而不是启动一个新会话。它会在稍后向该会话发送一次或重复发送消息，例如：“24小时后，检查供应商是否回复。” 会话被唤醒时会保留其完整的历史记录并继续运行。

会话也可以被 Webhook、事件或已合并的变更请求唤醒：例如执行 `kortix triggers add "…" --on cr-merged --cr <id>`。在终端中，使用 `kortix loop "…" --in 24h` 即可设置一个循环。循环功能默认处于开启状态。它们列在 **Triggers（触发器）** 页面的 **Created at runtime（运行时创建）** 下，且每个会话都会显示唤醒它的触发器。

#### 智能体自主跟进

你无需主动说“稍后再检查”。当智能体执行了某个需要稍后才能得到结果的操作时（例如给供应商发邮件、提交表单、发起变更请求或启动部署），它会在停止前自行设置检查点：

1. **选择信号。** 当结果能够主动通知时（例如变更请求被合并、已连接的收件箱收到新邮件、系统调用了链接、应用报告了变更），事件发生的瞬间会话就会被唤醒。否则，或者作为结果可能永远不会到来的备用方案，它会设置一个循环。
2. **根据等待内容调整循环频率。** 对于人工回复：几小时后（在工作时间内）进行首次检查，然后每天检查几次。对于部署任务：每 10 到 30 分钟检查一次。对于响应缓慢的供应商：每天检查一次。每个循环都有一个结束日期，除非你另行指定，否则默认为 14 天。
3. **用一行文字告知你。** 例如：“我将每 3 小时检查一次回复，直到 11 月 14 日，或者直到收到全部 12 个回复为止。”
4. **每次检查。** 智能体会寻找结果并采取相应行动。你只会听到发生变化的内容。如果在多次检查后都没有新进展，智能体会降低检查频率。
5. **自动清理。** 当工作完成或到达结束日期时，智能体会移除其设置的循环。

**查看或停止循环。** 包含活跃循环的会话会在顶部显示一个时钟图标。点击它可以查看每个循环及其下次运行时间，并可以暂停或移除它。**Triggers（触发器）** 页面会列出每个会话的循环。你也可以直接告诉智能体“停止检查”。

**长任务。** 对于包含多个步骤或跨越数天的任务（例如“寻找打印机、获取 12 份报价并从最优供应商处订购”），智能体会规划各个步骤，将可并行的任务交给其他智能体，为每个等待环节设置检查点，并保留一份简短的状态笔记，以便每次检查点都能从上次停止的地方继续。当工作具有周期性时（例如每季度进行一轮报价），它会提议设置一个触发器或专属智能体，并在执行前先征求你的同意。任务完成后，它会移除循环，停止其启动的其他智能体，并向你发送一份简短的最终报告。

若要全天候监控某些内容（例如状态页面或价格），智能体可以构建一个小型应用（App），按计划对其进行检查，并仅在内容发生变化时报告应用事件。该应用独立于任何会话自行运行，并在变化发生的瞬间唤醒会话。请参阅 [Apps（应用）](#应用apps)。

### 保持对触发器的控制

- **运行限制（Run limits）：** 除非你在 **Options（选项）** → **Run limits（运行限制）** 中设置了其他限制，否则触发器每小时最多启动 60 次运行。你也可以添加每日运行限制。
- **自动暂停（Auto-pause）：** 如果触发器连续 2 小时达到其每小时运行上限，它将自动暂停。在状态显示为 **Paused（已暂停）** 后，直到你手动选择 **Resume（恢复）** 才会继续运行。
- **故障（Failures）：** 失败的运行会显示 **Last run didn’t finish（上次运行未完成）**。当触发器的运行开始频繁失败时，账户所有者的手机会收到一次通知。
- **暂停所有触发器（Pause everything）：** 在 **Account settings（账户设置）** → **Settings（设置）** → **Triggers（触发器）** 中选择 **Pause all triggers（暂停所有触发器）**，会停止该账户下所有项目中的定时计划、Webhook、事件和循环。

## 计算机（Computers）

<video src="/media/guide/computers.mp4" aria-label="Computers in OpenChatly: connecting your own computer" controls muted playsInline preload="metadata" style={{ width: '100%', borderRadius: '8px', border: '1px solid var(--border)' }} />

每个会话都在其专属的隔离云计算机上运行，该计算机预装了项目文件、终端、浏览器、Python、Node.js 以及文档工具。对于需要本地环境的任务，你也可以连接自己的计算机。你的计算机拥有自主决定权，可以控制智能体在其上能执行哪些操作。

### 云计算机的工作原理

1. **你启动一个会话**

    OpenChatly 会为会话分配一个专属的项目分支，并为其启动一台云计算机。拥有 **Project repository access（项目仓库访问权限）** 的智能体（如 `worker`）会在 `/workspace` 目录下获得一份仓库副本。

2. **智能体在其计算机上工作**

    智能体会读取你的项目、运行命令、浏览网页并编写文件。它会将工作成果保存到该会话的专属分支上。

3. **人工审批变更**

    当智能体对项目进行修改时，它会发起一个变更请求（change request）。由人工进行审核并将其合并。

4. **空闲时计算机进入休眠**

    在最后一次对话交互约 15 到 20 分钟后，OpenChatly 会停止该计算机。它会保留 `/workspace` 目录、分支以及会话的消息记录。新的消息或预览请求会将其唤醒。

处于休眠状态的计算机不消耗计算资源。只要 `/workspace` 中的文件被保留，它们就会计入 [存储（storage）](#积分消耗说明) 费用。

#### 保留的内容

- `/workspace`：在会话的整个生命周期内，保存该会话的文件。
- `/drives`：保存你的云盘（Drive）文件，这些文件跨会话共享，且会一直保留，直到你将其删除。请参阅 [Drive（云盘）](#云盘drive)。
- 其他所有内容（如主目录、`/tmp`、已安装的软件包）：在会话唤醒时可能会被清除。请将工具配置在沙盒模板（sandbox template）中。

沙盒模板用于设定云计算机上预装的软件及其资源大小。你可以在 **Project admin（项目管理员）** → **Sandbox templates（沙盒模板）** 中为整个项目统一设置。相关配置键（keys）请参阅 [kortix.yaml reference（kortix.yaml 参考）](/docs/zh/developers#kortixyaml-参考)。

智能体可以协助你完成这项设置。如果你要求它“永久安装某个程序”，它会在当前会话中安装该程序，将其添加到 `kortix.yaml` 的项目沙盒模板中，并为你发起一个变更请求。在你合并该请求且新镜像构建完成后，后续启动的会话都会包含该程序。

#### 资源规格

| 字段 | 默认值 | 范围 |
| --- | --- | --- |
| `cpu` | 2 vCPU | 1 到 32 |
| `memory` | 4 GiB | 1 到 128 GiB |
| `disk` | 15 GiB | 1 到 500 GiB |

如果设定的值超出上限，系统会发出警告，OpenChatly 将自动使用允许的最大值。如果设定的值低于下限，在执行 `kortix validate`、`kortix ship` 或合并变更请求时会被视为错误。OpenChatly 目前没有提供 GPU 计算机：如果配置了 `gpu` 键，系统会发出警告。资源规格是镜像的一部分，因此更改规格将在下一个会话中生效，而正在运行的会话会保持其原有规格。计算资源的计费依据是计算机预留的资源大小，而非实际使用量。请参阅 [Billing（计费）](#计费billing)。

#### 运行环境

OpenChatly 实例的运营方负责决定启用哪些沙盒提供商（sandbox providers），以及新会话默认使用哪一个。每个提供商都有独立的计费标准，计算机将按其实际运行的提供商的费率进行计费。

| 提供商 | 标识符 (Id) | 计算机内支持 Docker | 持久化机器与共享文件夹 | 美国区域 |
| --- | --- | --- | --- | --- |
| Platinum | `platinum` | 是 | 是 | 是（需开启 **US Region** 标志） |
| Alibaba Cloud Agent Sandbox | `alibaba` | 是（仅限 Gen2 模板） | 否 | 否 |
| Daytona | `daytona` | 是 | 否 | 否 |

**警告（Warning）**
>
> **区域与功能：Alibaba（阿里云）。** `alibaba` 运行在由运营方设定的单个阿里云区域（例如 `cn-hangzhou`）；没有美国区域选项。共享文件夹功能需要 Platinum（白金）环境。该环境中的计算机在重启后仍会保留在其所在区域。

**提示（Info）**
>
> **可选：Daytona。** 某些实例会将 Daytona 作为默认提供商之外的可选模式保留。当该模式开启时，其运作方式与其他提供商无异；当该模式关闭时，指定使用该提供商的请求将返回 `400` 错误。

新会话按以下优先级获取其提供商：

1. 创建请求中指定的提供商。如果指定的提供商未开启，将返回 `400` 错误。
2. 项目绑定的提供商（前提是该提供商仍处于开启状态）。
3. 实例在其已启用的提供商之间自动进行负载均衡分配。

若要为项目绑定特定提供商，请打开 **Customize（自定义）** → **Settings（设置）** → **Sandbox templates（沙盒模板）**，在 **Routing（路由）** 下选择一个提供商，或选择自动分配以取消绑定。在终端中，使用 `kortix sandboxes provider <name>` 进行设置，使用 `kortix sandboxes provider --clear` 取消绑定，使用 `kortix sandboxes provider status` 查看最近的切换记录。

#### 预览（Previews）

智能体在其计算机上启动的任何网站或工具都可以从外部访问。会话页面的预览面板提供了常用端口（如 **App preview / 应用预览** 和 **Frontend preview / 前端预览**）以及其他自定义端口。预览功能会要求你先登录 OpenChatly。若要将预览展示给 OpenChatly 外部的人员，需由会话所有者创建一个公开链接。

#### 桌面环境（Desktop）

项目中智能体的会话运行在带有桌面环境的计算机上。点击会话标题栏中的 **Desktop（桌面）** 即可实时观看其操作。My OpenChatly 运行在没有桌面环境的较小计算机上，因此其会话没有 **Desktop（桌面）** 按钮：它会将浏览器操作交由你的智能体会话来处理。

桌面环境中包含一个浏览器，由你和智能体共享。你可以看到智能体访问的每个页面，并且停靠栏（dock）上的浏览器会打开相同的窗口、相同的标签页以及相同的登录状态。默认情况下，控制权在智能体手中。你可以点击 **Take over（接管）** 来亲自点击和输入，例如替智能体登录某个网站，或使用停靠栏上的终端和文件管理器。完成后，点击 **Return control（交还控制权）** 将控制权还给智能体。桌面画面会自动缩放以适应面板大小。

你可以要求智能体在桌面上打开某个应用，例如说“安装 QGIS 并在你的桌面上打开它”，然后在面板中观看其操作。当你说“my desktop（我的桌面）”时，智能体会将文件放入 **My files（我的文件）** 中（你启动的每个会话都会在 `~/Desktop` 路径下打开该文件夹），并将程序放在会话的桌面上。当你的个人计算机连接到 OpenChatly 时，智能体会先询问你指的是哪一个桌面。

如果自定义沙盒模板的基础镜像是 Ubuntu 24.04，则该模板下的会话会获得桌面环境。

#### 住宅 IP 地址（Residential IP address）

某些网站会屏蔽或限制来自数据中心的流量。沙盒模板可以将其网络流量通过住宅 IP 地址发送，而不是使用云计算机本身的地址。你可以在 `kortix.yaml` 的模板上设置 `residential_proxy: true`，或者在 **Project admin（项目管理员）** → **Sandbox templates（沙盒模板）** 中勾选 **Residential IP（住宅 IP）**。使用该模板的会话将自动应用此设置。

```yaml
sandbox:
  default: web
  templates:
    - slug: web
      residential_proxy: true
```

- 通过住宅地址传输的流量将从你的积分（credits）中按 GB 计费。在积分历史记录中，该项显示为 **Residential proxy（住宅代理）**。
- OpenChatly 自身的服务和常用的软件包注册中心会直接连接，这部分流量不会按代理流量计费。
- 代理开启期间 UDP 协议会被阻断，因此 QUIC 和 WebRTC 无法泄露计算机的真实地址。浏览器和工具会自动降级使用 TCP 协议。
- 使用该模板的会话仅在部署环境提供住宅 IP 的地区启动。在其他地区，会话将无法启动：它们绝不会降级使用计算机本身的地址。
- 使用 `{ country: us }` 代替 `true` 可以指定代理地址所在的国家。请参阅 [kortix.yaml reference（kortix.yaml 参考）](/docs/zh/developers#住宅-ipresidential-ip)。

#### 删除会话时

被删除的会话在 30 天内可以恢复。在 **Sessions（会话）** 页面打开 **Recently deleted（最近删除）**，然后选择 **Restore session（恢复会话）**。智能体已保存至其分支或云盘（Drive）的工作成果将会保留，但计算机上未保存的文件将会丢失。

### 连接你的个人计算机

有些工作需要用到你的个人计算机：例如桌面上的某个文件、只有你安装的程序，或屏幕上的某个应用。连接后的计算机就是你的真实计算机，智能体会以你的用户身份在其上执行操作。

连接计算机时，你可以选择最多三种能力：

| 能力 | 智能体可执行的操作 |
| --- | --- |
| **Filesystem（文件系统）** | 读取、写入、列出和删除文件。 |
| **Shell（命令行）** | 运行程序。 |
| **Computer Use（计算机控制）** | 查看屏幕并使用应用程序。 |

你的计算机默认是私有的。只有你可以使用它，且仅限于你在各个项目中开启的私有会话。

#### 设置步骤

1. **发起连接**

    在 OpenChatly 桌面应用中，选择侧边栏的 **Connect this computer（连接此计算机）**。浏览器会打开一个审批页面。

2. **核对代码并命名计算机**

    核对页面上的代码是否与计算机上显示的代码一致。为计算机命名，例如“工作笔记本”。

3. **选择使用者**

    保持 **Only you（仅限你本人）**，或选择 **Also share with（同时共享给）** 当前项目。

4. **选择能力并批准**

    选择 **Filesystem（文件系统）**、**Shell（命令行）**、**Computer Use（计算机控制）** 或它们的组合。在 macOS 上，被提示时请选择 **Allow all（全部允许）**，并授予 OpenChatly 所请求的 macOS 权限。

退出应用后，计算机仍会保持连接状态。

#### 访问权限由计算机端决定

无论项目允许什么，计算机本身会决定是否允许智能体使用它。其 **Access（访问权限）** 设置包含三种模式：

- **Ask each time（每次询问）：** 首次调用时，你的计算机会弹出提示：**Allow for 1 hour（允许 1 小时）**、**Allow for 24 hours（允许 24 小时）** 或 **Deny（拒绝）**。这是桌面应用运行时的默认设置。
- **Always allowed（始终允许）：** 每次调用均直接运行，无需提示。
- **Off（关闭）：** 拒绝所有调用。

只有你本人（在计算机前）才能放宽访问权限。而收紧权限可以在任何地方进行，且会立即生效。你还可以暂停连接，或在接通电源时开启 **Keep this computer awake（保持计算机唤醒）**。

#### 与团队共享

打开 **Customize（自定义）** → **Connectors（连接器）** → **Computers（计算机）** → **Accounts（账户）**，在你的计算机所在行选择 **Share（共享）**。你可以选择特定人员、群组或整个项目。与整个项目共享的计算机也可以为无人值守的触发器（triggers）提供服务。你的 **Access（访问权限）** 设置依然生效：在 **Ask each time（每次询问）** 模式下，每次审批都必须由你亲自授予。

## 模型（Models）

<video src="/media/guide/models.mp4" aria-label="Models in OpenChatly: providers, a custom endpoint and costs" controls muted playsInline preload="metadata" style={{ width: '100%', borderRadius: '8px', border: '1px solid var(--border)' }} />

模型是智能体运行的 AI 引擎。你可以使用 OpenChatly 托管的模型、你自己的提供商密钥（provider keys），或者 ChatGPT / Claude 的订阅服务。你可以为项目设置默认模型、为特定智能体绑定模型，或在单次会话中选择模型。每个模型请求都会经过 OpenChatly LLM 网关（gateway），该网关会应用预算限制、访问规则以及成本报告。

### 工作原理

#### OpenChatly 托管模型

OpenChatly 托管模型无需配置密钥。在模型选择器中，它们列在 **OpenChatly** 分类下，并标明了每个模型的上下文大小和图像支持情况。

- 托管模型需要 Credits（积分）计划或 Enterprise（企业版）。免费版（Free）不可用。
- 托管请求会消耗你账户钱包中的积分。请参阅 [Billing（计费）](#计费billing)。
- 托管模型仅通过承诺“零数据保留（zero data retention）”的推理提供商运行。

#### 使用你自己的密钥和订阅

当请求使用你自己的密钥或订阅运行时，由你的提供商进行计费。包括免费版在内的所有计划都可以使用你自己的密钥或 ChatGPT 订阅。关于使用自有密钥时 OpenChatly 收取的费用，请参阅 [What uses credits（积分消耗说明）](#积分消耗说明)。

提供商密钥属于整个项目共享。

#### 你的 Claude 订阅

关联 Claude Pro 或 Max 计划后，即可运行 Claude 模型：**Claude Opus 5.5**、**Claude Fable 5.1**、**Claude Sonnet 5.5** 和 **Claude Haiku 5.5**（对应标识符为 `claude-agent/opus`、`claude-agent/fable`、`claude-agent/sonnet`、`claude-agent/haiku`）。

- 每次对话交互都会通过 Claude Code（Anthropic 的官方程序）在会话的计算机上运行。Claude Code 会将每个模型请求发送到 OpenChatly LLM 网关，网关会附加该 Claude 账户的登录凭证，并将请求原封不动地转发给 Anthropic。登录凭证绝不会进入会话的计算机中。Claude 请求不消耗任何积分。
- 其他所有功能与其他模型完全一致：包括智能体的工具、权限、提问、子智能体、技能（skills）、pi 扩展，以及会话中显示的消息和工具调用。
- 你可以在同一会话中随时在 Claude 订阅模型与其他模型之间切换。新模型可以查看完整的会话历史记录。
- Claude 账户的运作方式与 ChatGPT 账户类似。在你将其共享给项目或特定成员之前，它仅对你个人私有。会话会优先使用为其选定的账户，其次是你自己的账户，最后才是与项目共享的账户。触发器（Triggers）和频道（channels）仅使用共享账户。OpenChatly 会对登录凭证进行加密存储，且之后绝不再次显示。
- 你的 Claude 计划决定了使用限制。当你达到限制时，当前交互会结束，并提示“Your Claude subscription limit is reached（已达到你的 Claude 订阅限制）”以及限制重置的时间。
- OpenChatly 尚未支持的 Claude Code 功能将不适用：包括计划用量查询（`/usage`）、自动模式（auto mode）以及 Claude Code 自身的技能。

**ChatGPT 订阅还可以生成图像。** 关联 ChatGPT 账户后，`image_gen` 工具可以使用你计划中的 `gpt-image-2` 模型。ChatGPT 设有独立于聊天限制的图像生成上限，达到该上限不会暂停账户的聊天功能。使用 OpenAI、Google、xAI 或 OpenRouter 的密钥同样可以生成图像。OpenChatly 托管模型不支持图像生成。请参阅 [Generate images（生成图像）](/docs/zh/developers#生成图像generate-images)。

#### 会话使用哪个模型

会话将采用以下各项中第一个已设置（非空）的模型：

1. 为该会话、[频道（channel）](/docs/zh/guide#频道channels) 或 [触发器（trigger）](/docs/zh/guide#触发器triggers) 所选定的模型。
2. 为该智能体绑定的模型。
3. 项目默认模型。
4. 账户默认模型（适用于每一个没有自身默认设置的项目）。
5. 平台默认模型。

如果某个默认模型无法运行（例如其密钥已被移除），则会回退到另一个已连接的提供商，再回退到平台默认模型。一个失效的默认设置绝不会导致会话失败。

### 设置步骤

1. **使用默认模型运行**

    在 Credits（积分）计划或 Enterprise（企业版）下，会话会运行在平台默认模型上。在 Free（免费版）下，请先连接一个提供商（见下一步）。

2. **连接你自己的提供商**

    打开 **Customize（自定义）** → **Models（模型）** → **Providers（提供商）** 并粘贴一个密钥。若要使用 ChatGPT 订阅，请在模型选择器中选择 **Use your ChatGPT subscription（使用你的 ChatGPT 订阅）**，然后点击 **Connect ChatGPT（连接 ChatGPT）**。

    若要使用 Claude 订阅，请打开 **Customize（自定义）** → **Models（模型）** → **Providers（提供商）** → **Anthropic**。在 **Claude accounts（Claude 账户）** 下，选择 **Sign in with Claude（使用 Claude 登录）**，为账户命名并选择谁可以使用它。在 claude.com 上批准 OpenChatly，粘贴 Claude 向你显示的代码，然后选择 **Connect Claude（连接 Claude）**。此后 Claude 模型会出现在模型选择器的 **Claude subscription（Claude 订阅）** 分类下。若要在之后共享某个账户，打开其菜单并选择 **Manage access（管理访问权限）**。在终端中，运行 `kortix providers login claude`。使用 `claude setup-token` 生成的令牌同样有效：将其通过管道传给 `kortix providers login claude --token-stdin`。

3. **选择其他模型**

    在输入框的模型选择器中选择一个模型。一个已停止的会话在重新开始时会使用新模型。切换正在运行的会话的模型，会重启该智能体在其计算机上的进程，并终止当前正在进行的对话交互。

4. **设置预算**

    打开 **Customize（自定义）** → **Models（模型）** → **Costs（费用）**。设置按天、按周或按月的限额。选择 **Block（阻止）** 以在达到限额时拒绝新的请求，或选择 **Warn only（仅警告）** 以让其继续运行。

账户所有者、管理员和项目经理会在预算用到 80% 和 100% 时收到邮件通知。

#### 费用与预估用值

**Costs（费用）** 会显示 OpenChatly 实际收取的费用。它还会显示 **LLM estimated usage value (not a bill)（LLM 预估用值，并非账单）**：即同样的请求按提供商的牌价（list price）本应花费的金额。该预估值永远不会被计入实际费用或预算。

- ChatGPT 订阅的请求没有实际收费，但可能有一个预估值。
- 只有对 `gpt-6.1-sol` 的请求（使用 OpenAI 密钥或 ChatGPT 订阅时）才会给出预估值。**Costs（费用）** 会同时统计已计价和未计价的请求。
- 该预估值不包含订阅费本身。

#### 回退模型（Fallback models）

打开 **Customize（自定义）** → **Models（模型）** → **Routing（路由）**，你可以列出最多 8 个模型。当某个模型发生故障时，网关会按顺序尝试这些模型。当回退模型给出响应时，输入框会显示 **Running on（当前运行于）** 及其名称。使用你自己的密钥发出的请求，只有当你的回退列表中明确列出了某个 OpenChatly 计费模型时，才会转移到该模型上。

当请求的模型未知或已退役时，回退列表同样会接管处理。每次网关成功响应时，都会指明你请求的模型（`x-kortix-requested-model`）和实际响应的模型（`x-kortix-model`）。当这两者不一致时，说明是由回退模型作出的响应。

## 目标（Outcomes）

在 OpenChatly 中，目标（Outcome）即是一个 **goal（目标）**：包含你的期望，加上对“完成”的定义。被分配负责该目标的智能体会不断被唤醒，持续处理该目标，直到一个独立的验证器会话确认其已完成为止。

目标（Goals）是一项实验性功能，默认处于关闭状态。你可以在 **Project admin（项目管理员）** → **Feature flags（功能开关）** → **Goals（目标）** 中将其开启。目标功能还需要依赖循环（loops），而循环默认是开启的。

这三个要素协同工作：

| 组成部分 | 决定内容 |
| --- | --- |
| Agent（智能体） | 谁负责处理该目标。智能体的授权（grants）决定了该目标可以触及哪些资源。 |
| Loop or trigger（循环或触发器） | 何时开始工作：例如心跳机制（heartbeat）、你的回复、或合并的变更请求。 |
| Goal（目标） | “完成”的定义，以文件夹的形式写在云盘（Drive）中。 |

### 工作原理

#### 目标文件夹

每个目标都是云盘中的一个文件夹，默认位于发起人的 **My files（我的文件）** 中，路径为 `Goals/<slug>/`。该文件夹是目标的记忆：每一个处理该目标的会话都会读取它并补充新内容。它包含：

- `GOAL.md`：目标本身、完成标准、面向的人员、分配的智能体、当前状态、限制条件，以及关联文件、应用、变更请求和会话的链接。
- `log.md`：每个操作、每次交接以及验证器的发现，各占一行。
- `evidence/`：每个标准的证明材料以及验证器的报告。

你可以打开并编辑这些文件。你的编辑具有最高优先级（会覆盖智能体的修改）。

#### 状态（States）

一个目标会经历 draft（草稿）、active（进行中）、waiting on you（等待你处理）、verifying（验证中）和 done（已完成）这几个阶段。人员可以在任何阶段手动停止目标。目标绝不会因为困难、缓慢或受阻而自行结束。

#### 工作与唤醒

同一时间只有一个所有者会话（owner session）在处理该目标，且在两次对话交互之间没有任何程序运行。以下情况会将其唤醒：

- 心跳循环（heartbeat loop）：在目标处于开启状态时，每 4 小时唤醒一次；
- 你对它提出的问题作出的回复；
- 它发起的变更请求被合并；
- 验证器的裁定结果。

当所有者会话的上下文（context）写满时，它会将交接信息写入 `log.md`，然后由一个全新的会话接手继续处理。

#### 向你提问

当只有你能解除目标的阻塞状态时，它会向你提问，并进入 **Waiting on you（等待你处理）** 状态。你可以在目标页面或它所在的频道中进行回复。你的回复会将其唤醒。

#### 独立检查

智能体永远不会评判自己的工作。当每个标准都有了相应的证明材料时，目标会启动一个独立的验证器会话，该验证器不参与任何实际工作。验证器会检查每个标准，在 `evidence/verification.md` 文件中为每一项写下 PASS（通过）或 FAIL（失败），并给出最终裁定。只有当所有标准均为 PASS 时，目标才算完成。如果出现 FAIL，目标会被打回重新处理，验证器的发现会记录在 `log.md` 中。

#### 权限

目标本身不授予任何访问权限。发送邮件、Slack 消息或调用连接器等操作，都必须遵循分配给该智能体的授权（grants）以及连接器的审批规则，这与普通会话中的规则一致。如果智能体缺少某项授权，目标会向你请求该授权。

#### 限制

`GOAL.md` 会对工作量设置上限，以防止卡住的目标耗尽你的积分：每个 UTC 日最多唤醒 12 次（达到上限后，心跳机制会等待到第二天），且总共最多运行 10 个会话。你可以在 `GOAL.md` 中修改 `heartbeat`（心跳频率）、`max_wakes_per_day`（每日最大唤醒次数）和 `max_sessions`（最大会话数）。

### 设置步骤

1. **开启目标功能**

    在 **Project admin（项目管理员）** → **Feature flags（功能开关）** 中开启 **Goals（目标）**。

2. **描述目标成果**

    在会话中描述期望的成果，例如“确保……”或“持续跟进直到……”。如果会话已经在进行中，可以说“make this a goal（将其设为目标）”。在 **Goals（目标）** 页面上，点击 **New goal（新建目标）** 即可基于该成果创建一个新目标。

3. **查看计划**

    智能体会回复该目标、完成标准、它首先需要你提供的内容，以及在哪里可以追踪进度。

4. **追踪进度**

    在项目侧边栏中打开 **Goals（目标）**：可以查看状态、负责人和智能体，以及上次和下次唤醒的时间。**Assigned to me（分配给我）** 会显示分配给你的目标。目标页面会展示其定义、日志、证明材料、链接和会话，并提供回复、共享或停止该目标的按钮。

> **警告（Warning）**
>
> 请勿删除处于开启状态的目标的所有者会话（owner session）。如果将其删除，该目标将停止被唤醒。

## 频道（Channels）

频道（Channels）可将项目与 Slack、Microsoft Teams、Telegram、Discord 和微信连接起来。人们可以在这些平台上 @OpenChatly 机器人并布置任务，智能体会在同一位置进行回复，并实时同步进度。每个频道都会自行决定谁可以与机器人对话：在 Slack 和 Teams 中，每个人都需要关联自己的 OpenChatly 账户；在 Telegram 和 Discord 中，项目会维护一份允许访问的人员名单；在微信中，一个机器人只回复扫码绑定它的那个账号。

### Slack 和 Microsoft Teams

#### 工作原理

- **在 Slack 中，一个帖子（thread）对应一个会话。** 帖子中的第一条消息会启动会话，后续消息则继续该会话。
- **在 Slack 频道中，只有 @提及 才会触发智能体。** 没有 @提及 的回复仅在人类之间可见。下一次有人 @提及 时，智能体会读取整个帖子的内容。
- **在与机器人的私信中，每条消息都会触发智能体。** 该会话对你个人私有。
- **在 Teams 中，每个频道发帖都是独立的会话。** 个人聊天或群聊会保持同一个会话，直到有人发送 `/new` 命令。

#### 每人关联自己的账户

由于 Slack 或 Teams 的消息不携带 OpenChatly 登录信息，因此每个人都需要关联一次自己的 OpenChatly 账户：在 Slack 中使用 `/kortix login`，在 Teams 中使用 `/login`。该关联链接仅对你可见，且只能使用一次，10 分钟后过期。

关联完成后：

- OpenChatly 会检查发送者是否为有权启动会话的项目成员。
- 智能体使用其自身的权限进行操作，而不是使用发送者的角色权限。
- 你私有的连接器账户仅在你的机器人私信中生效，绝不会在共享频道中使用。
- 如果某人不在该项目中，会收到一张申请访问权限的卡片。账户所有者和管理员会收到该申请。

#### 谁可以加入会话

每个频道都有一个加入策略（join policy），用于决定谁可以加入在该频道中启动的会话。

| 策略 | 谁可以加入 |
| --- | --- |
| Open（开放，默认） | 任何已关联的项目成员 |
| Approval（审批） | 由会话所有者批准或拒绝每个新加入的人 |
| Owner only（仅限所有者） | 仅限启动该会话的人 |

#### 帖子中的审批与提问

当智能体请求决策时，卡片会显示标题、摘要、风险提示以及 **Approve（批准）** 和 **Deny（拒绝）** 等按钮。每张卡片还带有 **View in OpenChatly（在 OpenChatly 中查看）** 按钮。当智能体需要使用需要审批的连接器操作时，卡片会显示其具体操作内容。项目经理或启动该会话的人可以选择 **Approve（批准）** 或 **Deny（拒绝）**。

当智能体提问时，OpenChatly 会发布该问题，并为每个选项提供一个按钮。在 Teams 中，多个问题或包含多个答案的问题会作为一个表单送达。你也可以用自己的话回复答案。

- 每次点击和表单提交都会传达给智能体，即使有多人回答也是如此。
- 随后，消息会显示答案及回答者的身份，并替换掉原有的按钮。
- 如果会话已被删除，或者 Teams 聊天已通过 `/new` 启动了新会话，那么该问题上的按钮将失效。
- 在关联账户之前按下的按钮，在关联账户后不会自动执行。你需要重新点击。

#### 设置步骤

1. **连接 Slack 或 Teams**

    打开 **Customize（自定义）** → **Connectors（连接器）**，选择 **Channels（频道）** 范围。选择 **Add to Slack（添加到 Slack）**，或连接 **Microsoft Teams**。对于 Teams，租户管理员只需授权一次，OpenChatly 应用就会出现在你组织的 Teams 目录中。

2. **添加机器人**

    将机器人邀请到 Slack 频道，或将 OpenChatly 应用添加到 Teams 聊天或频道中。与机器人的私信无需邀请。

3. **关联你的账户**

    在 Slack 中发送 `/kortix login`，或在 Teams 中发送 `/login`，打开链接并登录。每个 Slack 工作区或 Teams 租户只需执行一次此操作。

4. **@提及 机器人并布置任务**

    智能体会在帖子中回复，并实时同步进度。

当一个 Slack 工作区或 Teams 租户服务于多个项目时，在新频道中发送的第一条消息会显示一个项目选择器。选择后会将该频道绑定到该项目。

删除项目会断开其与 Slack 和 Teams 的连接。其频道会转移到仍处于连接状态的那个项目，或者再次显示项目选择器。在被删除项目的 Slack 帖子中回复将不会得到任何回应。

### Telegram

人们向你创建的 Telegram 机器人发送消息，智能体会在 Telegram 聊天中回复。一个 Telegram 聊天对应一个会话。在论坛群组（forum group）中，每个主题（topic）都是独立的会话。发送 `/new` 后，你的下一条消息将启动一个新会话。

1. **创建机器人**

    在 Telegram 中向 **@BotFather** 发送消息，发送 `/newbot`，并复制它给你的令牌（token）。

2. **进行连接**

    打开 **Customize（自定义）** → **Connectors（连接器）**，选择 **Channels（频道）** 范围，并在 Telegram 上选择 **Connect（连接）**。粘贴 **Bot token（机器人令牌）** 和 **Allowed Telegram user ids（允许的 Telegram 用户 ID）**。OpenChatly 会在服务器上安全保存该令牌。

3. **向机器人发送消息**

    来自允许人员的消息会启动一个会话。其他任何人都会收到一条显示其 Telegram 用户 ID 的回复。当他们在私信中向机器人发送消息时，他们也会出现在 **Allowed users（允许的用户）** → **Wants access（请求访问）** 下，项目经理可以一键批准或拒绝该请求。你也可以通过用户 ID 手动添加人员。

**谁可以使用该机器人。** Telegram 没有账户关联机制：允许的用户名单决定了谁可以与机器人对话，且只有允许人员的点击才会生效。每个允许的人员都可以运行所有命令。在群组中，每个成员都能看到机器人的回复，包括未被允许的成员。回复中可以显示项目名称、模型 ID 和会话链接；但该链接仅对项目有访问权限的人有效。

**命令。** 命令在 OpenChatly 中运行，而不是在智能体中运行：

| 命令 | 作用 |
| --- | --- |
| `/help`（或 `/start`） | 列出命令，并附带可执行这些命令的按钮。 |
| `/status` | 显示当前 Telegram 聊天所属的项目、智能体、模型和会话。 |
| `/stop` | 停止智能体当前的运行。 |
| `/new` | 停止当前运行并启动一个新会话。 |
| `/model`、`/model <id>`、`/model default` | 以按钮形式列出模型、将聊天切换到指定模型，或恢复为项目默认模型。 |
| `/agent`、`/agent <name>`、`/agent default` | 列出智能体、将聊天切换到指定智能体，或恢复为项目默认智能体。新智能体适用于下一个会话：请发送 `/new`。 |

**照片、文件和语音消息均可传达给智能体**，每条消息最多支持 8 MB 的文件。当项目配置了支持读取图像的模型时，智能体才能看到照片。由于没有预装语音转文字工具，处理语音消息大约需要一分钟：智能体会自行安装一个工具来转录录音。

**提问附带按钮。** 一个问题会显示每个选项对应的按钮。多个问题会在一条消息中依次送达（显示 **Question 1 of 3 / 问题 1/3**），智能体会在最后一次点击后获取所有答案。在可以选择多个选项的问题中，每次点击会添加或移除 ✓，点击 **Done ›（完成）** 即可发送。如果消息末尾提示“or type your own answer（或输入你自己的答案）”，你输入的消息将作为该问题的答案。

**Telegram 限制与边缘情况**

- **顺序。** OpenChatly 会按 Telegram 中的顺序，将某个聊天中的消息和点击逐一交给智能体处理。点击按钮会等待你在其之前发送的消息处理完毕。如果某条消息处理失败，后续消息会等待一次重试（通常为 10 到 30 秒）；随后系统会跳过该失败消息继续处理。
- **文件。** 每张照片和文件都会像你在 OpenChatly 中附加的文件一样，显示在会话的消息文本上方。超过 8 MB 限制的文件无法送达，智能体会告知你。相册中的每张照片都会作为独立消息送达，而贴纸则会作为其对应的 emoji 送达。
- **命令词汇。** OpenChatly 会将 11 个词汇作为命令处理：`new`、`reset`、`stop`、`cancel`、`status`、`model`、`models`、`agent`、`agents`、`help` 和 `start`。其他所有消息都会发送给智能体，包括以 `/` 开头且针对其他机器人的命令（例如 `/status@other_bot`）。在照片说明（caption）中输入命令会执行该命令，但不会发送照片：请重新发送不带命令的照片。
- **菜单。** `/model` 和 `/agent` 每页列出 8 个选项，第一页首先是 **Project default（项目默认）**，并带有 **More ›（更多）** 和 **‹ Back（返回）** 按钮。点击后，菜单消息会变为操作结果。菜单仅有效一次：选择选项、点击 **Stop（停止）** 或 **New conversation（新对话）** 都会移除其按钮。如果点击已使用过的菜单、选项或会话已失效的菜单、转发到其他聊天的菜单副本，或超过 30 天的旧菜单，系统会回复“This menu is out of date（此菜单已过期）”：请重新发送命令。
- **`/stop` 和 `/new`** 仅当该 Telegram 聊天启动了当前运行时，才会停止该会话的运行。如果运行是在其他地方启动的（如 Web 应用、API、触发器），它将继续运行，回复中会附带指向该运行的链接。如果在会话仍在启动过程中时发送 `/new`，它不会停止启动过程：智能体仍会回复你之前的消息。
- **模型和智能体。** `/model` 和 `/agent` 适用于整个 Telegram 聊天，包括论坛群组的每个主题。Telegram 聊天仅使用整个项目共享的模型和提供商密钥，绝不会使用个人的密钥或订阅。
- **提问。** 只有在无需审批即可发送 Telegram 消息的情况下，OpenChatly 才会发布带按钮的问题。否则，智能体会用自己的话提问，该消息会等待审批或被拒绝。如果选项超过 6 个，会通过 **More ›（更多）** 和 **‹ Back（返回）** 进行翻页。点击已回答过的问题不会改变任何状态。
- **智能体的写入位置。** 由 Telegram 聊天启动或继续的会话，仅在该聊天及其主题中发送、编辑和删除消息，且仅引用来自该处的消息。它启动的所有其他会话也是如此。从 Web 应用或触发器启动的会话可以向机器人的任何聊天发送消息。
- **机器人的菜单。** 连接机器人后，OpenChatly 命令会被添加到其菜单顶部，同时保留你在 @BotFather 中设置的每个条目。如果你的条目与 OpenChatly 同名，或者菜单会超过 Telegram 的 100 个命令上限，OpenChatly 会省略自己的条目。断开连接时，仅会移除 OpenChatly 添加的条目。
- **群组。** 在群组中，机器人仅读取命令、对它的回复以及 @提及。若要让它读取每条消息，请向 @BotFather 发送 `/setprivacy`，或将机器人设为群组管理员。
- **访问请求** 仅保留请求者信息：用户 ID、用户名、姓名以及最后一次发消息的时间，绝不保留消息内容。OpenChatly 会保留最新的 20 条请求，为期 30 天。断开机器人连接会删除这些请求。
- **删除项目** 会断开机器人的连接。OpenChatly 会删除其令牌，并移除其 Webhook，除非该 Webhook 现已指向另一个项目。

### Discord（Discord）

人们在 Discord 服务器中 @提及 OpenChatly 应用，或直接向它发送消息，智能体会在 Discord 帖子（thread）中回复。

1. **将 OpenChatly 添加到你的服务器**

    打开 **Customize（自定义）** → **Connectors（连接器）**，选择 **Channels（频道）** 范围，并在 Discord 上选择 **Add to Discord（添加到 Discord）**。在 Discord 的页面上选择服务器；你需要在该服务器上拥有 **Manage Server（管理服务器）** 权限。OpenChatly 会立即将你自己的 Discord 账户加入允许名单，**Open Discord（打开 Discord）** 会带你进入该服务器。

2. **@提及 应用并布置任务**

    在文本频道中 @提及 该应用，例如：`@OpenChatly what changed in the release?`。OpenChatly 会在你的消息上创建一个帖子，智能体在该帖子中回复。之后在帖子中 @提及 该应用即可继续。

3. **允许相关人员**

    来自允许人员的 @提及 或私信会启动一个会话。其他人则会收到一条显示其用户 ID 的回复，并出现在 **Allowed users（允许的用户）** → **Wants access（请求访问）** 下，项目经理可以一键批准或拒绝该请求。你也可以通过用户 ID 添加人员。

**一个 Discord 帖子对应一个会话。** 在文本频道或公告频道中的 @提及 会在该消息上创建一个帖子，之后在该帖子中的 @提及 会继续该会话。与该应用的私信在发送 `/new` 之前一直是一个会话，其中的每条消息都会传达给智能体。在不支持帖子的频道中（例如语音频道的文字聊天），该频道本身即为会话。

**在服务器中，只有 @提及 才会触发智能体**，这一点与 Slack 相同。在该帖子中，人们可以在没有智能体参与的情况下交流，直到有人 @提及 它。OpenChatly 会用 ⏳ 标记它交给智能体的每条消息，并在运行完成时将其替换为 ✅。当运行失败或被你停止时，⏳ 会消失，回复中会说明发生了什么。

**命令。** `/help`、`/status`、`/new`、`/stop`、`/model`、`/agent` 和 `/connect` 在 OpenChatly 中运行，而不是在智能体中运行。它们在频道、帖子和私信中都有效，也可以在 @提及 之后输入。在频道中使用的命令适用于整个频道：在该频道中执行 `/model` 会设置其中每个帖子的模型。在 Web 应用中，Discord 卡片上的 **N channels（N 个频道）** 会列出 OpenChatly 在其中回复过的所有频道和私信；选择其中一个即可设置其智能体和模型。

**照片、文件和语音消息均可传达给智能体**，每条消息最多 8 MB，与 Telegram 相同。转发消息的文本和文件、以及投票（poll）的问题和选项同样如此。提问附带按钮，每页 4 个选项。

**Discord 限制与边缘情况**

- **@提及。** 对应用的回复只有在开启 **@mention（@提及）** 时才会被计入；当该功能关闭时，OpenChatly 会提示一次。在 15 分钟内通过编辑添加 @提及 的消息同样会被计入。如果自托管（self-hosted）的 OpenChatly 其 Discord 应用启用了 Message Content（消息内容）意图（intent），则可以让 OpenChatly 帖子中的每条消息都传递给智能体（`DISCORD_MESSAGE_CONTENT`）。
- **智能体能读取的内容。** 如果没有启用 Message Content 意图，Discord 只会向智能体显示 @提及 它的消息、私信以及它自己发出的消息。若要询问某段讨论的内容，请把你所指的部分粘贴过来。
- **菜单。** `/model` 和 `/agent` 会列出选项，并带有 **More ›（更多）** 和 **‹ Back（返回）**。一次选择、**Stop（停止）** 或 **New conversation（新对话）** 操作只会生效一次。点击旧菜单会回复 "This menu is out of date（此菜单已过期）"：请重新使用命令。一条只有你能看到的提示会确认你的点击，或说明为何没有产生任何变化。
- **顺序。** 一个帖子中的消息和点击会按 Discord 的顺序逐一传达给智能体。当 OpenChatly 在多次尝试后仍无法接收某条消息时，它会请你重新发送。
- **项目。** 一个服务器可以服务于多个项目。频道归属于第一个在其中作出回复的项目；`/connect` 会列出各项目并将频道绑定到你所选择的那个项目。私信归属于那个允许你访问的项目；若有多个，则由 `/connect` 进行选择。
- **智能体的写入位置。** `kortix_discord` 连接器仅在该项目自身的服务器、帖子和私信中读取和写入。在由多个项目共享的服务器中，它仅在自己的帖子、私信和已绑定的频道中操作。由 Discord 帖子启动的会话仅在该处读取和写入。用 `/connect` 转移到另一个项目的私信，在新项目中会保留其先前的消息。每个项目每分钟最多发起 60 次 Discord 调用。
- **权限。** 在你添加应用时，Discord 会请求以下权限：查看频道、发送消息、在帖子中发送消息、创建公开帖子、读取消息历史、附加文件、添加表情反应以及嵌入链接。当某个频道拒绝其中某项权限时，OpenChatly 会予以提示。在应用无法发布回复的地方，它会单独向你发出一条提示，并附上需要授予的权限。在私密帖子中，请先 @提及 该应用或将其加入。
- **归档。** OpenChatly 帖子在一天没有消息后会被归档，而新消息会重新打开该帖子。当服务器达到 Discord 的活跃帖子上限时，OpenChatly 会予以提示，而不再新建帖子。
- **断开连接** 会将该服务器从项目中移除。当没有其他项目使用该服务器时，应用会离开该服务器。将应用从服务器中移除，会使其与所有项目断开连接。
- **访问请求** 仅保留请求者信息：用户 ID、用户名、显示名称以及他们最后一次发消息的时间，绝不保留消息内容。

### 微信（WeChat）

每人用自己的微信扫码，将一个 iLink 机器人绑定到该账号，智能体就在与这个账号的一对一聊天中回复。一个机器人只服务扫码绑定它的那个账号：一个项目可以绑定多个机器人，每人一个；每个机器人都是独立的会话，两个账号永远看不到彼此的消息。

1. **连接微信**

    打开 **Customize（自定义）** → **Connectors（连接器）**，选择 **Channels（渠道）** 范围，并在微信上选择 **Connect（连接）**。页面会显示二维码。

2. **扫码**

    用微信扫描二维码，并在手机上确认登录。机器人便绑定到扫码的账号。

3. **给它发一条消息**

    在微信中打开该机器人并发送第一个任务。智能体会在同一聊天中回复。

**每人连接自己的账号。** 微信卡片上的 **Connect another（再连接一个）** 会把机器人绑定到另一个微信账号，每人一个。每个机器人都有自己的会话，其对话不会与其他机器人的对话混在一起。卡片会列出所有机器人：可以单独断开某个机器人，也可以一次全部断开。

**命令。** `/help`、`/status`、`/new`、`/stop`、`/model` 和 `/agent` 在 OpenChatly 中运行，而不是在智能体中运行。`/model` 和 `/agent` 会列出此聊天可用的选项，你回复 `/model <id>` 或 `/agent <name>` 即可：微信消息没有按钮。

**微信限制与边缘情况**

- **仅限一对一。** 机器人只回复扫码绑定它的那个账号，且只在该聊天中回复，不接收群消息。来自任何其他账号的消息都会被丢弃。
- **纯文本。** 一条微信消息最多 4,000 个字符；更长的回答会分成多条消息发送。没有 Markdown、标题、表格和按钮，因此智能体会写短段落，并用短横线表示列表。
- **只有文本会传达给智能体。** 图片、语音、文件和视频只会以一个标明其类型的标签到达，而不是其内容。智能体会请你描述它，或在 OpenChatly 应用中重新发送。
- **提问。** 智能体会用平实的文字提问并等待你的回复；带按钮的问题卡片不会出现在微信中。
- **单个机器人的暂停。** 当微信暂停该账号（iLink 风控）时，该机器人会停止轮询一小时，之后继续接收新消息。项目中的其他机器人不受影响。
- **机器人令牌保存在服务器上。** 智能体通过 `kortix_wechat` 连接器回复，沙箱中永远看不到该令牌。机器人只接收扫码账号的消息，聊天中仅显示该账号 ID 的最后六位。
- **断开连接** 会删除该机器人的凭据并停止接收消息。断开一个机器人不会影响项目中其他微信机器人。

## 全平台（Everywhere）

OpenChatly 可在 Web 应用、桌面应用、移动端应用、终端，以及通过 MCP 接入的其他 AI 工具中运行。所有这些入口打开的都是相同的项目和会话。

### Web 应用

Web 应用是主要的工作场所。它在 [openchatly.com](https://openchatly.com) 上运行，登录之后会打开你上次打开的那个项目。在会话中，你可以为下一轮对话选择智能体和模型，附加文件或将文件拖放到页面上，并在智能体工作时发送消息：它会在它的下一步读取这些消息。[熟悉网页应用界面](#熟悉网页应用界面) 列出了各个功能所在的位置。

### 桌面应用

桌面应用是将 Web 应用封装在原生窗口中的版本，支持 macOS、Windows 和 Linux。请在 [openchatly.com/download](https://openchatly.com/download) 下载。

- **快速入口（Quick Entry）。** 在任何应用中，按 Mac 上的 `Cmd+Shift+Space`，或 Windows 和 Linux 上的 `Ctrl+Shift+Space`。在输入栏中输入一个任务并按回车键：OpenChatly 会据此启动一个新会话。
- **截图。** 在 macOS 上，快速入口中的相机按钮会截取一张屏幕截图并将其附加上去。
- **更新。** 应用会自动更新。当更新准备就绪时，选择 **Restart now（立即重启）** 或 **Later（稍后）**。
- **你的计算机。** 在连接了计算机的情况下，当你关闭最后一个窗口时，应用会留在菜单栏或系统托盘中。请参阅 [计算机（Computers）](/docs/zh/guide#计算机computers)。

### 移动端应用

移动端应用可在 iPhone、iPad 和 Android 上运行。请从 App Store 或 Google Play 获取。借助它，你可以：

- 打开项目并启动会话；
- 跟进并继续会话，支持照片、文件和语音听写；
- 接受或拒绝项目邀请；
- 浏览你的文件；
- 在你的会话完成、失败或向你提问时收到通知。

### 终端

`kortix` 命令行工具可以在终端中完成 Web 应用所做的操作：它用于创建和克隆项目、运行会话、审核变更请求，以及配置智能体、连接器和密钥（secrets）。它可在 macOS 和 Linux 上运行；在 Windows 上，请使用 WSL。

```sh
curl -fsSL https://kortix.com/install | bash
```

然后运行 `kortix login`。此时会打开你的浏览器，你需要在浏览器中批准登录。[CLI reference（CLI 参考）](/docs/zh/developers#cli命令行界面) 中列出了所有可用命令。

`kortix tui` 会在你的终端内打开一个完整的 OpenChatly 客户端。单个会话会占满整个屏幕，你可以通过其输入框完成所有操作：输入 `/` 可列出所有命令，`/sessions` 可打开另一个会话，`/new` 可启动新会话，`/drive` 或 `/approvals` 则可打开相应的界面。在没有打开任何会话的情况下，你输入的第一条提示词（prompt）将直接启动一个新会话。`/sidebar` 会在侧边栏中显示你的项目和会话，TUI 会记住这一选择。TUI 目前仍处于实验阶段，因此其命令和快捷键可能会在不同版本之间发生变化。

### 其他 AI 工具（MCP）

OpenChatly MCP 服务器允许其他 AI 工具（如 Claude、ChatGPT、Cursor 或 Codex）调用 OpenChatly 的能力。你无需安装任何额外组件：只需在工具中添加一个 URL 并登录即可。配置完成后，该工具可以：

- 启动会话并向其发送消息；
- 读取会话的进度；
- 在会话的云计算机上运行命令；
- 调用你的连接器（connectors）。

该工具将以你的身份进行操作，拥有你的权限，并能访问你可以打开的所有账户和项目。

1. **复制 URL**

    在 Web 应用中，打开左上角的项目菜单并选择 **Connect MCP（连接 MCP）**。对话框会显示你的 OpenChatly URL（在 OpenChatly Cloud 上为 `https://api.kortix.com/v1/mcp`），并提供针对 Claude、Claude Code、Cursor、Codex 及其他 MCP 客户端的安装操作。

2. **将其添加到你的工具中**

    在 Claude 中，打开 **Settings（设置）** → **Connectors（连接器）** → **Add custom connector（添加自定义连接器）** 并粘贴 URL。ChatGPT 需要开启开发者模式并使用 **OAuth** 登录。在 Cursor 中，在对话框的 Cursor 行上选择 **Add（添加）**。

3. **登录**

    在首次调用时，你的浏览器会打开 OpenChatly 的授权同意页面。请仅在你亲自连接该工具时才批准授权。

若要断开工具的连接，请打开 **Settings（设置）** → **Personal access keys（个人访问密钥）** → **Connected apps（已连接的应用）** 并选择 **Revoke access（撤销访问权限）**。其访问权限将立即停止。

## 人员与访问权限

账户（Account）用于承载项目及其成员。你可以决定谁能打开每个项目、每个人可以运行哪些智能体，以及谁能查看每个会话。

### 工作原理

- **Account（账户）：** 你的公司在 OpenChatly 中的大本营。它包含项目、成员和设置。一个登录账号可以属于多个账户。
- **Project（项目）：** 一个独立的 Git 仓库，拥有自己的智能体、技能、连接器、文件和设置。
- **Account role（账户角色）：** 每个人都有一个账户角色：所有者（Owner）、管理员（Admin）或成员（Member）。
- **Project role（项目角色）：** 每个人在其参与的每个项目中都有一个角色：项目经理（Manager）或成员（Member）。
- **Group（群组）：** 一组命名的人员集合。授予群组访问权限后，其中的每个人都会获得该权限。

#### 账户角色

| 角色 | 权限说明 |
| --- | --- |
| Owner（所有者） | 拥有管理员的所有权限。此外，他们还可以删除账户并将其他人设为所有者。 |
| Admin（管理员） | 邀请和移除成员、更改角色、管理群组、创建项目和更改计划。他们在每个项目中都充当项目经理。 |
| Member（成员） | 在被分配的项目中工作。他们可以看到计划，但不能创建项目或更改计费信息。 |

#### 项目角色

| 角色 | 权限说明 |
| --- | --- |
| Manager（项目经理） | 拥有项目中的所有权限：编辑智能体、技能、连接器、密钥和触发器，合并工作成果，以及管理访问权限。 |
| Member（成员） | 打开项目，启动和跟进会话，并提交工作成果以供审核。他们不能更改设置或合并更改。 |

成员数量没有上限，且不收取额外费用。请参阅 [Billing（计费）](#计费billing)。

### 设置步骤

1. **首先创建团队账户**

    注册时 OpenChatly 创建的账户是个人账户。它不支持单点登录（SSO），且项目以后无法转移到其他账户。请打开项目菜单，选择 **Switch Project（切换项目）**，然后选择 **Create an account…（创建账户…）**，并在那里创建你团队的项目。

2. **邀请你的队友**

    打开 **Account settings（账户设置）** → **Members（成员）** 并选择 **Invite（邀请）**。输入他们的电子邮件地址并选择角色。已有 OpenChatly 登录账号的人员会立即加入。其他人会收到一封有效期为 14 天的电子邮件邀请。

3. **为他们分配项目**

    打开 **Account settings（账户设置）** → **Projects（项目）**，选择项目并点击 **Grant access（授予访问权限）**。选择 **Manager（项目经理）** 或 **Member（成员）**。你还可以设置访问权限的到期日期。

4. **选择他们可用的智能体**

    在同一个对话框中，将 **Agents（智能体）** 设置为 **All agents（所有智能体）** 或 **Only these…（仅限以下…）**。如果没有分配任何智能体，成员将无法启动会话。

所有者和管理员无需授权即可访问所有项目。

### 群组

群组可以免除你逐个授予访问权限的麻烦。创建一个“Engineering（工程）”群组，为其分配一个项目，群组中的每个人都会获得该项目的访问权限。群组只会增加访问权限，绝不会剥夺个人已经拥有的权限。

创建群组并向其中添加人员是 Enterprise（企业版）功能。如果你的公司使用身份提供商（IdP），它可以保持群组的同步。请参阅 [Single sign-on and directory sync（单点登录与目录同步）](#单点登录与目录同步)。

### 谁能看到什么

成员在成员列表中只能看到自己，看不到其他成员或群组。所有者和管理员可以看到所有人。在项目中，人员仍会出现在其工作成果展示的地方，例如作为会话的所有者。

打开其无权读取的项目的人员会看到 **Request access（请求访问）**。OpenChatly 会通知该项目的经理，由他们批准或拒绝请求。

### 共享会话

会话对启动它的人是私有的。所有者可以选择允许其他人打开它：

| 选项 | 谁可以打开 |
| --- | --- |
| **Only you（仅限你）** | 所有者。这是默认设置。 |
| **Specific people（特定人员）** | 所有者，加上他们选择的成员和群组。 |
| **Whole project（整个项目）** | 项目的每个成员。 |

每个有访问权限的人都可以读取会话并继续操作。只有所有者可以更改访问权限。

你还可以创建一个 **Public link（公开链接）**。它向任何拥有该链接的人展示只读的会话，且无需登录。你可以随时撤销该链接。

### 智能体的工作如何进入项目仓库

你的智能体、技能和设置都存放在项目的共享仓库中。OpenChatly 保护它免受未经审核的更改影响：

1. 每个会话都在自己的分支上工作，该分支是仓库的私有副本。
2. 智能体完成后，它会打开一个变更请求（change request）：即请求将该分支合并到共享分支中。
3. 变更请求会出现在 **Review（审核）** 页面上。
4. 人员会阅读更改并批准、关闭或要求修改。
5. 要求修改的备注会作为新消息返回给智能体。

智能体只有在拥有合并权限时才能合并自己的变更请求。`worker` 角色拥有此权限；请参阅 [How an agent asks before risky actions（智能体在执行高风险操作前如何请求授权）](#智能体如何在风险操作前先征求同意)。如果合并操作会更改智能体或触发器，也需要相应的权限。

## 安全性

每个会话都在其独立的隔离沙盒中运行。密钥和连接器登录信息均加密存储，并尽可能保留在沙盒之外。每个智能体都有自己的权限，审计日志会记录每一个操作。需要单点登录、目录同步和自托管的企业客户均可获得相应支持。

### 工作原理

#### 每个会话拥有自己的沙盒

每个会话都会启动一台独立的、隔离的云计算机，称为沙盒（sandbox）。智能体在该项目仓库的自有分支上工作。默认情况下，会话只能推送到它自己的分支，其工作成果只有在某个人合并它的变更请求（change request）后才会进入共享仓库。请参阅 [智能体的工作如何进入项目仓库](#智能体的工作如何进入项目仓库)。

没有 **Project repository access（项目仓库访问权限）** 的智能体不会获得仓库的任何副本。其会话无法读取仓库、向其推送或向其合并。

#### 智能体拥有各自的权限上限

会话以智能体的权限运行，而不是以启动它的那个人的权限运行。由你决定每个智能体能做什么，智能体永远无法给自己授予它所不具备的权限。

#### 密钥（Secrets）：由你决定谁能使用、如何使用

密钥（secret）是会话所需的密码、API 密钥或令牌。OpenChatly 会对每一个值进行加密，任何页面、命令或 API 都不会再次显示已存储的值。

每个密钥都有一个适用受众（audience）：

| 选项 | 谁可以使用 |
| --- | --- |
| Everyone in the project（项目内的所有人） | 项目中的每个会话。这是默认设置。 |
| **Only you（仅限你本人）** | 你本人，在你自己的私有会话中。 |
| **Specific people, groups, or agents（特定人员、群组或智能体）** | 仅限你所挑选的人员、群组和智能体。 |

你还可以决定密钥以何种方式送达沙盒：

- **Environment variable（环境变量）。** 沙盒获得真实的值，会话中的代码可以读取它。
- **Egress-enforced（强制出口管控）。** 沙盒获得一个本身毫无用处的替身（stand-in）。OpenChatly 会在沙盒之外、仅针对发往你所列出的网址的请求，替换为真实的值。
- **Disabled（已禁用）。** 该值保持存储状态，不会送达任何会话。

要检查强制出口管控的送达效果，可在会话中运行两个探测（probes）。首先，打印该变量：它显示的是替身，而非真实值。然后调用使用该凭证的某个 API 端点——绝不要调用会把请求头原样回显的端点：返回 `200` 说明 OpenChatly 已替换为真实值，`401` 说明并未替换。

> **警告（Warning）**
>
> 以环境变量方式送达的密钥，在会话内部就是一个真实的值。对于一个 Web API 密钥，除非代码确实需要真实的值，否则请使用强制出口管控方式送达。

#### 连接器登录信息保留在 OpenChatly 侧

当你连接 Gmail 或 Linear 等应用时，OpenChatly 会存储登录信息，它绝不会进入沙盒。对于每一次调用，OpenChatly 会选定账户、应用你的规则、执行调用并记录在案。由你的规则决定每个智能体在每个应用中可以做什么：**Allow（允许）**、**Ask（请求某个人审批）**，或 **Block（阻止）**。审批事项会等待在 **Review（审核）** 页面上。OpenChatly 还会拒绝对私有或内网地址发起的连接器请求。

### 审计日志（Audit log）

审计日志记录账户中谁、在何时、做了什么、如何登录，以及该操作是否被允许。记录功能始终开启，被拒绝的请求同样会被记录。当一个智能体采取行动时，日志还会指明它是代表谁行事的。日志绝不存储任何密钥。

所有者和管理员可在 **Account settings（账户设置）** → **Audit log（审计日志）** 下读取该日志。事件在那里保持可读 90 天。介于 90 天到 365 天之间的事件保留在一个锁定归档中，任何人都无法缩短或删除该归档，你可以将其导出。你还可以将每一个新事件流式传输（stream）到你自己的安全工具中。

读取、导出和流式传输日志均为 Enterprise（企业版）功能。

### 登录控制

所有者和管理员在 **Account settings（账户设置）** → **Settings（设置）** → **Security（安全）** 下设置账户的登录规则：

- **Require two-factor authentication（要求双因素认证）**：针对每个成员。
- **Maximum session length（最大会话时长）** 和 **Idle timeout（空闲超时）**：在设定的时间后将人员登出。
- **Active sessions（活动会话）**：列出最近的登录记录，你可以将任何人登出。

每个人可在 **Settings（设置）** → **Security（安全）** 下查看并登出自己的设备。

### 单点登录与目录同步

借助单点登录（SAML），你的团队通过你公司的身份提供商（identity provider）登录。开启 **Enforce SSO for this domain（对该域名强制启用 SSO）** 后，其他登录方式将对该电子邮件域名停止工作。

目录同步（SCIM）让你的身份提供商在 OpenChatly 中添加、更新和移除成员及群组。当某人离开你的公司时，他同样会失去对 OpenChatly 的访问权限。请先设置好单点登录。

两者均为 Enterprise（企业版）功能。请在 **Account settings（账户设置）** → **Identity & directory（身份与目录）** 下进行设置。它们需要团队账户，而不是 OpenChatly 在注册时创建的个人账户。

### 设置步骤

1. **开启双因素认证**

    在 **Account settings（账户设置）** → **Settings（设置）** → **Security（安全）** 下，要求整个账户启用双因素认证。

2. **限制每个密钥**

    在项目的 **Secrets（密钥）** 页面上，为每个密钥指定能正常工作的最小受众范围。

3. **设置连接器规则**

    阻止智能体绝不应执行的操作，并对有风险的操作请求审批。

4. **连接你的身份提供商**

    在企业版下，在 **Account settings（账户设置）** → **Identity & directory（身份与目录）** 下设置单点登录和目录同步。

## 计费（Billing）

OpenChatly 以积分（credits）为一个账户计费。1 积分等于 ￥0.01。积分存放在整个账户共用的一个钱包中，每个项目都从中消耗。成员免费且数量不限。

要查看你的余额，请打开 **Account settings（账户设置）** → **Billing（计费）** → **Plan（计划）**。

### 计划（Plans）

一个账户处于两种计划之一：Free（免费版）或 Credits（积分版）。当前价格详见 [openchatly.com/pricing](https://openchatly.com/pricing)。

| | Free（免费版） | Credits（积分版） |
| --- | --- | --- |
| 计费 | 不收费 | 你自行选择的一个按月金额 |
| 积分 | 每月 500 积分 | 以实际营销为准 |
| 成员 | 以实际营销为准 | 不限，不按成员收费 |
| OpenChatly 托管模型 | 以实际营销为准 | 全部 |
| 购买额外积分 | 以实际营销为准 | 可以 |
| 自动充值 | 以实际营销为准 | 可以 |
| 项目 | 以实际营销为准 | 200 个 |

- 每个计划都可以使用你自己提供商密钥上的模型或 ChatGPT 订阅。请参阅 [Models（模型）](#模型models)。

#### Enterprise（企业版）

Enterprise 并不是一种计划。它是在任一计划之上开启额外功能：单点登录、目录同步、群组与自定义角色、审计日志，以及品牌定制。拥有企业版许可证的账户没有项目数量上限。要获取一份许可证，请在应用中点击 **Talk to sales（联系销售）**，或发送邮件至 [support@openchatly.com](mailto:support@openchatly.com)。请参阅 [Security（安全性）](#安全性)。

### 积分消耗说明

| 消耗项 | 计费方式 |
| --- | --- |
| OpenChatly 托管模型 | 按每次请求使用的 token 数量，并以提供商的模型倍率计算。 |
| 使用自有密钥的模型 | 每月前 ¥7,200 的用量免费。超出部分，按每次请求牌价的 5% 收费。ChatGPT 订阅绝不收费。拥有企业版许可证则无此费用。 |
| 会话机器 | 按机器预留的规格和实际运行秒数，以运行该机器的提供商的费率卡计算。应用（App）机器同样计费。 |
| 网页工具 | 每次通过 OpenChatly 发起的网页搜索、图像搜索或网页抓取请求。 |
| 住宅代理 | 按会话通过住宅 IP 地址发送和接收的数据量（GB）计费。仅适用于要求使用此功能的沙盒模板。请参阅 [Residential IP address（住宅 IP 地址）](#住宅-ip-地址residential-ip-address)。 |
| 存储 | 按云盘（Drive）和每个会话的 `/workspace` 中保留的数据量（GiB/小时）计费，保留多久计多久。OpenChatly 每天测量一次存储数据（压缩后且重复块仅计一次），并在当天结束后进行扣费。 |

已停止或处于休眠状态的机器不产生费用。每个沙盒提供商都有自己的费率卡，机器按其实际运行提供商的费率计费，因此更改新会话的落地位置不会改变已在运行会话的价格。**Admin（管理员）** → **Billing（计费）** → **Compute（计算）** 会显示并允许编辑每个提供商的一行费率；下面的卡片是当前部署适用的费率：

| 资源 | 费率 |
| --- | --- |
| vCPU | ¥0.16 / 小时 |
| 内存 | ¥0.08 / GB-小时 |
| 存储 | ¥2.00 / GB-月 |

按此费率卡计算，默认的 2 vCPU / 4 GB / 15 GiB 机器每小时约 ¥0.68，约 68 积分。

### 钱包（The wallet）

钱包中包含两种积分：

| 类型 | 来源 | 有效期 |
| --- | --- | --- |
| 会过期（Expiring） | 你的计划赠送 | 随计划结束而失效。若不续费，余额将降至免费额度。 |
| 不过期（Non-expiring） | 充值、奖励、退款和促销活动 | 永不过期 |

OpenChatly 会优先消耗会过期的积分。已完成的工作始终会被记录，即使余额降至零以下，但新的运行需要账户有正余额。

### 添加积分

每个计划都可以购买积分，购买的积分永不过期。要添加积分，请在 **Billing（计费）** → **Plan（计划）** 上选择 **Add credits（添加积分）**，选择金额并支付。

### 更改你的计划

| 更改操作 | 发生的情况 |
| --- | --- |
| 从 Free（免费版）升级到 Credits（积分版） | 在 **Billing（计费）** → **Plan（计划）** 上选择金额并点击 **Subscribe（订阅）**。 |
| 提高按月金额 | 你现在需支付当前周期剩余时间的差价，并获得相应比例的新增积分。 |
| 降低按月金额 | 更改将从下一次续费时生效，不予退款。你现有的积分保持不变。 |
| 取消 | **Cancel subscription（取消订阅）** 会在当前计费周期结束时终止计划。在此之前，**Reactivate subscription（重新激活订阅）** 可撤销取消操作。 |

在 **Manage billing（管理计费）** 下管理支付方式和发票。只有所有者和管理员可以更改计费信息；所有成员都可以查看。请参阅 [People and access（人员与访问权限）](#teams)。

### 余额耗尽

当余额降至零时，智能体会暂停，触发器也会停止启动新会话。账户的应用（Apps）同样会停止，其访客会看到一个 **App paused（应用已暂停）** 页面。

若要继续，请添加积分或更新支付方式。在免费版下，你也可以订阅 Credits（积分版）计划，或等待下个月的免费额度发放。无法添加积分的成员可以选择 **Ask an owner（询问所有者）**，随后每位所有者和管理员都会收到一封包含当前余额的邮件。

### 追踪用量

| 位置 | 显示内容 |
| --- | --- |
| **Billing（计费）** → **Plan（计划）** | 当前计划、钱包、本周期支出（计算、存储、模型）以及自动充值设置 |
| **Billing（计费）** → **Usage（用量）** | OpenChatly 扣费记录和积分历史 |
| 项目中的 **Customize（自定义）** → **Models（模型）** → **Costs（费用）** | 该项目的模型支出和预算 |
