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/docs交互文档页面返回 404。

开启 Octop API 文档：从 404 到拿到有效 token

交互文档默认是关闭的，访问/api/docs或/api/openapi.json都会得到 404。这么设计的原因很直接：防止公网暴露接口结构。开启有两种方式，任选其一：

{ "enable_api_docs": true }

在~/.octop/config.json中加一行，或者用环境变量（优先级高于配置文件）：

export OCTOP_ENABLE_API_DOCS=1

改完重启服务。Octop 默认监听127.0.0.1:8088，浏览器访问http://127.0.0.1:8088/api/docs就能看到 Scalar 页面。

接着拿 token，用账号密码登录：

curl -s http://127.0.0.1:8088/api/auth/login \ -H 'Content-Type: application/json' \ -d '{"username":"admin","password":"your-password"}'

响应里有access_token和token_type: "Bearer"。之后每次请求带上Authorization: Bearer <access_token>请求头即可。

💡 登录返回 503 且内容为{"setup_required": true}，说明初始安装向导还没走完，先完成管理员创建再回来调接口。

Octop 接口鉴权：token 过期为什么不用重登

token 是JWT（JSON Web Token），默认有效期 86400 秒，即 24 小时。关键在滑动续期机制：只要某次请求的剩余有效期低于总时长的三分之一，响应头X-Octop-Access-Token里就会附带一个新 token，客户端应当替换保存。脚本只要在每次响应里检查这个头，一次登录就能长期在线，长任务中途不会突然掉线。

除豁免清单外，所有/api/*路由都走 JWT 中间件拦截。不需要令牌的路径包括：

• 文档与健康检查：/api/docs、/api/openapi.json、/api/health
• 登录与 SSO：/api/auth/login、/api/auth/captcha、/api/auth/oidc/*、/api/auth/oauth/*、/api/auth/ldap/status
• 安装向导：/api/setup/全系列
• 邀请码：/api/auth/invite/validate与/api/auth/invite/redeem
• 内部网关：/api/internal/mcp/*、/api/connectors/oauth/callback、/api/downloads/link/*（下载链接的 token 本身就是凭证）

Scalar 交互文档实战：逛页面、试跑与 WebSocket 特例

/api/docs的路由注册在应用工厂 src/octop/api/app.py 中，底层调用get_scalar_api_reference()渲染 OpenAPI 规范，和 FastAPI 默认的 Swagger UI 是两条渲染路径。

页面左右分栏：左边是业务标签树，右边是 "Try" 面板，填好参数点 Send，响应直接展示在页面上，所见即所得。标签共 35 组，覆盖全部核心能力，挑高频的几组看：

聊天走 WebSocket，是最容易踩的坑

实时对话轮次不走 REST，而是走WebSocket：WS /api/agents/{agent_id}/chat/ws?token=<jwt>。

注意 token 放在查询参数里，不在请求头——这是该接口最常见的坑，缺 token 时连接会直接关闭（close code 4001）。连上后发送一帧{"type": "user_turn", "text": "你的输入"}，就能收到流式回复。帧字段全集见 docs/api.md 的 "Chat (WebSocket)" 一节。

高频接口与背后的身份要求

权限分四级：public（免令牌）→user（登录即可）→owner（资源属主或管理员）→admin（管理员角色）。调接口前先在 Scalar 条目头部看一眼要求身份，拿到 403 时多半是身份问题，而不是参数缺失。一个容易忽略的细节：cron 接口是严格 owner，即使管理员查看他人的任务，拿到的也是空列表。

排错与生产建议：信封、错误码与 OpenAPI 导出

所有非 2xx 的 JSON 响应都是统一结构，message会按Accept-Language请求头本地化：

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

新手最常遇到的几个错误码：

• 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" 部分。

安全方面：文档页本身不含任何数据，但会暴露接口结构，建议在开发或内网环境开启，公网生产保持关闭。想把文档能力集成进自己的工具链，直接请求/api/openapi.json拿到 OpenAPI 3.1 规范，导入 Postman、YApi 等工具即可离线协作。

下一步建议：通读一遍 docs/api.md 的完整接口清单，配置项疑问查 docs/configuration.md。

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