简体中文 · English

面向 AI 编程与桌面工作流的开放硬件入口

官方硬件 · 桌面客户端 · Developer Kit · Awesome AhaKey · 社区共创

AhaKey 是一个面向 AI 编程与桌面工作流的开放硬件项目。

我们希望把键盘、语音输入、AI coding agent、桌面状态反馈和社区 workflow 连接起来，让开发者可以更自然地控制 Claude、Cursor、Codex 等 AI 编程工具。

AhaKey 不是只卖一个键盘，而是希望长期建设：

硬件入口
→ 官方桌面客户端
→ AhaKey Developer Kit
→ 第三方客户端 / SDK 二创 / 自定义 HEX
→ Awesome AhaKey 社区项目
→ 更深度的产品共创与路线图反馈

AhaKey 采用 “开源客户端 + AhaKey Developer Kit + Awesome AhaKey 社区共创 + 受控生产级资料” 的分层开放机制。

我们默认开放：

• 官方桌面客户端源码
• BLE 协议文档
• AhaKey X1 硬件 SDK
• 按键、拨杆、灯光、OLED 等开发接口
• examples 示例项目
• 自定义 HEX 构建和烧录参考
• Awesome AhaKey / 社区项目展示入口
• 第三方客户端、脚本、workflow、教程和 SDK demo 共创入口

普通开发者需要开发客户端、workflow、按键玩法、拨杆逻辑、灯效、OLED 显示或自定义 HEX 时，应优先查看 AhaKey Developer Kit：

👉 protocol

社区独立项目、教程、workflow、SDK demo、自定义 HEX 玩法展示，默认提交到 Awesome AhaKey：

👉 awesome-ahakey

如果你希望进一步参与固件代码完善、硬件产品技术开发、底层调试、生产级资料评估或更深度的产品共创，可以提交：

👉 Hardware Source Access Program

PCB layout、Gerber、BOM、生产测试资料、供应链资料、完整官方固件源码等生产级资料不默认通过公开仓库开放。确有深度合作、生产级调试或特殊研究需求时，请通过表单或官方联系方式进一步沟通。

AhaKey 尊重用户对自己设备的本地控制权。 我们不会故意通过远程认证、云端锁定或固件更新，破坏已公开协议和 SDK 下的合理本地开发、第三方客户端使用和自定义玩法探索。

进入 desktop/releases
→ 下载最新版本
→ 安装桌面客户端
→ 连接 AhaKey
→ 开始使用

入口：desktop/releases

进入 protocol
→ 阅读 BLE 协议和通信文档
→ 参考 examples
→ 创建自己的 repo
→ 做出 demo
→ 提交到 awesome-ahakey

适合：

• 自己写 macOS / Windows 客户端
• 做 Cursor / Claude / Codex 工作流工具
• 做快捷键脚本
• 做状态同步工具
• 做自动化集成

入口：protocol

进入 protocol
→ 阅读 AhaKey Developer Kit README
→ 查看 sdk/README.md
→ 选择 buttons / toggle / lights / display 等模块
→ 参考 examples
→ 构建自己的 HEX
→ 本地烧录到正版 AhaKey X1 硬件

适合：

• 改四个按键行为
• 改拨杆逻辑
• 改灯光效果
• 改 OLED 显示
• 做自己的 AI 编程状态反馈
• 构建自定义开发者固件

入口：protocol

用户自己构建的 HEX 是自定义开发者固件，不等同于 AhaKey 官方固件。 请不要将自定义 HEX 描述为官方固件，也不要冒充官方发布版本。

进入 desktop
→ 阅读 README
→ Fork 仓库
→ 修改代码
→ 本地测试
→ 提交 Pull Request

适合：

• 修 bug
• 改 UI
• 优化安装体验
• 增加 macOS / Windows 适配
• 改进官方默认体验
• 改进桌面端与设备通信逻辑

入口：desktop

进入 awesome-ahakey
→ 按模板提交项目
→ 社区收录
→ 让更多用户看到、学习和 Fork

适合：

• 第三方客户端
• 工具脚本
• 使用教程
• 工作流 preset
• SDK demo
• 自定义 HEX 玩法展示
• 按键、拨杆、灯光、OLED 二创
• 桌面 setup 展示
• 视频 / 图文教程
• 非敏感硬件二创，例如外壳、键帽、支架、桌面 setup

入口：awesome-ahakey

进入 firmware
→ 查看 release notes
→ 阅读升级说明
→ 确认设备兼容性
→ 按官方说明升级

