Atlassian Teamwork Graph CLI 怎么接入 Codex？2026 教程

Codex CLI 开发者：需要让编码 Agent 查询 Jira、Confluence 等项目上下文。
平台工程师与企业管理员：需要确认身份、权限范围和撤销方式。
AI Coding 团队：准备把 Atlassian 工作资料接入编码流程，并验证执行环境。

最后更新于 2026 年 10 月 8 日；公告核对自 OpenAI 官方公告，接入细节以 Atlassian 官方文档和公开插件仓库为准。

1合作公告与现有 CLI 能力

OpenAI 于 2026 年 10 月 6 日宣布与 Atlassian 扩大合作，包括将 GPT‑6 系列模型引入 Atlassian 平台、通过 Teamwork Graph 相关插件让 Codex 用户获取项目上下文，以及探索更深入的 Jira 集成。公告中的“探索”不是已经开放的功能，不能据此认定自动派单、进度同步或结果审核已可使用。(合作公告)

接入前要分清四层：

• Teamwork Graph：关联人员、项目、文档和决策的工作上下文层。
• Teamwork Graph CLI：在终端执行查询或操作的命令行工具。
• Codex 插件与 skills：告诉 Agent 如何发现和使用 CLI 命令；它们不是 CLI 程序，也不是账号凭证。
• 身份与权限：决定当前用户能访问哪些站点和数据，由 Atlassian 账号及组织策略控制。

因此，合作公告不是 CLI 权限变更或组织授权的证明。安装状态、登录站点、可查询内容，都应分别按官方安装说明和管理员配置核实。

2安装前：确认运行环境与试点对象

官方安装说明列出 macOS（arm64 或 x64）、Linux（x64）和 Windows（arm64 或 x64）支持范围，并说明 CLI 二进制不需要额外安装 Node.js 等运行时。你还需要可用的 Codex 环境，以及对目标 Atlassian 产品有访问权限的账号；组织是否开放功能、站点是否已授权，不能自行假定。(Teamwork Graph CLI 安装说明)

先选一个可以人工对照的只读对象，例如一条你本来就能打开的 Jira 工单，或一篇已知的 Confluence 页面。记录站点、对象标识、预期可见内容，再选一个明确不应访问的对象。这样可以分别排查账号混用、站点选错、连接器未就绪和权限不足，而不必一开始就让 Agent 搜索整个项目。

还要提前检查执行环境：首次 OAuth 授权需要浏览器交互；如果 Agent 沙箱无法访问本机凭证、刷新凭证或连接网络，安装成功也不等于运行时查询可用。附件、白板等内容还可能受沙箱网络限制，遇到资料缺失时先查网络策略，不要让 Codex 根据残缺上下文补全结论。

3安装时：按顺序接好 CLI、插件和身份认证

macOS 和 Linux 的安装命令如下。执行前请重新核对官方安装说明；如果企业终端策略不允许运行远程安装脚本，应改用管理员批准的方式，而不是绕过软件管理要求。

