title: "odc README" updated: 2026-04-12

odc

odc 是一个自部署的 AI Agent 编排平台。它面向 owner，帮助你在本地或团队内网里管理 workspace、session、plugin 和 IM 渠道，把 AI agent 接到真实工作流中。

这份 README 面向第一次安装 odc 的使用者，不是面向仓库贡献者。重点是两件事：

• 尽快把 odc 安装并跑起来
• 把它接到飞书或企微，完成首个可用对话链路

适合谁

如果你符合下面任一情况，这个项目就是给你用的：

• 你想通过飞书或企微和 AI agent 交互
• 你想把多个 agent 放进可管理的 workspace 中
• 你希望 session、transcript、workspace 和 plugin 都能落到本地文件系统，便于持续使用和排查

路径 A：5 分钟跑起来

最快的方式不是手工逐步安装，而是把下面这段提示词交给一个能执行命令的 AI coding agent，让它替你完成安装和首个可用链路验证。

这段提示词假设你要用的是 全局安装版 odc，而不是仓库源码版本。

你现在是我的安装代理，请把 odc 安装到“可用”为止，而不只是“命令存在”。

安装目标：
1. 全局安装 odc：`npm install -g @opendeepcrew/odc`
2. 全局安装 acpx：`npm install -g acpx@latest`
3. 验证 `odc` 和 `acpx` 命令可用
4. 启动 odc server
5. 创建一个最小可用 workspace
6. 接入一个 IM 渠道（优先飞书，其次企微）
7. 完成一次首个可用对话链路验证
8. 最后给我一份非常短的结果摘要：已完成什么、还缺什么、下一步我该做什么

执行要求：
- 优先使用已经安装好的全局命令 `odc` 和 `acpx`
- 不要假设我是在源码仓库里运行，也不要默认走 `node dist/...`
- 如果缺少机器人凭证、平台配置、owner 身份配置或外部权限，请明确列出阻塞项
- 如果某一步失败，请继续排查，不要在第一次报错后停止
- 如果无法完成完整 IM 接入，至少要把 odc 跑起来、workspace 建好，并把剩余阻塞项整理成 checklist

完成标准：
- `odc --help` 可用
- `acpx --version` 可用
- odc server 成功启动
- 至少有一个 workspace 可用
- 至少完成一次从“外部消息进入”到“agent 回复返回”或明确证明只差外部凭证的验证

如果你更喜欢手工安装，再看路径 B。

路径 B：手工安装并开始使用

1. 安装前置依赖

先安装 odc：

npm install -g @opendeepcrew/odc

再安装 acpx：

npm install -g acpx@latest

2. 验证命令是否可用

odc --help
acpx --version

如果这两个命令都能正常执行，说明最基本的 CLI 前置条件已经满足。

3. 启动 odc server

odc server start

如果你需要覆盖运行时 root 或端口：

odc server start --root ~/.odc --port 7200

odc 默认会把运行时数据写到 ~/.odc/。

4. 创建第一个 workspace

先看已有 workspace：

odc workspace list

创建一个新的 workspace：

odc workspace create <name> --agent-type <agentType>

例如：

odc workspace create demo --agent-type codex

查看 workspace 详情：

odc workspace show demo

5. 接入飞书或企微

odc 的核心使用方式之一，是把 chat 绑定到 workspace，然后通过 IM 直接与 agent 对话。

接入飞书或企微前，你通常需要准备：

• 机器人应用本身
• 对应平台的 app id、app secret、token 等凭证
• 事件订阅或 websocket 配置
• odc 的 owner 身份配置

推荐顺序是：

1. 先确认 odc 和 acpx 已安装
2. 再确认 server 能启动
3. 再确认至少一个 workspace 已创建
4. 然后再补齐 IM 渠道凭证和平台侧配置

如果你不确定缺什么，最省事的方式仍然是走路径 A，把问题交给 AI agent 逐项排查。

6. 开始使用

接入成功后，owner 的典型使用流是：

1. 在 IM 中把 chat 绑定到某个 workspace
2. 给 agent 发消息
3. 查看回复
4. 必要时排查 transcript、workspace、session 和日志

如果当前 chat 尚未绑定，系统会提示你先选择或绑定 workspace。

常用操作

常见的 owner 操作主要是这几类：

odc workspace list
odc workspace create <name> --agent-type <agentType>
odc workspace show <name>
odc server start

如果你在做排查，优先关注：

• odc 命令是否存在
• acpx 命令是否存在
• server 是否成功启动
• workspace 是否已创建
• ~/.odc/ 是否有预期文件
• IM 渠道凭证是否齐全

数据目录

odc 默认把运行时数据写到 ~/.odc/，通常会看到这些目录：

~/.odc/
├── config/
├── channels/
├── transcripts/
├── workspaces/
├── plugins/
└── logs/

可以把它理解为 odc 的本地控制面和运行时状态目录：

• config/：配置
• channels/：渠道绑定与渠道状态
• transcripts/：会话记录
• workspaces/：workspace 元数据
• plugins/：插件与订阅源
• logs/：服务日志

项目状态

odc 仍在持续演进中，但目标很明确：让 owner 能通过全局安装快速部署，并把 AI agent 以 workspace + session + IM channel 的方式稳定接入日常工作流。