适合：

• 查看官方固件版本
• 查看升级说明
• 查看兼容性记录
• 查看官方确认过的固件说明

入口：firmware

进入 Hardware Source Access Program
→ 填写你的基本信息、GitHub 用户名和想参与的方向
→ 说明你希望完善的固件代码、硬件技术问题或共创内容
→ AhaKey 团队评估用途和匹配度
→ 如果适合，我们会进一步联系你

适合：

• 一起完善固件代码
• 补足硬件产品技术开发不足的地方
• 参与底层问题排查
• 参与硬件 / 固件技术共创
• 参与新硬件 / 新软件方向的技术讨论
• 需要更深度资料或生产级调试合作

入口：Hardware Source Access Program

简单理解：

不确定 → 先 Discussion
明确问题 → 提 Issue
客户端 / 文档 / SDK 已改好 → 提 Pull Request
做了独立项目、workflow 或 SDK demo → 提到 awesome-ahakey
需要官方固件版本和升级说明 → 看 firmware
想参与固件 / 硬件深度共创 → 提交 Hardware Source Access Program
生产级资料或特殊合作 → 联系官方

这些文件不是新的用户入口，而是 AhaKey 社区的基础维护规则。 普通用户不需要一开始全部阅读；当你准备提 Issue、PR、报告安全问题或参与社区协作时，再查看对应文档即可。

你可以贡献：

• bug report
• 文档修正
• 安装教程
• macOS / Windows 客户端改进
• BLE 协议反馈
• SDK 使用反馈
• examples 改进
• 构建脚本改进
• 第三方客户端
• workflow / preset / 脚本
• SDK demo
• 自定义 HEX 玩法展示
• 按键、拨杆、灯光、OLED 二创
• 使用视频、截图、教程
• 非敏感硬件二创展示
• 固件 / 硬件技术共创建议

建议尽量保持：

• 小步提交
• 说明清楚
• 有截图 / 日志 / demo 更好
• 不提交密钥、token、私人文件
• 不提交无关二进制文件、安装包或编译产物
• 大功能先 Discussion，再 PR
• 不提交官方完整固件源码、PCB、Gerber、BOM、生产测试资料或供应链资料
• 涉及生产级资料、底层调试或特殊深度合作时，先提交 Hardware Source Access Program 表单

需要了解 AhaKey、下载软件、购买设备、加入讨论或联系官方，可以从下面这些入口开始。

扫码加入中文社群 / 联系客服

微信公众号	微信讨论群	QQ 讨论群
关注公众号	加入微信讨论群	加入 QQ 讨论群
小红书群	企业微信客服	更多入口
加入小红书群	联系专人客服	ahakey.com 官网与下载入口

↑ Back to top

An open hardware entry point for AI coding and desktop workflows

Official Hardware · Desktop Client · Developer Kit · Awesome AhaKey · Community Collaboration

AhaKey is an open hardware project for AI coding and desktop workflows.

We connect keyboards, voice input, AI coding agents, desktop status feedback, and community workflows, so developers can control Claude, Cursor, Codex, and similar tools more naturally.

AhaKey is not just a keyboard. We are building:

Hardware entry point
→ Official desktop client
→ AhaKey Developer Kit
→ Third-party clients / SDK remixes / custom HEX
→ Awesome AhaKey community projects
→ Deeper product collaboration and roadmap feedback

AhaKey follows a layered openness model: open-source client + AhaKey Developer Kit + Awesome AhaKey community collaboration + controlled production-grade materials.

We open the following by default:

• official desktop client source code
• BLE protocol documentation
• AhaKey X1 Hardware SDK
• button, toggle, light, and OLED development APIs
• example projects
• custom HEX build and flashing references
• Awesome AhaKey community showcase
• third-party client, script, workflow, tutorial, and SDK demo collaboration entry points

Developers building clients, workflows, button behavior, toggle logic, light effects, OLED display logic, or custom HEX files should start with AhaKey Developer Kit:

👉 protocol

Independent community projects, tutorials, workflows, SDK demos, and custom HEX showcases should be submitted to Awesome AhaKey by default:

👉 awesome-ahakey

If you want to help improve firmware code, fill technical gaps in hardware product development, join deeper debugging, or explore deeper product collaboration, you can submit:

👉 Hardware Source Access Program

PCB layout, Gerber, BOM, production test materials, supply-chain materials, and the full official firmware source are not provided through public repositories by default. For deep collaboration, production-level debugging, or special research needs, please contact AhaKey directly.

