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_DOCS1改完重启服务。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 是JWTJSON 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 组覆盖全部核心能力挑高频的几组看标签覆盖能力setup安装向导、管理员创建auth/users登录、当前用户、用户管理agents/chat智能体增删改查、会话、轨迹providers/voice模型供应商、语音识别合成channels/cronIM 渠道桥接、定时任务skills/subagents技能市场、子智能体workspace工作区文件操作admin/security/tls审计日志、安全策略、证书browser/terminal/desktop远程浏览器、终端、桌面聊天走 WebSocket是最容易踩的坑实时对话轮次不走 REST而是走WebSocketWS /api/agents/{agent_id}/chat/ws?tokenjwt。注意 token 放在查询参数里不在请求头——这是该接口最常见的坑缺 token 时连接会直接关闭close code 4001。连上后发送一帧{type: user_turn, text: 你的输入}就能收到流式回复。帧字段全集见 docs/api.md 的 Chat (WebSocket) 一节。高频接口与背后的身份要求目的接口要求身份健康检查GET /api/healthpublic登录POST /api/auth/loginpublic当前用户GET /api/auth/meuser智能体列表GET /api/agentsuser创建智能体POST /api/agentsuser启动/停止POST /api/agents/{id}/startowner自定义供应商POST /api/providersuser测试连通性POST /api/providers/{id}/testuser定时任务POST /api/agents/{id}/cronowner权限分四级public免令牌→user登录即可→owner资源属主或管理员→admin管理员角色。调接口前先在 Scalar 条目头部看一眼要求身份拿到 403 时多半是身份问题而不是参数缺失。一个容易忽略的细节cron 接口是严格 owner即使管理员查看他人的任务拿到的也是空列表。排错与生产建议信封、错误码与 OpenAPI 导出所有非 2xx 的 JSON 响应都是统一结构message会按Accept-Language请求头本地化{ error: { code: AGENT_NOT_FOUND, message: ..., details: {} } }新手最常遇到的几个错误码AUTH_FAILED/TOKEN_EXPIRED401令牌错误或已过期重新登录SETUP_REQUIRED409初始管理员尚未创建LOGIN_LOCKED423登录失败次数过多等待自动解锁或让管理员调用/api/users/{id}/unlock-loginAGENT_NOT_FOUND404智能体不存在或属于其他用户。完整对照表在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考