腾讯云 Octop 快速入门：一小时跑通一个自托管的多用户 Agent 平台
内容提要
Octop是腾讯云开源的多用户Agent平台，单进程集成对话、技能、知识库、IM与插件。文章介绍源码安装、配置模型、创建专家、接入飞书、定时任务与Token统计，并演示编写字数统计插件，强调多用户场景需设置配额、脱敏API Key、限制文件权限，适合团队自托管使用。
延伸解读
多用户场景下的默认配置风险
文章指出，Octop 的 token_quota 和 max_agents 默认不限，普通用户默认拥有 13 项权限。单人使用无碍，但一旦给同事开号，就可能出现额度被跑光或资源滥用。作者建议在添加用户时同步设置这两个数值，并修改供应商 API Key 明文返回的问题，否则任何登录用户都能在开发者工具中看到 Key。
插件机制：函数签名即接口
Octop 插件是一个包含 plugin.yaml 和 main.py 的目录，kind 决定其类型为 tool、skill 或 hook。最省事的设计是框架根据 Python 函数的参数名、类型注解和 docstring 自动生成工具 schema，无需手写 JSON Schema。插件全局安装后，还需在“个性化 → 插件”中按专家启用，否则对话中不会调用。
自托管成本与统计局限
文章提到管理页的 Token 统计可按天、按专家、按模型查看，示例中缓存命中率为 22.0%，这部分输入价格通常更低。但页面标注“部分消耗（如记忆总结、召回等）尚未纳入统计”，因此该面板显示的是成本下限而非准确值。自托管时账单分散在各供应商，做预算需留余量。
适用场景与替代方案对比
作者判断 Octop 适合需要“在服务器上持续活着、能从 IM 被叫到、还能碰文件和终端”且多人使用的场景，例如让无技术背景的同事统一使用团队配置好的技能和工具。若只是个人写代码需要结对伙伴，CLI 工具更轻。与工作流编排类平台相比，Octop 的隔离单位是 Agent 而非应用或流程。
Q&A
Octop 是什么？它和 Dify 这类平台有什么区别？
Octop 是腾讯云开源的、可自托管的多用户 Agent 平台，MIT 协议，单个 Python 进程集成对话、技能、知识库、IM 通道、定时任务和插件系统。与 Dify/n8n 等工作流编排类平台不同，Octop 是面向多用户的 Web 平台，隔离单位是 Agent（每个有独立工作区和记忆），内置账号、角色、权限和配额，并内置 10 个 IM 通道。
从源码安装 Octop 并跑起来需要哪些步骤？
步骤：1) 安装 uv；2) git clone 仓库；3) cd Octop 后执行 uv sync 安装依赖；4) uv run octop init 初始化（密码需数字加字母，若目录已存在可加 --force）；5) 编译前端：make build-frontend（需 Node 18+）；6) uv run octop run 启动，访问 http://localhost:8000 登录。
Octop 的多用户功能怎么用？给同事开号前要注意什么？
登录方式有本地账号密码、邀请码注册、飞书 SSO、企业微信/钉钉、通用 OIDC/LDAP，也可用命令行建号（octop user create）。管理员拥有全部权限，普通用户默认 13 项权限。开号前务必设置 token_quota 和 max_agents（默认不限），并修复供应商 API Key 明文返回的问题，否则普通用户可通过开发者工具看到 Key。
如何让 Octop 的 Agent 在飞书里回复消息？
在「个性化 → 通道」选择当前专家使用的通道，以飞书为例：填 App ID / App Secret，然后选择长连接模式（无需公网 IP，适合本地）或事件回调模式（需公网 HTTPS 地址和签名校验）。配置好后在飞书发消息，Agent 在服务器上执行并返回结果。
怎么给 Octop 写一个自定义插件？
插件是一个目录，包含 plugin.yaml（定义 id、version、kind、entry 等）和 main.py（必须定义 setup(ctx)）。kind 可选 tool/skill/hook。以字数统计插件为例：在 main.py 中定义异步函数 count_text，在 setup 中调用 ctx.tool 注册。函数签名和 docstring 会自动生成工具 schema。打包成 zip 后执行 octop plugin install 安装，再调用 reload 接口加载，最后在「个性化 → 插件」中按专家启用。
Octop 的定时任务怎么用？失败时先检查什么？
在「自动化」里按 cron 挂任务，也可用 octop cron 命令行管理。定时任务触发的是一个 Agent 的一次完整回合，因此该 Agent 必须有模型、有权限，且工作区脚本存在。任务失败时先检查这三样，比看日志更快。
Octop 自托管时有哪些安全风险需要注意？
五条红线：1) 供应商 API Key 对任何登录用户明文返回，需脱敏或存环境变量；2) 文件浏览默认从 / 开始，终端使用同一 OS 用户，多人场景应设 workspace_root_dir 或容器化；3) token_quota 和 max_agents 默认不限，开号时务必设置；4) 监听 0.0.0.0 时同网段可访问，公网使用需加 HTTPS 反代和强口令；5) 插件是进程内 Python 代码，无沙箱，只安装信任的插件。