AhaKey respects users' local control over their own devices. We will not intentionally use remote authentication, cloud lock-in, or firmware updates to break reasonable local development, third-party clients, or custom experiments built on published protocols and SDKs.

Go to desktop/releases
→ Download the latest version
→ Install the desktop client
→ Connect AhaKey
→ Start using it

Entry: desktop/releases

Go to protocol
→ Read BLE protocol and communication docs
→ Check examples
→ Create your own repo
→ Build a demo
→ Submit it to awesome-ahakey

Best for:

• macOS / Windows third-party clients
• Cursor / Claude / Codex workflow tools
• shortcut scripts
• status sync tools
• automation integrations

Entry: protocol

Go to protocol
→ Read the AhaKey Developer Kit README
→ Check sdk/README.md
→ Choose buttons / toggle / lights / display modules
→ Check examples
→ Build your own HEX
→ Flash it locally to genuine AhaKey X1 hardware

Best for:

• changing four-button behavior
• changing toggle logic
• changing light effects
• changing OLED display
• building your own AI coding status feedback
• building custom developer firmware

Entry: protocol

User-built HEX files are custom developer firmware and are not official AhaKey firmware. Please do not describe custom HEX files as official firmware or use them to impersonate official releases.

Go to desktop
→ Read the README
→ Fork the repository
→ Modify the code
→ Test locally
→ Submit a Pull Request

Best for:

• bug fixes
• UI improvements
• installation improvements
• macOS / Windows support
• official default experience improvements
• desktop-to-device communication improvements

Entry: desktop

Go to awesome-ahakey
→ Submit your project with the template
→ Get listed by the community
→ Help more users discover, learn from, and fork it

Best for:

• third-party clients
• utility scripts
• tutorials
• workflow presets
• SDK demos
• custom HEX showcases
• button, toggle, light, and OLED remixes
• desk setup showcases
• video / written guides
• non-sensitive hardware remixes such as cases, keycaps, stands, and desk setups

Entry: awesome-ahakey

Go to firmware
→ Read release notes
→ Check update instructions
→ Confirm device compatibility
→ Update according to official docs

Best for:

• checking official firmware versions
• reading update instructions
• checking compatibility notes
• reading official firmware documentation

Entry: firmware

Go to Hardware Source Access Program
→ Fill in your basic information, GitHub username, and collaboration direction
→ Explain the firmware code, hardware technical gap, or product development issue you want to help with
→ AhaKey team reviews the purpose and fit
→ If it fits, we will contact you for the next step

Best for:

• helping improve firmware code
• filling technical gaps in hardware product development
• joining low-level issue debugging
• joining firmware / hardware technical collaboration
• joining early technical discussions for new hardware or software directions
• deeper materials or production-level debugging collaboration

Entry: Hardware Source Access Program

Simple rule:

Not sure → Discussion
Clear problem → Issue
Client / docs / SDK already changed → Pull Request
Built an independent project, workflow, or SDK demo → awesome-ahakey
Need official firmware versions or update notes → firmware
Want deeper firmware / hardware collaboration → submit Hardware Source Access Program
Production-grade materials or special collaboration → contact AhaKey

These files are not extra entry points for new users. They are the basic rules and support files that help keep the AhaKey community maintainable.

You can contribute:

• bug reports
• documentation improvements
• installation guides
• macOS / Windows client improvements
• BLE protocol feedback
• SDK usage feedback
• example improvements
• build script improvements
• third-party clients
• workflows / presets / scripts
• SDK demos
• custom HEX showcases
• button, toggle, light, and OLED remixes
• videos, screenshots, and tutorials
• non-sensitive hardware remix showcases
• firmware / hardware technical collaboration suggestions

Please try to keep contributions:

• small and reviewable
• clearly explained
• accompanied by screenshots / logs / demos when helpful
• free of secrets, tokens, or personal files
• free of unrelated binaries, installers, or build artifacts
• discussed first if the feature is large
• free of the full official firmware source, PCB, Gerber, BOM, production test materials, or supply-chain materials
• submitted through Hardware Source Access Program first when production-grade materials, low-level debugging, or special collaboration is involved

To learn about AhaKey, download software, buy the device, join discussions, or contact the team, start here.

Chinese community QR codes / support contact

WeChat Official Account	WeChat Group	QQ Group
Follow us	Join WeChat group	Join QQ group
Xiaohongshu Group	WeCom Support	More
Join Xiaohongshu group	Contact support	ahakey.com Website and downloads

↑ Back to top