Octop 自托管 AI 助手 API 文档实战指南:5 步从开启 /api/docs 到调通第一个接口

Octop 自托管 AI 助手 API 文档实战指南:5 步从开启 /api/docs 到调通第一个接口

【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop

Octop 是一个多用户、多智能体协作的自托管 AI 助手,全部后端能力挂在/api前缀下,官方自带/api/docs交互文档与在线调试页。本文从打开文档页讲起,覆盖 JWT 令牌获取与续期、分组导航、首次接口调通和错误码解读,读完你能独立跑通第一条 API 请求链路。

01 | 把文档页打开:默认关闭、两种开启方式与验证动作

/api/docs与/api/openapi.json出厂状态是关闭的,访问直接 404——生产环境少暴露一层能力面,这个取舍很合理。想打开它,只有两个开关,环境变量优先级高于配置文件:

开启方式写法生效条件
配置文件~/.octop/config.json中加"enable_api_docs": true重启服务
环境变量OCTOP_ENABLE_API_DOCS=1重启服务,优先覆盖配置
{ "enable_api_docs": true }

字段定义在 src/octop/config.py 的OctopConfig中,/api/docs路由本身注册在 src/octop/api/app.py,页面由 Scalar 渲染。

验证动作:重启后浏览器打开http://127.0.0.1:8088/api/docs(Octop 默认监听127.0.0.1:8088),看到左侧接口分组导航即算成功。

💡 小贴士:开启状态未走完首次安装向导时,/api/docs本身能打开,但调任何业务接口都会拿到 503 和{"setup_required": true}——先完成向导再调试。