bash <(curl -fsSL https://teamwork-graph.atlassian.com/cli/install)

然后按顺序完成：

1. 在终端运行安装程序，并在浏览器中登录 Atlassian；选择目标站点，检查授权请求后再确认。
2. 按公开插件仓库当前的 Codex 指引添加并安装 Teamwork Graph 插件。仓库提供插件与 Agent 使用说明，CLI 本身仍由安装程序安装。(公开插件仓库)
3. 在 Codex 中按插件指引运行 /twg-setup，完成设置和登录；不要把插件包当作 CLI 程序或凭证库。
4. 运行 twg doctor 检查基础配置。Codex 可从通用的 ~/.agents/skills 目录读取 skills；如需手动修复，再按官方 Agent skills 说明处理。
5. 先发起只读查询，要求 Codex 返回对象标识、站点和来源链接；核对无误后，再让 Agent 分析代码或提出修改计划。

这几个组件各有职责：插件负责为 Agent 提供使用指引，CLI 执行命令，OAuth 确定当前身份，组织权限限制可访问的数据。任何一环通过，都不代表其余环节已经通过。

4登录后：核对账号、权限与资料范围

Teamwork Graph CLI 使用 OAuth 2.1，并沿用当前 Atlassian 账号已有的数据权限；Bitbucket 命令需要单独配置 token。OAuth 访问令牌有效期为 8 小时，CLI 会在运行命令时刷新；连续 30 天未使用后，刷新令牌会过期，需要重新登录。若 Agent 沙箱无法完成刷新，计划任务和长时间运行任务都可能中断。(官方认证说明)

管理员可以控制 Read、Write and manage、Delete 权限类别。官方权限文档说明，若默认允许全部权限，之后新增的 CLI 权限也可能自动获准；只需要检索上下文的团队，应关闭默认全开并按需授权。权限变更时，可以选择保存并撤销活动会话，要求用户重新认证后再使用更新后的权限。(官方权限配置说明)

建议按以下顺序检查查询是否遵循预期权限：

• 查询一个当前账号可访问的工单，核对标识、站点和来源链接。
• 查询一篇你有权查看的文档，逐项对照 Codex 摘要中的关键决策。
• 查询一个明确无权访问的对象，确认受限内容没有返回；单纯“没有搜到”并不足以证明权限设置正确。
• 查看 Bitbucket 结果时，单独确认 token 配置状态；不要把令牌粘贴进提示词、对话或代码仓库。
• 如果刚撤销权限，确认活动会话已经处理，再让用户重新登录并重复正反向测试。

Teamwork Graph 的关联关系能帮助 Agent 找到上下文，但不会让用户自动成为其他项目的成员，也不能突破账号权限。组织的网络允许列表同样可能拦截请求；即使账号有权限，从不符合策略的来源发起查询仍可能失败。

5FAQ：在终端与其他 Agent 宿主间选择

Codex 中的 CLI、插件和 skills 如何完成配置？

先按官方安装说明安装 CLI 并完成登录，再根据公开插件仓库的 Codex 指引安装插件，最后运行 /twg-setup 并检查 twg doctor 结果。CLI、插件和 skills 分别承担命令执行、Agent 指引和命令发现职责；它们都不会自动授予 Atlassian 数据权限。接入后应先用只读请求验证来源，再开放后续操作。

接入后可能查到哪些 Atlassian 内容？

可查询范围取决于 CLI 支持的命令、组织启用的产品与连接器、账号权限和管理员设置。Jira、Confluence、Bitbucket 等资料可能在范围内，但不能推断每个站点都开放相同内容。先用一条已知工单或文档核对对象标识和来源，再按实际命令覆盖范围逐步扩展。

Codex 的本机终端工作流应该用 CLI 还是 MCP？

如果 Agent 在终端运行，需要串联本地仓库、命令或脚本，优先评估 CLI；如果运行于网页、IDE 或无法可靠运行二进制的沙箱，MCP 可能更适合。两种方式面向不同宿主与认证流程，并非权限绕过手段；选择前应在目标环境中核实命令覆盖、认证要求与组织策略。(官方 CLI 与 MCP 选型指南)

怎样验证 Codex 沿用 Atlassian 账号的权限？

用一个当前账号可访问的对象和一个明确受限的对象做正反向测试，检查对象标识、来源、返回字段和拒绝结果，再与网页端账号及管理员设置对照。权限由 Atlassian 服务端执行；撤销会话后，用户需要重新登录。还要人工检查 Agent 是否准确引用来源、是否把“没有搜到”误写成“不存在”，以及输出是否包含不应传播的信息。

6首个编码任务：把上下文核验与交付验收分开

只读查询通过后，再选择低风险代码任务，例如根据已确认的需求列出受影响文件并生成修改计划。要求 Codex 把实现假设关联到具体工单、文档或代码协作资料；由你逐项核对后，再决定是否允许它修改工作区。

把结果拆成四个检查点，避免将“Agent 能回答”当成任务完成：

• 资料检索：工单、决策、PR 或文档确实存在，站点与权限正确。
• 代码修改：检查工作区差异，确认变更范围与需求一致。
• 测试执行：记录实际运行的命令和结果；没有运行测试，就不能表述为测试通过。
• 交付验收：按团队流程完成人工审查、CI 或构建验证；CLI 接通只证明上下文通路可用。

若仓库属于 iOS 或 macOS 项目，还要确认是否需要真实 macOS 与 Xcode 环境。查到需求、生成 Swift 代码或修改工程文件，都不等于完成 Apple 平台构建、签名和运行验证。你可以接着阅读Agent 执行环境与权限验收指南；如果任务需要远程执行，再查看远程环境使用说明，但不要把 Teamwork Graph CLI 误认为必须运行在云端 Mac。

7接入验收清单

• [ ] 已按官方说明核对支持环境与当前安装方式。
• [ ] CLI、Codex 插件、skills 和身份认证分别完成，没有把某一步当成其他步骤的替代品。
• [ ] twg doctor 检查通过，且只读查询的对象标识、站点和来源均可复核。
• [ ] 管理员确认只开放任务所需的权限类别，没有因方便而默认开放写入和删除。
• [ ] 一个可访问对象和一个受限对象都完成正反向权限测试。
• [ ] Bitbucket token 单独管理，没有进入对话或代码仓库。
• [ ] 代码修改、测试、构建和交付审查分别留有证据；Apple 平台项目已明确 Xcode 要求。
• [ ] 沙箱或远程环境已验证网络访问、凭证刷新和撤权后的重新登录流程。

如果你已有可交互的本机 Codex 环境，先在本地完成只读试点通常更直接；但把 CLI 放进团队共用主机或无人值守任务后，还要处理凭证保管、会话撤销、网络限制和中断恢复。若当前环境难以安全承载长任务，或项目确实需要持续远程执行与 Apple 工具链交付，租赁 Mac 可以作为补充，但它不会替你完成 Atlassian 授权，也不是每个接入场景的必要条件。对于长期稳定的高负载任务、必须连接专用物理设备的工作，或已有合规本地设备的团队，继续使用自有环境可能更合适；只有临时测试、隔离执行或远程交付需求明确时，再评估租赁 Mac。