Octop 交互式 API 文档 5 步上手教程：从开启 /api/docs 到调通第一个接口

Octop 交互式 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 文档、打开 /api/docs 页面、用 JWT 鉴权拿到凭据、动手调几个接口、看懂错误码，最后讲生产收尾。

🔧 第一步：用环境变量或配置文件开启 Octop API 文档

Octop 的 HTTP 接口全部挂在/api前缀下。其中/api/docs是打开浏览器就能看、能直接发请求的文档页，在 src/octop/api/app.py 的应用工厂里注册；/api/openapi.json是同一份 OpenAPI 规范的原始文件——OpenAPI 简单说就是一份给机器读的接口清单，把每个路径、参数、响应都写清楚，能直接导入 Postman、YApi 这类工具里离线使用。

这两个入口默认都是关的，没开时访问直接 404。这是刻意设计：免得公网环境被人一把扫出系统能力。打开方式二选一，改完都必须重启服务才生效：

方式一，写进配置文件~/.octop/config.json：

{ "enable_api_docs": true }

方式二，用环境变量，优先级更高：

export OCTOP_ENABLE_API_DOCS=1

字段定义在src/octop/config.py的OctopConfig里，默认值enable_api_docs: bool = False。Octop 默认监听127.0.0.1:8088，重启后浏览器访问http://127.0.0.1:8088/api/docs，看到左侧按业务分组的接口树就算成功了。渲染页面的 Scalar 是个网页版文档工具，比传统 Swagger 更照顾新手：左边分组、右边表单，填完参数点发送，响应立刻可见。

常见坑位：改完配置忘了重启，或端口根本不是 8088，都会让你对着一个 404 发呆。先curl http://127.0.0.1:8088/api/health确认服务还活着，再回头查开关。

🔑 第二步：登录后拿到 JWT 的三步操作，含滑动续期

文档页里几乎所有接口都挂着 BearerAuth 标识。JWT（JSON Web Token）说白了就是登录成功后服务器发给你的一张"门卡"：之后每个请求带上它，服务端才知道你是谁。

拿门卡分三步：调POST /api/auth/login提交用户名密码，从响应里取access_token；之后每个请求加上请求头Authorization: Bearer <access_token>；令牌默认 24 小时过期，由access_token_ttl_seconds控制。

用 curl 走一遍：

curl -s -X POST http://127.0.0.1:8088/api/auth/login \ -H 'Content-Type: application/json' \ -d '{"username": "admin", "password": "<你的密码>"}' # 从返回里取 access_token，再调任意受保护接口： curl -s http://127.0.0.1:8088/api/auth/me \ -H 'Authorization: Bearer <access_token>'

还有一组接口根本不用门卡：/api/docs、/api/openapi.json、/api/health、/api/setup/*安装向导、登录与 SSO 相关端点、邀请码验证与兑换、连接器 OAuth 回调、/api/internal/mcp/*内部网关——全部免令牌。

值得花两分钟搞懂的是滑动续期。JWT 中间件（src/octop/api/middleware/jwt_auth.py）会盯着令牌剩余寿命：当它跌破总时长的 1/3，响应就会带上X-Octop-Access-Token头，值是一张新令牌。自己写客户端的话，每个响应都查一眼这个头，有就替换本地存的令牌——一次登录长期在线，不会被过期踢下线。

常见坑位：全新实例还没创建第一个管理员时，除/api/setup/*外的/api路径一律返回503 {"setup_required": true}。这是 setup 锁定逻辑，先走完安装向导，登录接口才真正可用。

🧪 第三步：在 Scalar 里调通接口：从健康检查到定时任务

拿到令牌后，建议按这条链路把最常用的接口串一遍，权限列能一眼看出你此刻能干什么：

权限一共四级，文档里一眼可辨：public（免令牌）→ user（任意登录用户）→ owner（资源属主或管理员）→ admin（管理员角色）。盯住表里 cron 那一行：定时任务接口是 owner 专属，管理员去查别人的任务也会拿到空列表。

Scalar 左侧的分组来自 OpenAPI tags 配置：setup 安装向导、auth 用户管理、agents 与 chat、providers 与 voice 本地模型、channels 消息渠道、skills 与 subagents、admin 安全、browser 远程浏览器、terminal 与 desktop 桌面终端——看分组名基本能猜到里面有什么，用到哪块再展开哪块。

唯一不能用 HTTP 试的接口：WebSocket 聊天

普通一问一答的接口，文档页在线调试就够；实时对话不是——它是一条长连接，发一条、流式回一串。所以聊天专门走了 WebSocket（一种浏览器和服务端随时互相说话的通道）：

WS /agents/{agent_id}/chat/ws?token=<jwt>

注意令牌这里放查询参数而不是请求头，是整套 API 里唯一的例外。连上后发送{"type":"user_turn", ...}帧，就能收到流式回复，直到{"type":"done"}或{"type":"error","message":"..."}收尾，帧格式细节见 docs/api.md 的 Chat (WebSocket) 一节。

🚨 第四步：看懂错误信封，按 code 修复问题

所有非 2xx 的 JSON 响应都套同一个信封（由 src/octop/infra/errors.py 渲染，还会按Accept-Language翻译成你的语言）：

{ "error": { "code": "AGENT_NOT_FOUND", "message": "智能体不存在或不属于你", "details": {} } }

排错先看code，HTTP 状态码只告诉你问题大类。最容易碰上的四个：

• AUTH_FAILED/TOKEN_EXPIRED（401）：令牌缺失、无效或过期，重新登录即可；
• SETUP_REQUIRED（409）：初始管理员还没建，先去走安装向导；
• LOGIN_LOCKED（423）：登录失败次数太多被锁，等自动解锁，或让管理员调/api/users/{id}/unlock-login；
• AGENT_NOT_FOUND（404）：智能体不存在——或者它不是你的，别人的智能体在你眼里就是"不存在"。

完整错误码对照在docs/api.md的 Error envelope 部分。遇到列表外的码，对照它的状态码和 message，一般也能猜个八九不离十。

✅ 第五步：生产环境收尾与上手前检查清单

文档页只暴露接口结构，不吐任何数据。开发机、内网、测试环境放心开着，自己和同事随查随调；实例一旦挂上公网，建议把开关关掉——留着它，等于把系统能力边界画给扫描器看，多此一举。

团队协作时另一个高频用法：GET /api/openapi.json拉完整规范，导进 Postman、YApi 做离线协作，不碰线上服务。

上手前检查清单

• 改过enable_api_docs之后重启过服务
• 安装向导已走完，/api/health正常返回
• 客户端会读X-Octop-Access-Token头做滑动续期，不是一到期就弹登录框
• 分清身份再调接口：user 能看列表，owner 才能 start/stop、管 cron
• 公网实例已关闭文档开关，只在内网保留

下一步建议：把 docs/configuration.md 翻一遍，把access_token_ttl_seconds这类跟运维习惯相关的字段调成想要的值，然后就可以放心写自己的集成脚本了。

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