02 | 拿到钥匙:令牌获取与续期三步走

  1. 登录换令牌:POST /api/auth/login提交username与password,响应里取access_token字段(启用强验证码时还要带上captcha_token)。
  2. 请求头携带:后续请求统一加Authorization: Bearer <access_token>;src/octop/api/middleware/jwt_auth.py 会对除白名单外的所有/api/*路由做拦截。
  3. 过期与自动续期:令牌 TTL 默认 86400 秒,由access_token_ttl_seconds控制。当剩余有效期不足三分之一时,认证响应会顺带一个X-Octop-Access-Token响应头,里面是新令牌——拿到就替换本地旧值,实现"一次登录长期在线"的滑动续期。
curl -s -X POST http://127.0.0.1:8088/api/auth/login \ -H "Content-Type: application/json" \ -d '{"username": "admin", "password": "你的密码"}'

以下端点免令牌,直接裸调:

  • /api/docs、/api/openapi.json、/api/health
  • /api/auth/login、/api/auth/captcha、SSO 系列/api/auth/oidc/*、/api/auth/oauth/*
  • 邀请码:/api/auth/invite/validate、/api/auth/invite/redeem;OAuth 回调/api/connectors/oauth/callback;内部网关/api/internal/mcp/*
  • 首次安装向导/api/setup/*

注意安装锁:首个管理员创建之前,src/octop/api/middleware/setup_lockdown.py 会对所有非公开/api接口一律回 503setup_required,等于强制你先走安装向导。

03 | 看懂左侧地图:40 多个标签的分组逻辑

文档页左侧 40 多个业务标签,不是拍脑袋起的,而是OPENAPI_TAGS配置逐条生成,定义在 src/octop/api/openapi_meta.py——分组有疑问直接翻这份源码对照。高频标签的能力边界:

标签管什么边界提醒
setup首次安装向导:建管理员、配模型只有初始安装阶段用得上
auth登录登出、当前用户资料与偏好免令牌入口也在这
agents智能体增删改查、启动/停止运行时运行时操作仅属主或管理员
providersLLM 供应商与模型选择、连通性测试删除前确认无智能体引用
cron挂在智能体上的定时 Promptowner only,跨属主查不到
browser远程浏览器会话、实时流、录放依赖宿主机浏览器环境

点标签 → 右侧看接口卡片 → 按卡片上的 Bearer 标识决定是否带令牌,导航就这三步。

04 | 登录到调通:一条请求链路完整走一遍

目的接口权限
探活GET /api/health公开
登录POST /api/auth/login公开
当前用户GET /api/auth/me用户
智能体列表GET /api/agents用户
启动智能体POST /api/agents/{id}/start属主
建定时任务POST /api/agents/{id}/cron属主

权限分四级递进:public → user → owner → admin。owner 指资源属主或管理员,例如 cron 接口即使管理员去看别人的任务也拿不到数据。文档页右侧接口卡片上的BearerAuth标识可以直接看出该接口属于哪一级。

在线调试演示两个高频动作。第一步,文档页找到POST /api/auth/login,填入username、password点发送,从响应 JSON 取出access_token;第二步,在请求设置里配置全局头:

Authorization: Bearer 刚才复制的令牌

再调GET /api/auth/me,返回{id, username, role, ...}即代表鉴权链路完全跑通。

实时对话不走 HTTP:连WS /api/agents/{agent_id}/chat/ws?token=<jwt>(JWT 放查询参数),发送{"type":"user_turn", ...}帧,服务端流式回 JSON 分片,直到done或error帧。

05 | 错误码怎么读:统一信封 + 5 个高频码

所有非 2xx 的 JSON 响应都是同一副信封,message会按Accept-Language本地化:

{ "error": { "code": "AGENT_NOT_FOUND", "message": "...", "details": {} } }

code与 src/octop/infra/errors.py 的ErrorCode枚举一一对应。新手最常撞上的五个:

codeHTTP处理建议
AUTH_FAILED/TOKEN_EXPIRED401重新走登录换新令牌
LOGIN_LOCKED429等login_lockout_seconds解锁,或请管理员调/api/users/{id}/unlock-login
SETUP_REQUIRED409初始管理员还没建,先完成安装向导
FORBIDDEN403令牌有效但角色不够,升 admin 或换属主账号
AGENT_NOT_FOUND404智能体不存在,或不属于当前用户

06 | 踩坑与生产建议:5 个高频问答

Q:公网开着文档页会泄密吗?文档页只暴露接口结构,不含任何业务数据;但它等于把系统能力边界摊开给扫描器。公网生产建议保持关闭,确实需要时让反向代理给/api/docs单独加一层基础认证。

Q:文档页打不开,怎么定位?先看返回码:404 说明enable_api_docs没开(改完记得重启);200 打开但业务接口全 503,是安装向导没走完。

Q:想把文档能力搬进 Postman 或 YApi?GET /api/openapi.json拉完整规范,导入即可离线维护集合。

Q:批量脚本总是令牌过期?在请求层加一行逻辑:每次响应检查X-Octop-Access-Token,存在就替换本地令牌——续期是服务端顺带完成的,别自己算时间。

Q:文档页和 Swagger 能共存吗?不用纠结。Octop 只保留 Scalar 这一套,/api/docs就是唯一入口。

这套"开页 → 拿令牌 → 看分组 → 调通首个接口 → 读懂错误 → 生产避坑"的闭环走完,Octop 的 HTTP API 就真正成了你的工具箱。想进一步挖接口细节,直接翻官方 docs/api.md 与 docs/configuration.md。

【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

ABS建模核心:滑移率物理本质与制动器动态建模

ABS建模核心:滑移率物理本质与制动器动态建模

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/11/18 18:30:16 阅读更多 →
盘点8款出圈国产AI芯片:从云端训练到端侧语音怎么选

盘点8款出圈国产AI芯片:从云端训练到端侧语音怎么选

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/11/18 20:47:34 阅读更多 →
深入parakeet-redux架构:从24层TDT编码器到解码器的设计细节

深入parakeet-redux架构:从24层TDT编码器到解码器的设计细节

人工智能语音模型量化模型压缩 【免费下载链接】parakeet-redux 项目地址&#xff1a; https://ai.gitcode.com/hf_mirrors/moondream/parakeet-redux 点击查看 免费下载 &#x1f99c; parakeet-redux 是一个 1.58 bit 三值量化的自动语音识别&#xff08;ASR&#xff09;模型…

2026/11/15 0:02:35 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年&#xff0c;我大部分时间都在跟浏览器标签页打交道&#xff0c;直到第一次把桌面应用跑起来&#xff0c;才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词&#xff0c;最开始是在某段时间频繁出现在同事的讨论里&#xff0c;一个用HTML…

2026/11/18 13:59:04 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介&#xff1a;亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档&#xff0c;主要面向智能锁安装人员、终端用户及售后维护者&#xff0c;帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件&#xff0c;大小4.37MB&#xff0c;内容结构清晰&#xff…

2026/11/18 15:33:23 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统&#xff0c;整车要求空载跑到8m/s&#xff0c;电机转速已经拉到额定点&#xff0c;驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令&#xff0c;转速纹丝不动&#xff0c;三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/18 17:05:28 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年&#xff0c;用它写过嵌入式驱动、做过游戏服务端&#xff0c;也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词&#xff0c;我其实挺感慨的——这门语言的难点从来不是语法多&#xff0c;而是知识点之间的耦合太深…

2026/11/18 14:33:19 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介&#xff1a;亚太天能T109滑盖智能锁产品说明书以PDF格式发布&#xff0c;适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开&#xff0c;先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能&#xff0c;再给出完整安装步骤&…

2026/11/18 17:05:28 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历&#xff1a;翻开源码注释、论文摘要或者一份专业报告&#xff0c;每个字都认识&#xff0c;连在一起却像天书。想找人聊聊&#xff0c;身边要么没人懂&#xff0c;要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型&#xff0c;几秒钟之后&a…

2026/11/18 14:13:08 阅读更多 →

日新闻

周新闻

月新闻